valgebra-jsonschema
JSON Schema read into valgebra's sets, so a schema answers two questions: whether a value belongs, as the specification states it, and whether everything one schema admits another admits too.
📖 Documentation: https://ppigazzini.github.io/valgebra-jsonschema/
🤖 For AI assistants and coding agents: the documentation is also published as
llms.txt (a curated manifest)
and llms-full.txt (the
full text, including the API reference) per the llmstxt.org
convention.
from valgebra_jsonschema import compile_schema
# What an MCP server lists for a tool: its arguments, as JSON Schema.
tool = {
"name": "get_weather",
"inputSchema": {
"type": "object",
"properties": {
"location": {"type": "string", "minLength": 1},
"days": {"type": "number", "minimum": 1, "maximum": 7},
"units": {"enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
}
arguments = compile_schema(tool["inputSchema"])
assert arguments.is_valid({"location": "Paris", "days": 3})
assert not arguments.is_valid({"days": 3})
assert not arguments.is_valid({"location": "Paris", "days": 8})
# `1` and `1.0` are one JSON number, and `true` is none.
assert compile_schema({"type": "integer"}).is_valid(1.0)
assert not compile_schema({"type": "integer"}).is_valid(True)
# The next release of the tool takes another unit. Every call that was valid still is,
# and the converse fails: that is a compatible change, decided without running either.
wider = compile_schema(
{
"type": "object",
"properties": {
"location": {"type": "string", "minLength": 1},
"days": {"type": "number", "minimum": 1, "maximum": 7},
"units": {"enum": ["celsius", "fahrenheit", "kelvin"]},
},
"required": ["location"],
}
)
assert arguments.relation_to(wider) == "subset"
assert wider.relation_to(arguments) == "not_subset"
relation_to answers subset, not_subset or undecided. It is undecided where valgebra
can prove neither, which is never a wrong proof, and a keyword this package does not read raises
Unsupported naming it, since skipping one would admit values the schema refuses. A schema
that spells its values out, with const, enum, or an anyOf or oneOf of them, is related
by each value: constants(schema) lists them, and the schema lies inside another exactly
where is_valid admits each, a keyword valgebra reads as a predicate included.
The recipes do five tasks end to end: a model's tool call checked against the schema it was shown, a schema change checked before release, a schema split across documents, files checked against a schema, and what a schema asserts, keyword by keyword.
What it reads
Drafts 2020-12, 2019-09, 07, 06 and 04, all but the first through upgrade, and a document
naming any other dialect fails saying so, as the Model Context Protocol asks
(reading an MCP tool).
Patterns follow ECMA-262, as the specification requires, and numbers compare by value: 1 and
1.0 are one number, and true is none. format is an annotation, as 2020-12 makes it, and
assert_format=True reads nine of them as assertions. A $ref resolves against the base URI it
sits under, within the document or to one passed in documents={uri: document}; nothing is
fetched.
The compiler page says how each keyword becomes a set, and
the conformance page holds the inventory and the ledger of
differences.
Measured
uv run python tools/suite.py --check docs/studies/json-schema-test-suite.json
uv run python tools/corpus.py --check docs/studies/jsonschemabench.json
uv run python tools/containment.py --check docs/studies/containment.json
- Against the official JSON-Schema-Test-Suite: draft 2020-12 with the four optional files on regular expressions and large numbers, 1393 of the 1393 cases it runs; draft 2019-09, 1256 of 1256; draft-07, 929 of 929; draft-06, 841 of 841; draft-04, 618 of 618. Skipped: the five cases naming a custom meta-schema as their dialect.
- Real-world schemas (JSONSchemaBench, 9558 schemas from GitHub, the JSON Schema Store,
Kubernetes and function-calling data): 9486 compile, none crashes; membership differs from the
jsonschemapackage's on 13 of 404720 values, each a reading the ledger records. - Inclusions (the JSON Schema containment test suite, 10890 labeled questions): 7048 proven, 6 against a label, each a wrong label; each of the 342 refutations against a label is a wrong label, which the results page names.
Install
On Python 3.11 or later, from PyPI, with valgebra, a Rust extension published as wheels:
pip install valgebra-jsonschema
License
MIT or Apache-2.0, at your option.
Metadata
Release files for valgebra-jsonschema 0.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| valgebra_jsonschema-0.0.2.tar.gz | 234.7 kB | With provenance | Details for valgebra_jsonschema-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| valgebra_jsonschema-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for valgebra_jsonschema-0.0.2-py3-none-any.whl |
Total release size: 291.0 kB
Release files / valgebra_jsonschema-0.0.2.tar.gz
| Download URL | valgebra_jsonschema-0.0.2.tar.gz |
|---|---|
| Size | 234.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21eacc4eed26c6775fab58c67e011d07beba79c9b29c0d4a41d477e73189cb6d
|
|
BLAKE2b-256 checksum How to use checksums |
7850db0de63cf98b54b2cdfa95d62685c1fbbd6a4c3d33c5a77963ff147c7584
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / valgebra_jsonschema-0.0.2-py3-none-any.whl
| Download URL | valgebra_jsonschema-0.0.2-py3-none-any.whl |
|---|---|
| Size | 56.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3cd928ca63efd46a23c7deb10ee6651e00ef85eaeba508bf725536b37aea6dbb
|
|
BLAKE2b-256 checksum How to use checksums |
46826b616e65f4cd312b7a35b481dfd3f1bc3cb7e3413bf8cfc988e0ceabf41a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for valgebra-jsonschema 0.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for valgebra_jsonschema-0.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.