# JSON input

A compiled validator validates JSON source directly, parsing on the Rust path:

```
from valgebra import Validator

users = Validator({"name": str, "age?": int})

users.validate_json('{"name": "Ada", "age": 36}')  # passes, returns None
assert users.is_valid_json('{"name": "Ada"}')  # optional key absent
assert not users.is_valid_json('{"name": 5}')  # name is not a str

# bytes input is accepted too
assert Validator(list[int]).is_valid_json(b"[1, 2, 3]")
```

`validate_json(data, /, *, fail_fast=False)` mirrors `validate`: it raises `ValidationError` on failure and aggregates every independent failure by default. `is_valid_json(data)` mirrors `is_valid`: it returns a bool, and raises only where a comparison raises a fatal interpreter signal. Both accept a JSON `str` or `bytes`.

When you need the data, not just the verdict, `load` validates and **returns the parsed value**, so it is not parsed twice:

```
from valgebra import Validator

users = Validator({"name": str, "age?": int})
record = users.load('{"name": "Ada", "age": 36}')
assert record == {"name": "Ada", "age": 36}
```

`load(data, /, *, fail_fast=False)` raises `ValidationError` on malformed JSON or a non-member, exactly as `validate_json` does, and otherwise returns the parsed object.

## Same decisions as the object path

The JSON path parses the document and runs the **same** validation walk as it would against the equivalent native object. So validating a JSON document is exactly validating `json.loads` of that document — the same accept/reject decision, the same error codes, and the same paths:

```
import json

from valgebra import Validator

v = Validator(list[dict[str, int]])
doc = '[{"a": 1}, {"b": "x"}]'

assert v.is_valid_json(doc) == v.is_valid(json.loads(doc))
```

The two paths part only where the parser is stricter than `json.loads`. A `bytes` argument is read as UTF-8 alone, where `json.loads` detects a UTF-8 byte-order mark or a UTF-16 or UTF-32 encoding and decodes it (below). And four kinds of document are held to the JSON grammar or to the parser's limits: the non-standard float tokens (below), a document nested past the parser's recursion limit (below), an integer longer than the parser's digit limit once the interpreter's own limit is lifted (below), and an escape naming a **lone surrogate**. `"\ud800"` is a half of a pair that encodes no character, and the parser reports `json_invalid` where `json.loads` builds a `str` the object path admits.

```
import json

from valgebra import ValidationError, Validator

text = Validator(str)
assert text.is_valid(json.loads(r'"\ud800"'))  # the object path admits it
assert not text.is_valid_json(r'"\ud800"')  # the JSON grammar does not

raised = False
try:
    text.validate_json(r'"\ud800"')
except ValidationError as error:
    raised = True
    assert error.code == "json_invalid"
assert raised
```

This equivalence is locked by tests over a corpus spanning the JSON value model.

## JSON-to-Python value mapping

Parsing uses jiter (the parser pydantic-core uses) with the standard JSON model, so a document maps to Python values exactly as the standard library's `json` module produces them:

| JSON | Python | Matches schema |
| --- | --- | --- |
| `null` | `None` | `None` |
| `true` / `false` | `bool` | `bool` (and `int`, since `bool` is a subtype) |
| number, no fraction or exponent (`42`) | `int` | `int`, not `float` |
| number with fraction or exponent (`4.2`, `1e3`) | `float` | `float`, not `int` |
| string | `str` | `str` |
| array | `list` | `list[...]` and fixed lists; **not** `tuple[...]`, which is a different container |
| object | `dict` | records and mappings |

Two consequences follow from valgebra's value-set semantics:

```
from valgebra import Validator

# JSON 42 is an int, and float is disjoint from int, so it is not a float
assert not Validator(float).is_valid_json("42")
assert Validator(float).is_valid_json("42.0")

# JSON true is a bool, and bool is a subtype of int
assert Validator(int).is_valid_json("true")
```

`Infinity`, `-Infinity`, and `NaN` are not valid JSON. The parser rejects these tokens as malformed, even though Python's own `json.loads` accepts them as an extension. This is deliberately stricter: a document is held to the JSON grammar, so a float special can only enter through the object path (where `float('inf')` is an ordinary member), never through `validate_json`. A number too large for a machine integer still parses to a Python `int`, up to jiter's digit limit: 4300 digits in the jiter the lockfile pins, which is also the interpreter's default `sys.get_int_max_str_digits()`. Past it the parser reports `json_invalid` (`number out of range`) whatever the interpreter's limit is set to, where `json.loads` follows that setting. An overflowing float literal such as `1e400` is standard JSON and parses to `inf`.

```
from valgebra import Validator

is_float = Validator(float)
# The non-standard tokens are rejected, though json.loads would accept them.
assert not is_float.is_valid_json("Infinity")
assert not is_float.is_valid_json("NaN")
# The object path, in contrast, admits the corresponding float special.
assert is_float.is_valid(float("inf"))
# An overflowing literal is valid JSON and parses to infinity.
assert is_float.is_valid_json("1e400")
```

## The JSON values as a set

The values a document parses to are a set like any other, so you can write it, ask inside it, and have one number however it is written. [Several value universes](<https://ppigazzini.github.io/valgebra/explanation/universes/index.md#the-json-values>) does that, and reads TOML's the same way.

## Malformed JSON

Unparseable input never reaches the validation walk. `validate_json` reports it through the same structured error model as any other failure — a single `errors` item coded `json_invalid` carrying the parser's diagnostic — and `is_valid_json` treats it as a non-member:

```
from valgebra import ValidationError, Validator

v = Validator(int)
assert not v.is_valid_json("{ not json")

raised = False
try:
    v.validate_json("{ not json")
except ValidationError as err:
    raised = True
    assert err.code == "json_invalid"
assert raised
```

A non-`str`, non-`bytes` argument is a `TypeError` from `validate_json` and `load`, not a validation failure; `is_valid_json` answers `False` for it, as it does for anything that is not a document.

**A leading byte-order mark makes the input malformed.** RFC 8259 forbids a sender to add one and lets a parser ignore one rather than treat it as an error; jiter refuses it, so a document exported by a spreadsheet or written by a Windows editor is refused at column 1 with `json_invalid` — reading as an error about a character nobody can see. `json.loads` refuses one at the start of a `str` as well, and decodes it away from `bytes`, so on `bytes` the two paths part here. Strip it before validating:

```
from valgebra import Validator

v = Validator({"a": int})
carrying = '\ufeff{"a": 1}'
assert not v.is_valid_json(carrying)
assert v.is_valid_json(carrying.lstrip("\ufeff"))
```

**`bytes` are read as UTF-8.** A document encoded as UTF-16 or UTF-32 is malformed input, where `json.loads` detects the encoding and decodes it; decode such bytes to a `str` before validating.

**A document nested past the parser's own recursion limit is malformed input too**, not a deep document the walk then refuses: jiter stops at a couple of hundred levels of arrays and objects, and stops on both readings alike, so a document either is a document for both or is one for neither. `tests/test_json_semantics.py` holds the two to each other across that boundary rather than pinning where it falls, which is jiter's to move. A document inside the limit but deeper than the walk descends is a different refusal, reported by the walk's own depth guard.

## Performance

A document is parsed in Rust, and a parse that memory cannot be found for ends the process rather than raising `MemoryError`: bound a document's size before handing it over ([limits](<https://ppigazzini.github.io/valgebra/guides/limits/index.md#what-the-bounds-do-not-bound>)).

`is_valid_json` parses with jiter and validates the parsed JSON value **in place**: no intermediate Python objects are built for the structure it walks, so membership of a large array or a deep document is decided in Rust. A comparison against a Python object — a literal, a refinement predicate, or an instance or attribute check — is the documented step back into Python (detailed below). The same walk runs over either input source — a Python object or a JSON value — so the two paths stay equivalent. On the benchmark machine (AMD Ryzen 7 PRO 7840U, WSL2, CPython 3.15.2 built as the [performance page](<https://ppigazzini.github.io/valgebra/guides/performance/index.md>) records, the jiter the lockfile pins, the PGO release wheel — the same profile the release ships), per-call median on a passing document:

| Shape | `is_valid_json` | `json.loads` + `is_valid` | speedup |
| --- | --- | --- | --- |
| Record, 50 int fields | 1.27 us | 5.61 us | \~4.4x |
| List of 200 small mappings | 18.4 us | 30.4 us | \~1.7x |
| `list[int]`, 10,000 elements | 75 us | 449 us | \~6.0x |

`benches/bench_json.py` times both columns, and a strict `TypeAdapter.validate_json` over the same three shapes beside them; that third column is not recorded here, so read the comparison from the benchmark rather than from this page:

```
uv run --no-sync --group bench pytest benches/bench_json.py
```

`scripts/page_figures.py` re-reads this table and the one below with the performance page's figures, and the [performance page's method](<https://ppigazzini.github.io/valgebra/guides/performance/index.md#method>) says how to run it.

Avoiding materialization helps where the document is large or scalar-heavy: the 10,000-element array is six times faster than parse-then-validate, and the wide record a little over four. The middle row is the shape where it pays least, at under twice -- two hundred small mappings are two hundred container walks either way. Measure your own documents rather than reading a rule off these three.

Where the middle shape's time goes is measured, because it is the shape where valgebra is closest to pydantic-core. On the competitive gate's document -- two hundred records of five fields, one of them a list and one a mapping, 17 KB -- `is_valid_json` reads about 58 us on the machine above in the PGO wheel, and the parts are:

| part | per call | how it was measured |
| --- | --- | --- |
| the parse into the tree the walk reads, and the call | 47 us | `Validator(anything).is_valid_json`, which parses and admits without a walk |
| the walk over that tree | 11 us | `is_valid_json` less the row above |
| `jiter::JsonValue::parse` alone | 72 us | in Rust, release, no profile |
| jiter's pull parser over the same bytes, building nothing | 15 us | in Rust, release, no profile |

The first two rows are one process. The parse moves with the heap a process starts from, by as much as two fifths between processes of one build, and the walk does not: compare a parse figure only within one process. Read in one build, the tree costs nearly five times the parse that builds nothing: the cost is the tree's containers -- a vector per array and per object, each behind its own allocation -- and not the scanning. pydantic-core validates from the parser's events and builds no tree, and still takes longer than valgebra's whole call on this document -- the ratio is the `json_document` entry `scripts/compare_gate.py` records in `scripts/perf_compare.json` -- so the tree is most of valgebra's call and the call is the shorter.

Two readings would remove that cost, and the page states both as the limits they are.

**A tree of the walk's own** -- one fixed-size node per value in one vector, strings as ranges into one buffer -- pays no allocation per container and pays a push per *value* instead. It is a gain exactly while a document holds a container per few dozen scalars: this one holds one per four and parses **2.4x faster** that way, while an array of ten thousand bare numbers holds one per ten thousand and parses slower. A representation that wins the document and loses the array is a trade and not an improvement, so the reading in place is the one that never loses.

**A walk over the parser's events** is refused (`docs/dev/walk.md`): a union, a meet, a complement and a refinement read their value again, which a pull parser has moved past, and a stream answers differently from the tree on documents the tests hold. The document shape is a tree the walk reads once and drops.

Nodes that compare against a Python object — literals, refinements, instance and object checks, and predicates — materialize just the value at that node, since the comparison runs in Python. A length bound on an array or an object compares nothing, so it builds nothing: an array's items are counted, and an object's keys as the dict `json.loads` builds holds them, a repeated key once. `validate_json` and `load` materialize the whole document, since each hands back what a caller reads -- a report of Python-level value summaries, or the value itself; only `is_valid_json` is fully in place.
