Skip to content

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 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).

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 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 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.