Skip to main content

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 jsonschema package'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)

Source distribution for valgebra-jsonschema 0.0.2
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)

Table of built distributions (wheels) for valgebra-jsonschema 0.0.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page