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.

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.

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 (docs/05-mcp.md). 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. docs/02-compiler.md says how each keyword becomes a set, and docs/03-conformance.md 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 docs/04-results.md 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.1

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.1
File Size Uploaded Provenance Actions
valgebra_jsonschema-0.0.1.tar.gz 222.7 kB With provenance Details for valgebra_jsonschema-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valgebra-jsonschema 0.0.1
File Interpreter ABI Platform Actions
valgebra_jsonschema-0.0.1-py3-none-any.whl Python 3 none any Details for valgebra_jsonschema-0.0.1-py3-none-any.whl

Total release size: 278.6 kB

Release files / valgebra_jsonschema-0.0.1.tar.gz

Download URL valgebra_jsonschema-0.0.1.tar.gz
Size 222.7 kB
Tags Source
SHA-256 checksum
How to use checksums
6e63e8bcf728f9c2ee4bcd042acaf51e5fb8671e8a0ca604a99421155edefc89
BLAKE2b-256 checksum
How to use checksums
b365e2744fc6c76faf6282070fd214d7ebe1c01d7e4b141842bde58986ddacb8
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 17, 2026.

Transparency log

Release files / valgebra_jsonschema-0.0.1-py3-none-any.whl

Download URL valgebra_jsonschema-0.0.1-py3-none-any.whl
Size 55.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d0b549f2e0763c26a8fbb586ce784231189510c2129d547076ec7820b157ceb
BLAKE2b-256 checksum
How to use checksums
12efcd5784b91ad21fa19c5f64b9250d562860e258ff8c0b12c1965b064f793d
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 17, 2026.

Transparency log

Security for valgebra-jsonschema 0.0.1

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.1.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 17, 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