# valgebra-jsonschema > JSON Schema read into valgebra's sets, for membership as the specification states it and inclusion between two schemas. JSON Schema read into valgebra's sets. compile_schema reads draft 2020-12, and drafts 2019-09, 07, 06 and 04 through upgrade, into sets over the values json.loads returns, and refuses a keyword it does not read by name; valgebra then decides whether a value belongs, as the specification states it, and whether one schema's values all lie in another's. read_tool reads an MCP tool listing into its two contracts. # Getting started # valgebra-jsonschema **JSON Schema read into valgebra's sets.** A schema answers two questions: whether a value belongs, as the specification states it, and whether everything one schema admits another admits too. `compile_schema` reads draft 2020-12, and drafts 2019-09, 07, 06 and 04 through `upgrade`, into [valgebra]()'s sets over the values `json.loads` returns, and raises `Unsupported` naming a keyword it does not read; valgebra then decides membership and inclusion. ``` from valgebra_jsonschema import compile_schema tags = compile_schema({"type": "array", "items": {"type": "string", "minLength": 1}}) assert tags.is_valid(["io", "net"]) assert not tags.is_valid(["io", ""]) # Every array of nonempty strings is an array of strings, and not the converse. strings = compile_schema({"type": "array", "items": {"type": "string"}}) assert tags.relation_to(strings) == "subset" assert strings.relation_to(tags) == "not_subset" ``` ``` pip install valgebra-jsonschema # Python 3.11 or later ``` Membership has the specification's verdict for every keyword the compiler accepts. An inclusion is `subset`, `not_subset` or `undecided`, and `undecided`, where valgebra cannot tell, is never read as either. [How it works]() follows a schema from its document to both answers, with a diagram for each step. Start with [reading an MCP tool]() or [the recipes](); [how each keyword compiles]() is what a schema means here. The site serves [`llms.txt`](), a manifest of its pages, and [`llms-full.txt`](), their full text, for a reader that is not a browser. The developer pages under `docs/dev/` are not published: [how a version reaches PyPI](), and [the standard for every text](). The study files each tool's `--check` reruns are under `docs/studies/`. # Reading an MCP tool A [Model Context Protocol]() server lists each tool with an `inputSchema` and, optionally, an `outputSchema`. `read_tool` reads one entry into its two contracts, so a call and its result can be checked, and two versions of a tool compared: ``` from valgebra_jsonschema import read_tool def listing(units): return { "name": "get_weather", "inputSchema": { "type": "object", "properties": {"location": {"type": "string"}, "units": {"enum": units}}, "required": ["location"], }, "outputSchema": { "type": "object", "properties": {"reading": {"type": "number"}}, "required": ["reading"], }, } old = read_tool(listing(["celsius"])) new = read_tool(listing(["celsius", "kelvin"])) assert old.arguments.is_valid({"location": "Paris"}) assert not old.arguments.is_valid({"location": "Paris", "units": "kelvin"}) assert old.result.is_valid({"reading": 21.5}) # A new version replaces an old one where it takes every call the old one took, # and returns only what the old one promised. assert old.arguments.relation_to(new.arguments) == "subset" assert new.result.relation_to(old.result) == "subset" ``` ## Dialects The protocol states a schema's dialect, and each reads here as: | a document's `$schema` | read as | | --- | --- | | absent | draft 2020-12, as the protocol states | | draft 2020-12 | draft 2020-12 | | draft 2019-09 | rewritten by `upgrade`: an array `items`, and `$recursiveRef` | | draft-07, draft-06, draft-04 | rewritten by `upgrade`, as [older drafts]() says | | anything else | `UnsupportedDialect`, whose message says the dialect is not supported | `UnsupportedDialect` is an `Unsupported`, so a caller refusing a schema it cannot read catches both, and one answering the protocol's error can tell them apart. A document in another dialect with no `$schema` is read as 2020-12: name its dialect with `{"$schema": uri, **schema}`. ## What a tool's schema may hold - **Any 2020-12 keyword.** [The inventory]() lists what each does here. A keyword that is refused raises `Unsupported` naming it, and is never skipped. - **`format` is an annotation**, as 2020-12 makes it, so it admits every value. `read_tool(spec, assert_format=True)` reads nine formats as assertions, and refuses any other ([format on request]()). - **No reference is fetched.** A `$ref` outside the document is refused, which is how the protocol's rule against dereferencing a network reference reads here. - **Bounds hold what a document may cost.** A document past `MAX_NESTING` is refused before it is walked, and valgebra refuses a set past the bounds it holds. - **`inputSchema` names an object**: `type: "object"`, or a root that is a bare `$ref` to one, as zod's named schemas are. `outputSchema` may be any schema. ## What a model vendor enforces A tool author emits a subset of 2020-12 for a model to generate from, and which subset is the vendor's. OpenAI's strict structured outputs ask `additionalProperties: false` and every property required, and leave out `allOf`, `not` and `if`. Anthropic's strict tools leave out numeric and length constraints and recursion. Gemini's `responseSchema` is an OpenAPI 3.0 subset, whose `nullable` is outside the vocabularies, so here it is an annotation that asserts nothing. These are the vendors' to change, so no test here holds them. Whichever subset a tool emits, a contract checks the membership of the value returned. # Recipes Each recipe is one task done end to end with a JSON Schema already in hand, and each says what it cannot do. Each block runs as written. What a keyword compiles to is [the compiler page]()'s, and where a reading differs from another validator's is [the ledger of differences]()'s. ## A model's tool call, against the schema it was shown A model calling a tool writes the arguments as JSON against the `inputSchema` it was shown, and nothing about the model makes them belong. Compiling that same schema checks them, so the schema is written once: what the model reads and what the call is held to are one document. `load` parses the arguments and checks them in one call, and its error names each wrong argument, which the server returns to the model as a tool error: ``` from valgebra import ValidationError from valgebra_jsonschema import read_tool GET_WEATHER = { "name": "get_weather", "description": "The forecast for a city.", "inputSchema": { "type": "object", "properties": { "city": {"type": "string", "minLength": 1}, "unit": {"enum": ["celsius", "fahrenheit"]}, "days": {"type": "integer", "minimum": 1, "maximum": 7}, }, "required": ["city", "unit"], "additionalProperties": False, }, } ARGUMENTS = read_tool(GET_WEATHER).arguments def call(arguments: str) -> dict[str, object]: """Answer a `tools/call` of `get_weather`: the forecast, or an error the model reads.""" try: parsed = ARGUMENTS.load(arguments) except ValidationError as error: return {"content": [{"type": "text", "text": str(error)}], "isError": True} return {"content": [{"type": "text", "text": f"{parsed['city']}: sunny"}], "isError": False} refused = call('{"city": "Turin", "unit": "kelvin", "country": "IT"}') assert refused["isError"] assert refused["content"][0]["text"].splitlines() == [ "2 validation errors:", ( "at unit: expected one of: the literal 'celsius', the literal 'fahrenheit', " "got 'kelvin' [union_error]" ), "at country: expected no unexpected key, got 'country' [extra_forbidden]", ] assert not call('{"city": "Turin", "unit": "celsius", "days": 3.0}')["isError"] ``` `"days": 3.0` meets `"type": "integer"`: JSON Schema reads a number by its value, and `3.0` is the integer 3, where valgebra's own `int` refuses it ([valgebra's recipe for a tool call]() writes the schema a second time, as a `TypedDict`). An argument the tool does not take is refused by `additionalProperties: false`; a schema without it admits any other key with any value. **It checks, and does not convert.** `"days": "3"` is a string, and the model is told so rather than the value read as a number. `format` asserts nothing unless asked: `read_tool(spec, assert_format=True)` reads nine formats as assertions and refuses a schema naming any other ([what a tool's schema may hold]()). ## A schema change, checked before release Whether a new version of a schema breaks its users is a question about two sets, and which one must hold the other turns on who writes the value ([Habib et al. 2021]()). A **request** is written by an old client and read by the new server, so every old value must be a new one: the old schema lies inside the new. A **response** is written by the new server and read by an old client, so the new schema must lie inside the old. Two documents can differ where their sets do not, so the check compares the sets, not the text: ``` from valgebra_jsonschema import compile_schema ORDER_V1 = { "type": "object", "properties": { "id": {"type": "integer", "minimum": 1}, "status": {"enum": ["open", "paid"]}, }, "required": ["id", "status"], } # The same set, its fields written once under `$defs`. ORDER_V1_DEFS = { "$defs": {"id": {"type": "integer", "minimum": 1}, "status": {"enum": ["open", "paid"]}}, "type": "object", "properties": {"id": {"$ref": "#/$defs/id"}, "status": {"$ref": "#/$defs/status"}}, "required": ["id", "status"], } # A status added. ORDER_V2 = { **ORDER_V1, "properties": {**ORDER_V1["properties"], "status": {"enum": ["open", "paid", "refunded"]}}, } # A field required. ORDER_V3 = { **ORDER_V1, "properties": {**ORDER_V1["properties"], "currency": {"type": "string"}}, "required": ["id", "status", "currency"], } def check(old: object, new: object, role: str) -> int: """Return a CI step's exit status for a change: 0 compatible, 1 a break, 2 undecided.""" before, after = compile_schema(old), compile_schema(new) inner, outer = (before, after) if role == "request" else (after, before) return {"subset": 0, "not_subset": 1, "undecided": 2}[inner.relation_to(outer)] for role in ("request", "response"): assert check(ORDER_V1, ORDER_V1_DEFS, role) == 0 assert check(ORDER_V1, ORDER_V2, "request") == 0 assert check(ORDER_V1, ORDER_V2, "response") == 1 # an old client refuses "refunded" assert check(ORDER_V1, ORDER_V3, "request") == 1 # an old client sends no currency assert check(ORDER_V1, ORDER_V3, "response") == 0 assert check({"type": "array"}, {"type": "array", "uniqueItems": True}, "request") == 2 ``` `ORDER_V3` holds as a response because the first version is open: it admits a `currency` of any value already, so every new response is one an old client reads. **Undecided is not compatible.** `uniqueItems` is an [opaque keyword](), exact on membership, and a relation that looks inside one answers `undecided`: `[1, 1]` is an array outside the second schema, and the relation does not refute the request. The exit status keeps the two apart, so a gate passing on 0 alone passes no change it could not decide; a test asserting a compatibility compares with `"subset"`, never with `!= "not_subset"`. A proof is about the schemas, not about data stored under the old one, which [valgebra's recipe for stored data]() reads row by row. ## A schema split across documents A `$ref` may name another document by its URI. Nothing is fetched: each document a reference may name is passed in `documents`, keyed by the URI the reference resolves to, and a reference to any other is refused when the schema compiles, never when a value is checked: ``` from valgebra_jsonschema import Unsupported, compile_schema ADDRESS = { "$id": "https://example.com/schemas/address.json", "type": "object", "properties": { "street": {"type": "string"}, "country": {"type": "string", "pattern": "^[A-Z]{2}$"}, }, "required": ["street", "country"], } CUSTOMER = { "$id": "https://example.com/schemas/customer.json", "type": "object", "properties": {"name": {"type": "string"}, "shipping": {"$ref": "address.json"}}, "required": ["name"], } customers = compile_schema(CUSTOMER, documents={ADDRESS["$id"]: ADDRESS}) assert customers.is_valid({"name": "Ada", "shipping": {"street": "Via Roma 1", "country": "IT"}}) assert not customers.is_valid( {"name": "Ada", "shipping": {"street": "Via Roma 1", "country": "Italy"}} ) refused = False try: compile_schema(CUSTOMER) except Unsupported as error: refused = True assert str(error) == "$ref 'address.json' names a document this one does not hold" assert refused ``` `address.json` resolves against the customer schema's `$id` to the address schema's. Documents kept as files are read the same way: each file parsed, keyed by its `$id`, or, where it declares none, by the URI the references name it by. A supplied document declaring no `$schema` is read in the compiled document's dialect. **A document on the network is the caller's to fetch.** A schema naming one by an `https` URI compiles only once the caller has fetched the document and passed it, so which hosts to trust is the caller's decision; a tool's schema reads the protocol's rule against dereferencing a network reference the same way ([what a tool's schema may hold]()). A URI two schema objects of one document claim is refused where a reference names it ([the inventory]()). ## Files checked against a schema A directory of JSON files, configurations or fixtures, is checked against one schema file by file. `validate_json` parses each file's bytes and checks the value in one call, building no error for a file that belongs, and each failure carries the path to the wrong value and a code: ``` from valgebra import ValidationError from valgebra_jsonschema import compile_schema SERVICE = { "type": "object", "properties": { "name": {"type": "string", "minLength": 1}, "release": {"type": "string", "format": "date"}, "port": {"type": "integer", "minimum": 1, "maximum": 65535}, }, "required": ["name", "release"], "additionalProperties": False, } SERVICES = compile_schema(SERVICE, assert_format=True) def problems(text: bytes) -> list[tuple[tuple[object, ...], str]]: """Return the path and the code of each reason the schema refuses a file's bytes.""" try: SERVICES.validate_json(text) except ValidationError as error: return [(item["path"], item["code"]) for item in error.errors] return [] # Each file's bytes, as `path.read_bytes()` returns them. files = { "web.json": b'{"name": "web", "release": "2026-11-18", "port": 8080}', "jobs.json": b'{"name": "", "release": "18/11/2026", "port": 0, "debug": true}', "admin.json": b'{"name": "admin"', } assert {name: problems(text) for name, text in files.items()} == { "web.json": [], "jobs.json": [ (("name",), "too_short"), (("port",), "union_error"), (("release",), "union_error"), (("debug",), "extra_forbidden"), ], "admin.json": [((), "json_invalid")], } ``` **Report the path and the code, not the message.** A message renders the set the schema compiled to, not the keyword it was written as: a `format` reads as its predicate or its regular expression, a `pattern` as its translation into valgebra's dialect, and an `integer` with a bound as `int and >= 1, float and >= 1`. The path names the value and the code the failed check, and both are stable. A file in TOML or YAML is parsed by the library that owns the format, and the value it returns checked with `validate`, which reads only what `json.loads` could return: a TOML date is no JSON value, and no schema admits it. `assert_format=True` refuses a schema whose `format` is one of the many it does not read, `uri` among them, so a schema from elsewhere compiles with formats as annotations or not at all. ## What a schema asserts A keyword outside the vocabularies is an annotation, as draft 2020-12 says, so a misspelled one asserts nothing and admits every value. `compile_with_fallbacks` returns the compiler beside the set, and the compiler records each keyword it read as an annotation in `ignored` and each it read as an opaque predicate in `opaque`; `compile_schema` refuses a keyword it does not read: ``` from valgebra_jsonschema import Unsupported, compile_schema, compile_with_fallbacks PROFILE = { "type": "object", "properties": { "name": {"type": "string", "maxLenght": 20}, "tags": {"type": "array", "uniqueItems": True}, }, } compiler, profiles = compile_with_fallbacks(PROFILE, PROFILE) assert compiler.ignored == {"maxLenght"} assert compiler.opaque == {"uniqueItems"} assert profiles.is_valid({"name": "a" * 50}) # the misspelled bound bounds nothing refused = False try: compile_schema({"type": "object", "dependencies": {"card": ["billing"]}}) except Unsupported as error: refused = True assert str(error) == "keyword 'dependencies' is not supported" assert refused ``` A schema's author reads `ignored` for a keyword meant to assert, and `opaque` for the keywords a relation through the schema answers `undecided` across. `dependencies`, a draft-07 keyword draft 2020-12 removed, is refused in a 2020-12 schema rather than read as an annotation, since its author wrote it to a draft where it asserts; a schema declaring draft-07 compiles it. **`compile_with_fallbacks` reads draft 2020-12.** It compiles the document as given, so an older one goes through `upgrade(document, older(document))` first, which `compile_schema` does itself. A `$defs` entry no reference names is never compiled, so a keyword in it is neither recorded nor checked. # Release notes ## Versioning, and what counts as a break The version follows [Semantic Versioning](). Below `0.1.0` there is no minor number to carry a break, so every `0.0.x` release may break, and its notes say where. A break is a public name removed or changed, a value a schema held that it no longer holds or the reverse, or an inclusion decided one way that is now decided the other; an inclusion left undecided that is now decided is not one. Each release takes valgebra's newest `0.0.x`, and the range it requires says which. # Changelog All notable changes to valgebra-jsonschema are recorded here. The format follows [Keep a Changelog](), and the project follows [Semantic Versioning](). ## [Unreleased]() ### Added - `Compiler.reworded(failure)` names each pattern a failure names in the schema's text, `a string matching '^[a-f0-9]{24}$'` where valgebra names the text it was given, the pattern unanchored and its classes written out; `Compiler.patterns` holds the texts. A part a lookahead is read as, and a text two patterns translate to, are named as valgebra gave them. ## [0.0.4]() - 2026-11-21 A release of three readings, on valgebra 0.0.31: what a member holds at a path inside a schema, a `propertyNames` spelling its names out as the record of those keys, and a conjunction drawn merged. Every case of the suite gets the verdict it got, and the corpus disagrees with the `jsonschema` package on the same 13 values; the containment study decides 65 questions more, 29 as the suite labels them and 36 against labels the `jsonschema` package's validator for the draft shows wrong. ### Added - A page follows a schema from its document to its two answers, membership and inclusion, with a diagram for each step: what the compiler reads, what valgebra decides, and where a keyword read as a predicate leaves a relation `undecided`. - `Compiler.below(path)` returns the values a member of the root holds at a path of keys and `ITEM`, any element of an array, read through every keyword that narrows them and a `$ref` resolved against the base URI it sits under: an upper bound, holding every value a member holds there. A consumer reading one field's schema itself, as through `properties` alone or a `$ref` from the document's root, reads less, or another resource's schema. ### Fixed - `Sampler` draws a conjunction merged keyword by keyword: an `allOf` with the schema around it, an `anyOf` or `oneOf` branch with its siblings, and a reference's target with the keywords beside it, `properties` met key by key, `required` united, `type` keeping the kinds both name and each bound the tighter. A member's `properties` replaced the outer schema's, so a record an `allOf` narrows drew no member. A required key `properties` does not name is drawn from `additionalProperties`, a pattern holding a group, an alternation or `.` is drawn inside it, and a schema naming no `type` draws the container kind its keywords read beside the scalars. On fishtest's six output schemas, 215 of 240 draws are members, against 88. ### Changed - The documentation site is built by Zensical, Material for MkDocs' maintained successor, from `mkdocs.yml` as written under `zensical build --strict`: its own search, the redirects from each page's former address, `llms.txt` and `llms-full.txt`, the Mermaid diagrams and the API reference through the mkdocstrings Python handler. No page moves. - A `propertyNames` spelling its names out, an `enum`, a `const`, or an `anyOf` or `oneOf` of them, compiles to the closed record of those keys, each optional, rather than to an opaque predicate: `{"propertyNames": {"enum": ["k", "j"]}}` is `subset` of the object whose `properties` are `k` and `j` with `additionalProperties: false`, and the converse too, where both read `undecided`. Membership is unchanged; the suite's `propertyNames` cases going through an opaque predicate fall from 7 to 0 in drafts 2020-12, 2019-09, 07 and 06. - The package requires valgebra 0.0.31 or later, which counts a record's keys under `minProperties` and `maxProperties`: `{"propertyNames": {"enum": ["k", "j"]}, "minProperties": 2}` is `subset` of the object requiring `k` and `j`, and `{"required": ["k"], "maxProperties": 1}` of the closed record of `k`, where both read `undecided`. The suite and corpus studies read no difference. The containment study decides 65 questions more, a proof and 64 refutations, 36 of them against the suite's labels: 35 in draft 4 stand on a `const`, which draft 4 does not have, and one in draft 2020-12's `unsatisfiable/dynamicRef.json` on `{"bar": {"baz": {}}}`, which the meet it labels empty holds. ## [0.0.3]() - 2026-11-19 A release of the dependency range: the compiler is 0.0.2's, and every published count is the one 0.0.2 recorded, read again on valgebra 0.0.30. ### Changed - The package requires valgebra 0.0.30 or later, with no upper bound: a valgebra release installs beside this package the day it is published, with no release of this package. ## [0.0.2]() - 2026-11-18 A release of the user guide, with no change to the compiler: every schema compiles to the set 0.0.1 compiled it to, and every published count is the one 0.0.1 recorded. ### Added - The user guide is published at [https://ppigazzini.github.io/valgebra-jsonschema/](), with `llms.txt` and `llms-full.txt` for a reader that is not a browser, and the API reference read from the package's docstrings. - A recipes page does 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. ### Changed - The package's `Documentation` link and the README's links go to the published guide. Each page's address is its topic, `/mcp/` and `/compiler/`, and an address the site has served before answers with a page that sends the reader on. - The package requires valgebra 0.0.29 and below 0.0.30, whose release changes no answer of 0.0.28. ## [0.0.1]() - 2026-11-17 ### Added - `compile_schema` reads JSON Schema drafts 2020-12, 07, 06 and 04 into valgebra's sets over the values `json.loads` returns, and raises `Unsupported` naming a keyword it does not read. - Draft 2019-09 reads through `upgrade`, and a document naming any other dialect raises `UnsupportedDialect`, a kind of `Unsupported`, whose message says it is not supported. - A `$ref` resolves against the base URI it sits under: an embedded `$id` starts a resource, and a reference names a resource of the document by its URI, then a schema in it by a JSON pointer or an `$anchor`. An older draft's `$id` fragment that is a plain name reads as the `$anchor` it names. A URI two schema objects of one document claim, and an anchor two of one resource set, name neither, and a `$ref` or `$dynamicRef` naming one is refused, as draft 2020-12 asks for an error (sections 8.2.2 and 9.1.2). - `compile_schema(schema, documents={uri: document})` takes the documents a reference may name beside the one compiled, and `Sampler` takes them too. Each is a resource at its URI, read in its own dialect or, declaring none, in the compiled document's; one in a dialect not read is refused only where a reference names it, and no document is fetched. The compiled document names its own URI throughout a compile, as draft 2020-12 makes the root's `$id` its canonical URI (section 9.1.1), so a document supplied at that URI is not read. - `$dynamicRef` reads the dynamic scope across every document: where its target sets a `$dynamicAnchor` of its fragment's name, it names the outermost schema object of the scope that sets one (draft 2020-12, sections 7.1 and 8.2.3.2), and `$dynamicAnchor` names its schema object as `$anchor` does. Draft 2019-09's `$recursiveAnchor: true` on a resource's root is a dynamic anchor with no name, and its `$recursiveRef: "#"` the `$dynamicRef: "#"` that reads it, as the draft 2020-12 release notes say the two pairs agree. - `unevaluatedProperties` and `unevaluatedItems` are read on each case of which in-place subschemas hold, as the object group or the array that leaves the keys or items nothing evaluates there to the subschema. - `patternProperties` up to four patterns, and a `propertyNames` of words, are clauses over keys narrowed by a pattern, so a relation reads them. `propertyNames: true` names every key, and `propertyNames: false` none, so it admits the empty object alone. - A `pattern` opening with lookaheads, `^(?!A)(?=C)B`, and one tempering its dot, `^((?!A).)*$`, are the sets they denote, meets of patterns with complements, which a relation reads. Any other lookaround is outside valgebra's dialect. - A property name ending in `?` is that name. valgebra's record literal reads the suffix as "optional", so such a key is written with one more and, where it is required, met with its presence, which a `TypedDict` names whole. - `uniqueItems` is one predicate in every schema, and a fractional `multipleOf` one per step, so a schema holding either is proved below itself. - `oneOf` leaves out the complement of a branch valgebra proves disjoint from another, which holds none of its values: each branch is spelled once per branch it may meet. - A schema past valgebra's node limit with keys read by predicate reads each `oneOf` as its union met with a count of the branches that hold, and each reference to a definition that does not reach itself through the definition's own set: membership stays exact, and a relation reading inside those parts declines. `compile_with_fallbacks` is the cascade `compile_schema` and `Sampler` share. - `constants(schema)` lists the values a schema spells out with `const`, `enum`, or an `anyOf` or `oneOf` of them, and such a schema lies inside another exactly where each value is a member of it, over a predicate as well. - NaN is a value of no schema, since JSON has none (RFC 8259 §6). An infinity is a number, as `json.loads` reads one past the float range. - `read_tool` reads an MCP server's tool listing into its two contracts. - `assert_format=True` reads `date`, `duration`, `ipv4`, `uuid`, `date-time`, `time`, `email`, `hostname` and `ipv6` as assertions, and refuses any other `format`. It is off by default. - The package requires valgebra 0.0.28 and below 0.0.29, since a `0.0.x` minor of valgebra is a breaking release here: each is taken by a release of this package, with its suite run on it. - Measured on this release, each figure in [the results page](): the official JSON-Schema-Test-Suite passes the 1393 draft 2020-12 cases it runs and the 1256 of 2019-09, each skipping the five that name a custom meta-schema, and every case of drafts 07, 06 and 04, 929, 841 and 618. 9486 of JSONSchemaBench's 9558 schemas compile, and membership differs from the `jsonschema` package's on 13 of 404720 values, each a reading the ledger records. Of the containment test suite's 10890 questions, 7048 are proven, 3560 refuted, 246 undecided and 36 refused. # Explanation # How it works A JSON Schema document becomes a valgebra set over the values `json.loads` returns, and the set answers two questions: whether a value belongs, as the specification states it, and whether every value one schema admits another admits too. This page follows a schema from its document to those two answers; [the compiler]() states each keyword in full. ## Two questions, one set A validator answers the first question for one value at a time. The second is about every value at once, so no run of a validator answers it: which values may a new version of a tool return that an old client never saw, which arguments did the old version take that the new one refuses. Here both are asked of one compiled set. ``` from valgebra_jsonschema import compile_schema at_least_3 = compile_schema({"type": "integer", "minimum": 3}) integers = compile_schema({"type": "integer"}) # Membership: a value's verdict, as the specification gives it. assert at_least_3.is_valid(5) assert not at_least_3.is_valid(2) # Inclusion: every value of one set in the other, or not. assert at_least_3.relation_to(integers) == "subset" assert integers.relation_to(at_least_3) == "not_subset" ``` ## From a document to a set ``` flowchart TD document["a JSON Schema document:
draft 2020-12, 2019-09, 07, 06 or 04"] --> upgrade["upgrade: an older draft
rewritten into draft 2020-12"] upgrade --> compiler["the compiler: each keyword a set,
a schema object their meet,
each reference resolved against its base URI"] compiler --> set["a valgebra set over
the values json.loads returns"] set -->|"is_valid(value)"| member["membership:
the specification's verdict"] set -->|"relation_to(other)"| relation["inclusion: subset,
not_subset or undecided"] ``` - **The dialect.** A document with no `$schema` is draft 2020-12, as the Model Context Protocol states. `compile_schema` rewrites a draft 2019-09, 07, 06 or 04 document by `upgrade` into the draft 2020-12 document with the same meaning, and refuses any other dialect. - **References.** A `$ref` resolves against the base URI it sits under, to the document compiled or to one `documents` holds; none is fetched. A schema reaching itself, a tree or a linked list, compiles to the recursive set it denotes. - **The universe.** The values `json.loads` returns: `None`, `bool`, `int`, a `float` that is not NaN, `str`, `list` and `dict` with `str` keys, nested. A tuple, a Python set or a `datetime` is no JSON value and lies outside every schema. What the set means, and whether one lies inside another, is [valgebra]()'s to decide; what a keyword means is the specification's, and reading it into a set is this package's. ## A keyword is a guarded set An assertion keyword constrains one kind of value and passes every other kind, and a schema object holds where each of its keywords does (Attouche et al. 2024, §4.2, §4.5). So a keyword is the set `complement(kind) | refined`, and a schema object the meet of its keywords: ``` flowchart TD schema["{type: integer, minimum: 3}"] --> kind["type: integer
an int that is no bool,
or a float that is a whole number"] schema --> bound["minimum: 3
every value that is no number,
or a number of 3 or more"] kind --> meet["their meet: the integers of 3 or more;
the values that are no number fall away"] bound --> meet ``` ``` from valgebra_jsonschema import compile_schema # Alone, `minimum` constrains numbers and passes every other kind. assert compile_schema({"minimum": 3}).is_valid("a") assert not compile_schema({"type": "integer", "minimum": 3}).is_valid("a") ``` ## One number, every spelling JSON compares numbers by value: `1` and `1.0` are one number, and `true` is not `1`. Every set here holds every spelling of the JSON values it admits, so `integer` admits a `float` that is a whole number, and a constant admits each spelling of itself. ``` from valgebra_jsonschema import compile_schema one = compile_schema({"const": 1}) assert one.is_valid(1) and one.is_valid(1.0) assert not one.is_valid(True) assert compile_schema({"type": "integer"}).is_valid(2.0) ``` ## What a keyword can become ``` flowchart TD keyword["a keyword of a schema object"] --> asserts{"does it assert?"} asserts -->|"no: an annotation, or
outside the vocabularies"| nothing["nothing asserted; one outside
the vocabularies is recorded
in Compiler.ignored"] asserts -->|yes| reads{"what does valgebra
spell it as?"} reads -->|"a set"| exact["exact: membership,
and relations through it decided"] reads -->|"only a predicate"| opaque["opaque: membership exact,
a relation looking inside it undecided;
recorded in Compiler.opaque"] reads -->|"neither"| refused["refused: Unsupported names it;
it is never skipped"] ``` `uniqueItems` needs equality across items, which no set of valgebra's spells, so it is a predicate: a value's membership is exact, and a relation that must look inside it is undecided. A keyword the specification's vocabularies do not hold, a vendor's `x-` extension, asserts nothing, and a reference to a document the compiler does not hold is refused: ``` from valgebra_jsonschema import Compiler, Unsupported, compile_schema unique = compile_schema({"type": "array", "items": {"type": "integer"}, "uniqueItems": True}) arrays = compile_schema({"type": "array", "items": {"type": "integer"}}) assert unique.is_valid([1, 2]) and not unique.is_valid([1, 1]) assert unique.relation_to(arrays) == "subset" assert arrays.relation_to(unique) == "undecided" schema = {"type": "array", "uniqueItems": True, "x-vendor": 1} compiler = Compiler(schema) compiler.compile(schema) assert (compiler.opaque, compiler.ignored) == ({"uniqueItems"}, {"x-vendor"}) try: compile_schema({"$ref": "https://example.com/other.json"}) except Unsupported as refusal: assert "does not hold" in str(refusal) ``` [The inventory]() lists what each keyword does, and [opaque keywords]() why each predicate is one. ## Three answers to an inclusion | `relation_to` answers | meaning | | --- | --- | | `subset` | valgebra proves every value of the first set lies in the second | | `not_subset` | valgebra proves a value of the first set lies outside the second | | `undecided` | neither: a predicate it must look inside, or a gap in valgebra's decision | `undecided` is never read as either of the others, so a caller relying on `subset` never relies on a guess. Membership has no third answer: for every keyword the compiler accepts and every JSON value, `is_valid` gives the verdict the specification gives, and [the conformance page]() holds how that is checked. ## A tool's two contracts ``` flowchart TD listing["an MCP tool listing"] --> read_tool["read_tool"] read_tool --> arguments["Tool.arguments:
the inputSchema's set"] read_tool --> result["Tool.result:
the outputSchema's set"] arguments --> call["a call checked
before it is made"] result --> answer["a result checked
as it returns"] arguments --> versions["two versions compared:
the old arguments inside the new,
the new result inside the old"] result --> versions ``` `read_tool` reads one entry of a tool listing into its two contracts. Which way a comparison runs turns on who writes the value ([Habib et al. 2021]()): an old client's arguments must lie inside what the new version takes, and the new version's results inside what the old one promised. [Reading an MCP tool]() has the example, and [valgebra-planning]() builds on the same sets to prove a program of calls well-typed for every result the contracts admit. ## Where it sits | a tool | answers | | --- | --- | | a validator, as the `jsonschema` package | one value's membership | | a subschema checker (Habib et al. 2021) | one schema's inclusion in another | | valgebra-jsonschema | both, from one set, with valgebra's three answers to an inclusion | Each answer is held to an oracle: the official JSON-Schema-Test-Suite for membership, JSONSchemaBench's real-world schemas beside the `jsonschema` package, and the JSON Schema containment test suite's labels for inclusion. [The results]() hold every count with the command that prints it. ## What it does not cover - **No reference is fetched.** A `$ref` to a document neither the one compiled nor `documents` holds is refused. - **`format` is an annotation**, as draft 2020-12 makes it; `assert_format=True` reads nine formats as assertions and refuses any other. - **An opaque keyword costs relations.** Membership through it is exact; an inclusion that has to look inside it is undecided. - **Values outside JSON.** A schema describes JSON values; a Python value `json.loads` never returns lies outside every one. [The ledger of differences]() lists each place the compiler reads a keyword apart from the specification, and why. # The compiler `valgebra_jsonschema/schema.py` compiles JSON Schema draft 2020-12, and drafts 2019-09, 07, 06 and 04 through `upgrade`, into valgebra sets. [How it works]() is the same ground in brief, with diagrams; [the conformance page]() holds the keyword inventory and the ledger of differences. The universe is what `json.loads` returns for a JSON text — `None`, `bool`, `int`, a `float` that is not NaN, `str`, `list`, and `dict` with `str` keys, nested. JSON has no NaN (RFC 8259 §6), and `json.loads` builds one only from the token `NaN`, so no schema admits it; an infinity is `json.loads`'s reading of a number past the float range, such as `1e400`, and stands for it. On it the translation is exact for every keyword it accepts, with patterns read as ECMA-262 defines them; where a pattern uses a construct valgebra's engine refuses, the schema is refused. ## Keyword semantics An assertion keyword constrains one kind and passes every other kind: `{"minimum": 3}` admits `"a"`. Each such keyword compiles to `complement(kind) | refined`, and a schema object to the meet of its keywords. Where `type` already confines the instance to the keyword's kind, the guard's other half is empty after the meet and is left out. Where `type` names arrays alone, `items` and `prefixItems` compile to lists whose every item is a compiled subschema, and where it names objects alone, `properties`, `required` and `additionalProperties` to a record whose every value is one: each lies inside the JSON arrays or objects, so the kind's own set is left out of the meet too, and a walk reads each value once. `{"type": "array", "items": {"type": "string"}}` is `list[str]`; `patternProperties` past four patterns is a predicate over every `dict`, and keeps the kind. An array's kind in a guard is the bare `list`, and an object's the bare `dict`: every compiled set is met with the JSON values, inside which the bare kind and the JSON one agree, and valgebra decides the complement of the bare kind where it declines that of the recursive one. The walk reads whether an array or an object lies outside the kind from its type alone, rather than from its items. A schema whose guard reaches past the JSON values is met with them, and only where it is used as itself. Where `not`, `oneOf`, `if` and `contains` complement a schema, the complement reads its keywords' meet alone (`Compiler.compile_body`): it is met with a set inside the JSON values, where the two agree, and valgebra decides the complement of the bare meet where it declines that of a meet holding the recursive universe. | keyword | set | | --- | --- | | `type` | union of kinds; `integer` is an `int` that is not a `bool`, or a `float` that is a multiple of 1 | | `enum`, `const` | union of the constants under JSON equality: `1` and `1.0` are one number, `true` is not `1`; arrays and objects compare structurally | | `minimum`, `maximum`, `exclusive*` | bound refinements on `int` and `float` | | `multipleOf` | an integral step is valgebra's `MultipleOf`; a fractional step is opaque, checked in exact rational arithmetic | | `minLength`, `maxLength` | length refinements, in code points | | `pattern` | `p` becomes `(?s:.*)(?:p')(?s:.*)`, where `p'` is `p` read by ECMA-262's grammar under the `u` flag and written back with every literal a code point, every class a list of code point ranges and General\_Category or Script property escapes, `\d`, `\w`, `\s` and their negations the ASCII and ECMA-262 ranges they denote, `.` every code point but the four line terminators, and `\b`, `\B` boundaries of ASCII word characters: ECMA-262 searches, valgebra's `Regex` matches the whole string, and the two dialects read those constructs differently. An escape of punctuation, a lone `]` or `}` and a `{` that opens no count are the character; any other construct invalid under `u` is refused. Lookaheads opening a pattern, `^(?!A)(?=C)B`, are the strings `^B` finds a match in where no match of `A` starts the string and one of `C` does, where `B` alternates at no top level; `^((?!A).)*$` is the strings with no line terminator where `A` occurs nowhere, where `A` matches no empty string and asserts no position. Any other lookaround is outside valgebra's dialect | | `prefixItems`, `items` | the union of the shorter fixed prefixes and the prefix followed by a repeated tail | | `minItems`, `maxItems`, `min/maxProperties` | length refinements | | `contains` | arrays not all of whose elements lie outside the subschema | | `properties`, `required`, `additionalProperties` | one record: optional and required fields, and a catch-all clause for every other key; a required key outside `properties` takes the additional schema | | `dependentRequired`, `dependentSchemas` | "key absent, or the dependency holds" | | `allOf`, `anyOf`, `not` | meet, union, complement within the JSON values | | `oneOf` | each branch minus every other branch valgebra does not prove disjoint from it | | `if`, `then`, `else` | `(if & then) \| (~if & else)` | | `unevaluatedProperties`, `unevaluatedItems` | on each case of which in-place subschemas hold, the keys or items no keyword beside it nor holding subschema evaluates (draft 2020-12, section 11), read as the object group or the array of a prefix that leaves them to the subschema: an `anyOf` of more than four branches beside one, more than 64 cases, or a `$ref` reaching itself at one instance is refused | | `$ref` | resolved against the base URI it sits under, to a resource of the document and a JSON pointer or `$anchor` in it; compiled as a `recursive` fixpoint over its target | | `$dynamicRef`, `$dynamicAnchor` | a `$dynamicAnchor` names its schema object as an `$anchor` does; a `$dynamicRef` reads the dynamic scope only where its target sets a dynamic anchor of the fragment's name, and names the outermost schema object of the scope that sets one (draft 2020-12, sections 7.1 and 8.2.3.2). Where one schema object of every document sets that name, it is the `$ref` it resolves as; anywhere else the document compiles again keeping the scope, each schema object once per binding of the names its scope holds, and a target the scope chooses is a `recursive` fixpoint, which a reference reaching it again closes | Annotations assert nothing and are skipped: `title`, `description`, `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `format` (the format-annotation vocabulary is the default), the `content*` keywords, `$comment`, `$defs`. `$id` and `$anchor` assert nothing either: `$id` sets the base URI of its resource, which the references inside resolve against (draft 2020-12, section 8.2), and `$anchor` names its schema object within that resource. An embedded resource declaring another `$schema` is refused. ## `format`, on request `format` is an annotation, as draft 2020-12 makes it. `compile_schema(schema, assert_format=True)` reads it as an assertion over strings, and passes every other kind as any assertion does. | format | read as | | --- | --- | | `date`, `duration`, `ipv4`, `uuid` | a regular language, so a relation through it is decided | | `date-time`, `time`, `email`, `hostname`, `ipv6` | a predicate, exact on membership and opaque to a relation | Any other format is refused, since the assertion left out would admit what the schema refuses. The results page has [the official suite's counts](), and the conformance ledger [the one difference](). ## Older drafts A schema whose `$schema` names draft 2019-09, draft-07, draft-06 or draft-04 is rewritten by `upgrade` into the draft 2020-12 schema with the same meaning before it is compiled: an `items` array becomes `prefixItems` and `additionalItems` becomes `items`; `dependencies` splits into `dependentRequired` and `dependentSchemas`; a `$ref` drops its siblings, which those drafts ignore, but for `definitions` and `$defs`; and a keyword the draft does not know is dropped, since it reads it as an annotation: `prefixItems`, `minContains` or `dependentRequired` written into any of them, `if`, `then` and `else` in draft-06, and `const`, `contains` and `propertyNames` in draft-04 too. Draft-04 also writes `exclusiveMinimum` and `exclusiveMaximum` as flags on `minimum` and `maximum`, and `$id` as `id`; both are rewritten. An older `$id` whose fragment is a plain name, `#foo`, names its schema object as `$anchor` does, and is rewritten to one. Only keywords that hold subschemas are descended into, so a property named `items` stays a name. Draft 2019-09 differs less. A `$ref` keeps its siblings, `dependencies` is no keyword, so it is refused as in 2020-12, and an array `items` and its recursion read apart from 2020-12. `$recursiveAnchor: true` on the root of a resource is a `$dynamicAnchor` whose name is empty, and `$recursiveRef: "#"` the `$dynamicRef: "#"` that reads it, as the draft 2020-12 release notes say the two pairs agree: the reference names the root of the resource holding it, or, where that root sets the anchor, the outermost schema in the dynamic scope that sets it (draft 2019-09, section 8.2.4.2.2). The empty name is one no draft 2020-12 anchor may spell, so it meets no anchor of a document. A `$recursiveAnchor: true` on a schema object starting no resource is refused, since 2019-09's text reads one anywhere in the scope by its resource's root and the release notes hold it to a root; so is a `$recursiveRef` of any other value. ## Keys `patternProperties` and a `propertyNames` of words are clauses over keys narrowed by a pattern, so a relation reads them: `{"patternProperties": {"^x-": {"type": "string"}}, "additionalProperties": false}` is `subset` of an object of strings and the converse is `not_subset`. A key takes the schema of every pattern it matches, a conjunction, and valgebra reads two clauses over one key as a disjunction, so the keys are split where the patterns part, into up to sixteen cells, and no two clauses share a key. `propertyNames: true` names every key, as `{}` does, and `propertyNames: false` names none, so the one object it admits is the empty one. A `propertyNames` spelling its names out, an `enum`, a `const`, or an `anyOf` or `oneOf` of them, is the closed record of those keys, each optional: keys as `properties` writes them, so `{"propertyNames": {"enum": ["k", "j"]}}` over objects is `subset` of `{"properties": {"k": {}, "j": {}}, "additionalProperties": false}` and the converse too. A name is a string (draft 2020-12, section 10.3.2.4), so a value that is not one names no key. `minProperties` and `maxProperties` count a record's keys. A `minProperties` counting every key the record can hold requires each, so `{"propertyNames": {"enum": ["k", "j"]}, "minProperties": 2}` over objects is `subset` of the object requiring `k` and `j`; a `maxProperties` counting the required keys admits no other, so `{"required": ["k"], "maxProperties": 1}` is `subset` of the closed record of `k`. A count of fewer keys than the record holds proves no one of them: with `"minProperties": 1` the first is `undecided` below the object requiring `k`, which `{"j": 1}` refutes. ## What a member holds below `Compiler.below(path)` returns the values a member of the root holds at `path`, a sequence of keys and `ITEM`, any element of an array: the meet of what each keyword says of them, through `properties`, `patternProperties`, `additionalProperties`, `prefixItems`, `items`, `allOf`, `anyOf`, `oneOf`, `if` with `else`, listed values and a `$ref` resolved against the base URI it sits under. It is an upper bound: `not`, a lone `if`, `$dynamicRef` and `unevaluatedProperties` narrow nothing, so every value a member holds at the path lies inside, and the set may hold one no member does. Whether the bound is tight is a relation valgebra decides against the whole schema. ``` from valgebra_jsonschema import ITEM, Compiler, compile_schema page = { "$defs": {"run": {"properties": {"tags": {"type": "array", "items": {"enum": ["a", "b"]}}}}}, "type": "object", "properties": {"runs": {"type": "array", "items": {"$ref": "#/$defs/run"}}}, } tags = Compiler(page).below(("runs", ITEM, "tags", ITEM)) assert tags.is_equivalent(compile_schema({"enum": ["a", "b"]})) ``` ## A failure in the schema's text valgebra matches a `pattern` in its own dialect: the compiler writes it unanchored, as ECMA-262's `test` searches, and each class atom as a code point, so a failure names that text, `a string matching '(?s:.*)(?:^[\\x{61}-\\x{66}]{2}$)(?s:.*)'` for `^[a-f]{2}$`. `Compiler.reworded` returns a failure with each pattern this compiler wrote named in the schema's text, in `expected` and in `message`; `Compiler.patterns` holds the texts. ``` from valgebra import ValidationError from valgebra_jsonschema import Compiler schema = {"type": "string", "pattern": "^[a-f0-9]{24}$"} compiler = Compiler(schema) ids = compiler.compile(schema) assert not ids.is_valid("nope") try: ids.validate("nope") except ValidationError as error: named = compiler.reworded(error.errors[0]) assert named["expected"] == "a string matching '^[a-f0-9]{24}$'" ``` A failure names a pattern this way wherever a `pattern`, a `propertyNames` pattern or a key of a closed `patternProperties` fails. A lookahead is read as parts, none of which is the pattern, and a failure names the part as valgebra gave it; so does a text two patterns translate to, as `^\d$` and `^[0-9]$` do. `compile_schema` keeps its compiler, and `compile_with_fallbacks` returns the one it read the schema with. valgebra holds no display text: a marker's fields are its identity, so a text stored beside a `Regex` would make one pattern two markers that compare and hash apart. ## Opaque keywords These have no counterpart in valgebra's set language, so they compile to predicates: membership is exact, and a relation that has to look inside one answers "undecided", never a wrong proof. `Compiler.opaque` lists those a schema used. `uniqueItems` is one callable in every schema, and a fractional `multipleOf` one per step, so valgebra relates each to itself: `{"uniqueItems": true}` compiled twice is proved below itself. The predicates of `minContains`, `maxContains` and `propertyNames` hold a set compiled from their subschema, and each compilation holds its own. | keyword | why | | --- | --- | | `patternProperties`, past four patterns or in a schema past valgebra's limit | a clause per cell of keys, and the cells number two to the patterns | | `propertyNames`, but `true`, `false`, one spelling its names out, and one reading only `pattern`, `minLength`, `maxLength`, `type` | a key is narrowed by words or listed, and no other schema names them | | `uniqueItems` | needs equality across elements | | `minContains`, `maxContains` | need counting | | `multipleOf` with a fractional step | `0.0075 % 0.0001` is not zero in binary floating point | | `oneOf`, and a `$ref` to a definition that does not reach itself, in a schema past valgebra's limit with keys read by predicate too | "exactly one" of two branches is their exclusive or, which no formula writes with each branch once, and a definition inlined at each use is written once per use: the union is met with a count of the branches that hold, and the reference checks the definition's own set | ## Refused, and ignored `Unsupported` names the keyword: references to a document neither the one compiled nor `documents` holds, a reference to a URI two schema objects of one document claim or to an anchor two of one resource set, a supplied document in a dialect not read where a reference names it, an embedded `$id` whose resource declares another `$schema`, a draft other than 2020-12, 2019-09, 07, 06 and 04, a draft 2019-09 `$recursiveAnchor: true` on a schema object starting no resource, and a property name holding a lone surrogate. A keyword outside the vocabularies is an annotation, as draft 2020-12 says, and `Compiler.ignored` records it. ## Measured ``` uv run python tools/suite.py --check docs/studies/json-schema-test-suite.json ``` The official JSON-Schema-Test-Suite at commit `89e83a740146`, vendored with its MIT license. Draft 2020-12, with the four optional files on regular expressions and large numbers: 1393 cases run, 1393 passed, 0 failed; 5 skipped, each naming a custom meta-schema as its dialect; 96 of the run cases go through an opaque predicate. A case's remote documents are the suite's `remotes/`, vendored with it, and the drafts' meta-schemas from the `jsonschema-specifications` package, passed as `documents`. Draft-07, through `upgrade`: ``` uv run python tools/suite.py --draft 7 --check docs/studies/json-schema-test-suite-draft7.json ``` 929 cases run, 929 passed, 0 failed; 0 skipped. Draft 2019-09, through `upgrade`: ``` uv run python tools/suite.py --draft 2019-09 --check docs/studies/json-schema-test-suite-draft2019-09.json ``` 1256 cases run, 1256 passed, 0 failed; 5 skipped, the same five. Draft-06 and draft-04, through `upgrade`: ``` uv run python tools/suite.py --draft 6 --check docs/studies/json-schema-test-suite-draft6.json uv run python tools/suite.py --draft 4 --check docs/studies/json-schema-test-suite-draft4.json ``` Draft-06, 841 cases run, 841 passed, 0 failed; 0 skipped. Draft-04, 618 cases run, 618 passed, 0 failed; 0 skipped. ``` uv run python tools/suite.py --reference ``` On the same optional files the `jsonschema` package 4.26.0 passes 42 of the 74 `ecmascript-regex` cases and 12 of the 12 `non-bmp-regex` cases: it reads patterns with Python's `re`, where `\d` matches any Unicode digit and `$` matches before a final newline. # Conformance What the compiler promises against JSON Schema, how it is checked, and where a difference is allowed to live. ## The contract For every keyword `valgebra_jsonschema/schema.py` accepts and every JSON value, compiled membership gives the verdict the specification gives. A keyword it cannot translate raises `Unsupported`; it is never skipped. A difference not in the ledger below is a defect. ## The oracles - **The specification**, as the official JSON-Schema-Test-Suite encodes it, vendored at commit `89e83a740146` with its MIT license: draft 2020-12 with the optional files on regular expressions and on large numbers, and drafts 2019-09, 07, 06 and 04 through `upgrade`. ``` uv run python tools/suite.py --check docs/studies/json-schema-test-suite.json uv run python tools/suite.py --draft 2019-09 --check docs/studies/json-schema-test-suite-draft2019-09.json uv run python tools/suite.py --draft 7 --check docs/studies/json-schema-test-suite-draft7.json uv run python tools/suite.py --draft 6 --check docs/studies/json-schema-test-suite-draft6.json uv run python tools/suite.py --draft 4 --check docs/studies/json-schema-test-suite-draft4.json ``` - **Real-world schemas.** JSONSchemaBench's 9558, fetched at a pinned commit and never vendored, each checked on drawn and generic values against the `jsonschema` package's validator for its draft: ``` uv run python tools/corpus.py --check docs/studies/jsonschemabench.json ``` - **Inclusions**, as the JSON Schema containment test suite labels them: pairs of schemas fetched at a pinned commit and never vendored, each labeled direction asked of valgebra. No proof may contradict a label, and a refutation that does is a wrong label the results page names: ``` uv run python tools/containment.py --check docs/studies/containment.json ``` - **The `jsonschema` package**, pinned in the development group, as a second implementation: `tests/test_properties.py` compares membership on 400 random schemas and 25 random values each, over the keywords whose meaning the two share exactly. Where the specification and the package disagree, the specification wins, and the disagreement is a ledger entry against the package. ## The inventory Every keyword of the draft 2020-12 vocabularies is in exactly one class, and `tests/test_boundaries.py` holds this table against the code in both directions. | class | keywords | | --- | --- | | translated exactly | `type`, `enum`, `const`, `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`, an integral `multipleOf`, `minLength`, `maxLength`, `pattern`, `prefixItems`, `items`, `contains`, `minItems`, `maxItems`, `properties`, `required`, `additionalProperties`, `minProperties`, `maxProperties`, `patternProperties`, `propertyNames`, `dependentRequired`, `dependentSchemas`, `allOf`, `anyOf`, `oneOf`, `not`, `if`, `then`, `else`, `$ref`, `$id`, `$anchor`, `$dynamicAnchor`, `$dynamicRef`, `unevaluatedProperties`, `unevaluatedItems` | | translated as an opaque predicate | `uniqueItems`, `minContains`, `maxContains`, a fractional `multipleOf`, `patternProperties` past four patterns or in a schema past valgebra's limit, a `propertyNames` reading more than words that is neither a boolean schema nor a list of names, and `oneOf` and a `$ref` to a definition that does not reach itself in a schema past valgebra's limit with keys read by predicate too | | annotations | `title`, `description`, `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `format`, `contentEncoding`, `contentMediaType`, `contentSchema`, `$schema`, `$vocabulary`, `$comment`, `$defs`, `definitions` | | refused | `$recursiveRef`, `$recursiveAnchor`, `additionalItems`, `dependencies` | `$ref` resolves against the base URI it sits under, as draft 2020-12's section 8.2 states: `$id` sets the base of its resource, and the reference names a resource of the document by its URI, then a schema in it by a JSON pointer or by an `$anchor`. A document the caller supplies in `compile_schema(schema, documents={uri: document})` is a resource at its URI, read in its own dialect, or in the compiled document's where it declares none. The compiled document names its own URI, and a document supplied at that URI is not read. A URI two schema objects of one document claim, and an anchor two of one resource set, name neither: a reference to one is refused, and a document that names neither compiles. Of two documents, the one supplied at a URI names it, then an embedded `$id` of the document supplied last. A reference to any other document is refused and never fetched, and so is an embedded resource declaring another `$schema`. An older draft's `$id` fragment that is a plain name is the `$anchor` it names. `$dynamicRef` reads the dynamic scope across every document, as draft 2020-12's sections 7.1 and 8.2.3.2 state it, and a draft 2019-09 `$recursiveRef: "#"` is the `$dynamicRef: "#"` that reads the dynamic anchor with no name `upgrade` writes for `$recursiveAnchor: true` on a resource's root, the correspondence the draft 2020-12 release notes give. A keyword outside the vocabularies is an annotation, as draft 2020-12 says to treat it, and `Compiler.ignored` records it: `x-label` or OpenAPI's `nullable` assert nothing. Two draft-07 keywords that 2020-12 removed, `additionalItems` and `dependencies`, are refused in a 2020-12 schema rather than ignored: a schema carrying them was written to a draft where they assert, and ignoring them would admit values its author meant to refuse. In a draft-07 schema `upgrade` translates them. A `pattern` is read by translating it into valgebra's dialect, and one the translation cannot write, a lookaround past the pattern's start or a backreference, refuses its schema: 5 of JSONSchemaBench's 9558. A second engine reading ECMA-262 for those alone, as a predicate, would split this package's reading of a pattern in two, the translation's and the engine's, whose agreement nothing tests past the patterns it takes, and would make a package of Python over valgebra carry a native dependency for them. Refusing a schema it cannot evaluate is what the specification's next release requires. ## Differences ledger | what | the specification | `jsonschema` 4.26.0 | this package | why | | --- | --- | --- | --- | --- | | `pattern` classes `\d`, `\w`, `\s`, `.`, boundaries `\b`, `\B` | ECMA-262: ASCII digits and word characters, ECMA-262 white space, any character but four line terminators, boundaries of ASCII word characters | Python's `re`: Unicode classes | ECMA-262 | the specification; on `optional/ecmascript-regex` `jsonschema` passes 42 of 74, this package 74 of 74 (`tools/suite.py --reference`) | | `$` before a final newline | no match | match | no match | the specification | | an escape of punctuation ECMA-262 leaves undefined under the `u` flag (`\:`, `\-` outside a class), a lone `]` or `}`, a `{` that opens no count | a pattern with one is not valid under `u`; Annex B reads the character | the character | the character, the rest of the pattern as under `u` | every dialect reads the character: Annex B, Python's `re` and valgebra's engine; Annex B reads the rest of such a pattern by UTF-16 code units, where `u` reads code points. 34 of the corpus's 2471 patterns hold one; any other construct invalid under `u` is refused | | fractional `multipleOf` | the decimal numbers written | binary floats: `0.0075` is not a multiple of `0.0001` | exact rationals: a value's shortest decimal, an integral value its integer | the specification; an integral value read as its integer agrees with an integral step's reading, as it must, since a multiple of 3 is one of 1.5 | | a number written with a fraction or an exponent: a bound, a constant | the decimal number written | the double `json.loads` returns | the double `json.loads` returns | the universe is what `json.loads` returns: `{"maximum": 1e23}` refuses `10**23`, since `1e23` parses to 99999999999999991611392 | | NaN, which `json.loads` returns for the token `NaN` | no JSON value: RFC 8259 §6 permits no NaN | a number | a value of no schema | the specification: a relation is about JSON values, and a NaN outside every bound would refute `{"type": "number"}` below `{"anyOf": [{"maximum": 10}, {"minimum": 5}]}`, which every number satisfies | | a string holding a lone surrogate, which `json.loads` returns for `"\udc00"` | a pattern searches its code units | Python's `re` searches its code points | no pattern matches it, and a property name holding one is refused | valgebra's engine reads Unicode text, and such a string is none; RFC 8259 calls its behavior unpredictable | | `integer` in a draft-04 schema | a number written without a fraction or an exponent: `1.0` and `1e300` are none | the same | an integral number, as draft 2020-12 reads `integer`: `1.0` and `1e300` are integers | draft-04's `integer` is a property of a number's spelling, while its own equality makes `1` and `1.0` one value, so it is no set of JSON values; every leaf here holds every spelling of one value, which is what a relation between two sets reads, and the reading by value is the one later drafts give `integer` | | integral constants above 2\*\*53 | one number each | one number each | one number each, its float spelling only when the float is the same number | `9007199254740993` and `9007199254740992.0` are two numbers | | `format: hostname` under `assert_format`, on an `xn--` label | the label is an IDNA A-label, so its Punycode and what it decodes to are read | not read | the label as it is spelled: 23 of the suite's 66 cases, each of them invalid and admitted | reading a label takes IDNA2008's tables, a package of their own and no dependency here | | `additionalItems`, `dependencies` in a 2020-12 schema | not keywords: annotations | annotations | refused | see the inventory | | a document supplied at the compiled document's own URI | no URI identifies two schemas, and a validator SHOULD raise an error where two claim one (section 9.1.2) | the compiled document: `referencing` registers the root at its `$id` over the registry's resource | the compiled document; the supplied one is not read | section 9.1.1 makes the root's `$id` its canonical URI, and a registry a caller passes may hold the compiled document; JSONSchemaBench's CloudFormation schema declares the draft-04 meta-schema's URI as its `$id`, the corpus study supplies that meta-schema, and the schema's 9092 references name its own definitions | | a URI two schema objects of one document claim, or an anchor two of one resource set | no URI identifies two schemas, and a validator SHOULD raise an error where two claim one (section 9.1.2); two anchors of one name are undefined, and an implementation MAY raise one (section 8.2.2) | one of the two: the first written of two siblings, and of two under different keywords, one that changes with Python's string hashing (`PYTHONHASHSEED`) | neither: a `$ref` or `$dynamicRef` naming it is refused | the error the specification asks for, raised where a reference meets the ambiguity: 15 JSONSchemaBench documents hold such a URI, none names it, and each compiles; the semantics of Attouche et al. (POPL 2024, section 3) reads a URI as naming one schema | | a draft 2019-09 `$recursiveRef` whose dynamic scope enters a resource without `$recursiveAnchor` between two with it | the outermost schema in the scope setting it (section 8.2.4.2.2) | the outermost of the resources setting it entered since the last one without it | the outermost schema in the scope setting it | the specification, and the draft 2020-12 release notes, whose `$dynamicRef` works the same way | ## The valgebra boundary `valgebra_jsonschema/_valgebra.py` is the only module that imports valgebra, and the derived forms the compiler needs — the conditional, key presence, exactly-one-of, a keyword's scope, a fixed-length list, the callback path — are written there once, as the recipes of valgebra's documentation. `tests/test_boundaries.py` fails if any other module imports valgebra. # Results Every number below is printed by a committed command and recorded as counts in `docs/studies/`; each tool's `--check` reruns it. ## The compiler ``` uv run python tools/suite.py --check docs/studies/json-schema-test-suite.json uv run python tools/suite.py --draft 2019-09 --check docs/studies/json-schema-test-suite-draft2019-09.json uv run python tools/suite.py --draft 7 --check docs/studies/json-schema-test-suite-draft7.json uv run python tools/suite.py --draft 6 --check docs/studies/json-schema-test-suite-draft6.json uv run python tools/suite.py --draft 4 --check docs/studies/json-schema-test-suite-draft4.json ``` Draft 2020-12, with the four optional files on regular expressions and large numbers: 1393 of the 1393 cases run pass; 5 are skipped, each naming a custom meta-schema as its dialect. Through `upgrade`: draft 2019-09, 1256 of the 1256 cases run pass, 5 skipped, the same five; draft-07, 929 of the 929 cases run pass, 0 skipped; draft-06, 841 of the 841 cases run pass, 0 skipped; draft-04, 618 of the 618 cases run pass, 0 skipped. A case's remote documents are the suite's `remotes/`, vendored, and the drafts' meta-schemas from the `jsonschema-specifications` package, passed as `documents`. See [what the compiler page measures](). ## `format`, on request ``` uv run python tools/suite.py --draft format --check docs/studies/json-schema-test-suite-format.json ``` The nine formats `assert_format` reads, on the suite's `optional/format` files: 471 of the 494 cases pass. Each of the 23 that do not is a hostname, an `xn--` label the suite refuses for what it decodes to, which the ledger records. ## Real-world schemas ``` uv run python tools/corpus.py --check docs/studies/jsonschemabench.json ``` The compiler on JSONSchemaBench (Geng et al. 2025, MIT), fetched at commit `9a94995b9279` into `results/` and never vendored: 9558 schemas from GitHub, the JSON Schema Store, Kubernetes, Snowplow, the Washington Post and function-calling data, in drafts 2020-12, 2019-09, 07, 06 and 04. Each compiled schema is checked on the values drawn from it and the generic values `tools/corpus.py` lists, against the `jsonschema` package's validator for its draft. | subset | schemas | compiled | refused | crashed | timed out | values | disagreed | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | Github\_easy | 1943 | 1934 | 9 | 0 | 0 | 86280 | 2 | | Github\_hard | 1240 | 1223 | 17 | 0 | 0 | 51523 | 0 | | Github\_medium | 1976 | 1965 | 11 | 0 | 0 | 87753 | 0 | | Github\_trivial | 444 | 444 | 0 | 0 | 0 | 17806 | 10 | | Github\_ultra | 164 | 164 | 0 | 0 | 0 | 6493 | 0 | | Glaiveai2K | 1707 | 1689 | 18 | 0 | 0 | 80303 | 0 | | JsonSchemaStore | 492 | 478 | 14 | 0 | 0 | 19646 | 1 | | Kubernetes | 1064 | 1064 | 0 | 0 | 0 | 44504 | 0 | | Snowplow | 403 | 400 | 3 | 0 | 0 | 18538 | 0 | | WashingtonPost | 125 | 125 | 0 | 0 | 0 | 5364 | 0 | | all | 9558 | 9486 | 72 | 0 | 0 | 418210 | 13 | - 9486 of the 9558 schemas compile, none crashes, none times out. Of the 72 refused, 58 use `dependencies` or `additionalItems` in a schema declaring no older draft, 1 a reference cycle under no constructor, which denotes no set, 5 hold a pattern outside valgebra's regex dialect, 4 of them a lookahead past the pattern's start and 1 a backreference, and 7 a `$ref` to nothing in the document; the rest are listed by `tools/corpus.py`. A schema may name a draft's meta-schema, which both the compiler and the `jsonschema` package read from the `jsonschema-specifications` package. - Membership differs from the package's on 13 of the 418210 values, each a reading the ledger records: 11 are an integral float, `1e300` or `-0.0`, under a draft-04 `integer`, and 2 are `"\n"` under a pattern ending in `$`, which Python's `re` matches before a final newline. - The 12 schemas past valgebra's node limit compile with each `oneOf` read as its union met with a count of the branches that hold, and each reference to a definition that does not reach itself checked through the definition's own set, each within the time the study allows a schema, `TIMEOUT` in `tools/corpus.py`: the `timed out` column is 0 in every subset. ## Inclusions against the containment test suite ``` uv run python tools/containment.py --check docs/studies/containment.json ``` The JSON Schema containment test suite (Attouche et al. 2021, MIT), fetched at commit `446fb41c527c` into `results/` and never vendored: pairs of schemas generated from the JSON-Schema-Test-Suite, each labeling whether the first is a subset of the second, the converse, or both. A labeled direction is a question, asked of valgebra with `relation_to`, or, where the first schema spells its values out (`constants`), of each value's membership in the second; the older drafts are read through `upgrade`, and the only optional files read are the four the suite study runs. | draft | questions | refused | proven | refuted | undecided | proven against the label | refuted against the label | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | 2020-12 | 3645 | 8 | 2480 | 1082 | 75 | 4 | 20 | | 7 | 2788 | 12 | 1907 | 842 | 27 | 1 | 7 | | 6 | 2524 | 12 | 1718 | 768 | 26 | 1 | 7 | | 4 | 1933 | 4 | 944 | 932 | 53 | 0 | 344 | - A proof stands against a label only where the label is wrong, as a refutation does: 7049 proofs of the 10890 questions, 6 against one. Two kinds of wrong label lie in a proof's direction. In `nonvalid/ref.json` the generator writes a `not` around the properties of the suite's tree of nodes and labels the tree it lists outside, where the `jsonschema` package admits it, and the tree's membership proves it inside: 3 proofs, one per draft but 04. In draft 2020-12's `nonvalid/dynamicRef.json` it labels `["foo", "bar"]` outside two schemas the official suite's own `dynamicRef.json` holds it valid in: 2 proofs. There too it puts the `$ref` of the suite's relative dynamic reference under a `not`, which the reference reaches again through the dynamic scope, and labels the object the suite holds valid outside it, where the `jsonschema` package admits it: 1 proof. A proof against a label in any other category fails `tests/test_docs.py`. - Each of the 378 refutations against a label is a wrong label, and the `jsonschema` package's validator for the draft admits the witness to one side and refuses it from the other. In every draft the generator writes two kinds. In `universal/items.json`, `universal/ref.json` and, in draft 2020-12, `universal/unevaluatedItems.json`, `universal/unevaluatedProperties.json` and `universal/dynamicRef.json` it leaves keywords outside the `not` it writes, such as `type` and `items: false`, or `type` and `required`, so the schema it labels universal leaves out a value: `1`, `{}`, `1.5` or `{"prop1": 1}`. In `unsatisfiable/ref.json` and `unsatisfiable/id.json`, and in draft 2020-12's `unsatisfiable/anchor.json`, it renames a `$ref`, an `$id` or an `$anchor` inside an `enum` or `const` value as well as in the schema, so the two copies differ and the schema it labels empty holds the value it lists, such as `{"$ref": "#/allOf/0/$defs/a_string"}`; in `universal/ref.json`, `universal/id.json` and draft 2020-12's `universal/anchor.json` the same renaming leaves the value its `not` lists outside the schema it labels universal, such as `{"$ref": "#/anyOf/1/$defs/a_string"}`. In draft 2020-12's `unsatisfiable/dynamicRef.json` it renames a copy and writes no `not`, so the meet it labels empty holds `[]`; in the same file it meets the suite's relative dynamic reference with a renamed copy whose `not` wraps the copy's `extended`, which the copy's own `$dynamicAnchor` reaches again, and labels the meet empty, where it holds `{"bar": {"baz": {}}}`. In `unsatisfiable/ref.json` it meets the suite's tree of nodes with a renamed copy whose `not` wraps the copy's properties, and labels the meet empty, where it holds `{"meta": "a", "nodes": [{"value": 1, "subtree": {"meta": "a", "nodes": []}}]}`: the inner tree's empty `nodes` is a list of the copy's nodes, so that tree is outside the copy, the node holding it outside the copy's nodes, and the outer tree inside it: 1 refutation per draft. In draft-04, 337 more pairs put `const`, which draft-06 added, in a draft-04 schema: the draft reads it as an annotation, so the first schema admits every value. - A question is refused where the compiler refuses a schema of its pair, as [the inventory]() lists; an undecided one is kept and counted. # Reference # API reference The package's public names, its `__all__`, each importable from `valgebra_jsonschema`, and the sampler a study draws members with. ### valgebra\_jsonschema JSON Schema, read into valgebra's sets over the values `json.loads` returns. #### ANNOTATIONS ``` ANNOTATIONS = frozenset( { "$schema", "$vocabulary", "$comment", "title", "description", "default", "examples", "deprecated", "readOnly", "writeOnly", "format", "contentEncoding", "contentMediaType", "contentSchema", "$defs", "definitions", } ) ``` #### ARRAY ``` ARRAY = Validator([JSON]) ``` #### BOOLEAN ``` BOOLEAN = Validator(bool) ``` #### INTEGER ``` INTEGER = intersection( union(int, Annotated[float, MultipleOf(1)]), NOT_BOOL ) ``` #### ITEM ``` ITEM = _Item() ``` #### JSON ``` JSON = recursive( lambda j: union( None, bool, int, JSON_FLOAT, str, [j], {str: j} ) ) ``` #### NULL ``` NULL = Validator(None) ``` #### NUMBER ``` NUMBER = intersection(union(int, JSON_FLOAT), NOT_BOOL) ``` #### OBJECT ``` OBJECT = Validator({str: JSON}) ``` #### REFUSED ``` REFUSED = frozenset( { "$recursiveRef", "$recursiveAnchor", "additionalItems", "dependencies", } ) ``` #### STRING ``` STRING = Validator(str) ``` #### SUPPORTED ``` SUPPORTED = frozenset( { "$id", "$anchor", "$dynamicAnchor", "$ref", "$dynamicRef", "prefixItems", "items", "contains", "additionalProperties", "properties", "patternProperties", "dependentSchemas", "propertyNames", "if", "then", "else", "allOf", "anyOf", "oneOf", "not", "type", "const", "enum", "multipleOf", "maximum", "exclusiveMaximum", "minimum", "exclusiveMinimum", "maxLength", "minLength", "pattern", "maxItems", "minItems", "uniqueItems", "maxContains", "minContains", "maxProperties", "minProperties", "required", "dependentRequired", "unevaluatedProperties", "unevaluatedItems", } ) ``` #### Tool A tool's two contracts. A tool with no `outputSchema` promises no structure. ##### name ``` name: str ``` ##### arguments ``` arguments: Validator[Any] ``` ##### result ``` result: Validator[Any] | None ``` ##### \_\_init\_\_ ``` __init__( name: str, arguments: Validator[Any], result: Validator[Any] | None, ) -> None ``` #### Compiler Compile one root document, resolving `$ref` against it. A reference is compiled as a `valgebra.recursive` fixpoint over its target, so a schema that names itself (a tree, a linked list) compiles to the recursive set it denotes rather than looping. A target is compiled once and reused. ##### root ``` root = root ``` ##### documents ``` documents: Mapping[str, object] = documents or {} ``` ##### by\_clauses ``` by_clauses = by_clauses ``` ##### by\_predicate ``` by_predicate = by_predicate ``` ##### assert\_format ``` assert_format = assert_format ``` ##### opaque ``` opaque: set[str] = set() ``` ##### ignored ``` ignored: set[str] = set() ``` ##### patterns ``` patterns: dict[str, set[str]] = {} ``` ##### asked ``` asked: Asked = {} ``` ##### \_\_init\_\_ ``` __init__( root: object, *, assert_format: bool = False, by_clauses: bool = True, by_predicate: bool = False, documents: Mapping[str, object] | None = None, ) -> None ``` ##### guard ``` guard(family: str, refined: object) -> Validator[Any] ``` Return the values outside the family's kind, or `refined` ones. Where the schema's own `type` already confines the instance to the family, the guard's other half is empty after the meet with `type`, so it is left out: the set is the same and every decision over it is cheaper. ##### reworded ``` reworded( failure: Mapping[str, object], ) -> dict[str, object] ``` Return a failure valgebra reports, each pattern it names in the schema's text. valgebra matches a `pattern` in its own dialect, unanchored and its classes written out, and names the text it was given: `a string matching '(?s:.*)(?:^[\x{61}-\x{66}]{2}$)(?s:.*)'`. Where this compiler wrote that text for one schema text alone (`patterns`), the failure's `expected` names the schema's, `a string matching '^[a-f]{2}$'`, and so does its `message`, where the expected set's span occurs once. A text two patterns translate to, as `\d` and `[0-9]` do, and a part a lookaround is read as are named as valgebra gave them, and so is every other key. A literal of the schema spelling such a label is renamed with it. ##### compile ``` compile(schema: object) -> Validator[Any] ``` Return the set of JSON values `schema` admits. ##### compile\_body ``` compile_body(schema: object) -> Validator[Any] ``` Return a set that agrees with `schema`'s on every JSON value, to complement. It is the meet of the schema's keywords without the universe `compile` meets it with. Every complement the compiler writes is met with a set inside the universe, where `~(P & JSON)` and `~P` agree, and valgebra's set reading declines the complement of a meet holding the recursive universe where it decides the bare one. ##### compile\_with\_body ``` compile_with_body( schema: object, ) -> tuple[Validator[Any], Validator[Any]] ``` Return `schema`'s set and its body (`compile_body`), read in one pass. A branch of a `oneOf` and the condition of an `if` are used whole and complemented both; a pass for each would compile a `oneOf` nested `d` levels down `2**d` times. ##### ref ``` ref( reference: str, *, dynamic: bool = False ) -> Validator[Any] ``` Return the set a reference names, resolved against the base URI it sits under. A target that reaches itself through references is a `valgebra.recursive` fixpoint; any other is compiled in place. Each fixpoint is a definition, and valgebra admits 128 in one set, so the 200 `$defs` a generated schema may carry are compiled inline, not as 200 definitions. A `dynamic` reference names what `dynamic_target` returns, and a target the dynamic scope chose is a fixpoint whether or not its references reach it statically: a `$dynamicRef` the scope redirects may reach it again. A set is kept for reuse only when it holds no placeholder of a fixpoint still being built: the placeholder stands for its fixpoint inside that fixpoint's builder alone, and a set built around one means something else, or nothing, anywhere else. Under the dynamic scope it is kept for the scope it is compiled in, the one entering the target's own resource, as `_compile_object` enters it. ##### dynamic\_target ``` dynamic_target( reference: str, base: str | None = None ) -> tuple[tuple[object, str], bool] ``` Return the schema a `$dynamicRef` names, and whether the dynamic scope chose it. It resolves as `$ref` does, and where that target sets a `$dynamicAnchor` of the fragment's name, the scope's binding of the name replaces it (draft 2020-12, section 8.2.3.2). A name at most one schema object of every document sets needs no scope. The empty name is the one `upgrade` writes for draft 2019-09's `$recursiveAnchor`, and its `$recursiveRef`, `"#"`, the one reference that reads it. ##### closed ``` closed(schema: object) -> Callable[[], Validator[Any]] ``` Return a getter of the set `schema` compiles to, for a callback to check against. An opaque predicate's callback runs at membership time, outside every fixpoint's builder, where a set holding the placeholder of a fixpoint then being built means nothing. Such a set is compiled again, by a fresh compiler, the first time the callback asks for it; any other is the set compiled now. ##### compile\_closed ``` compile_closed( schema: object, ) -> tuple[Validator[Any], Callable[[], Validator[Any]]] ``` Return the set `schema` compiles to now, and the getter `closed` returns. ##### dynamic\_anchors ``` dynamic_anchors(name: str) -> int ``` Return how many schema objects of every document set `$dynamicAnchor` `name`. ##### evaluations ``` evaluations(schema: dict[str, Any]) -> list[Case] ``` Return the cases a schema object being compiled evaluates on. What `unevaluated*` reads is what the keywords beside it and the in-place subschemas that succeed evaluate at the instance (draft 2020-12, section 11), and which of those succeed depends on the instance. Each case is the sets an instance of it is in, and what is evaluated there. `allOf` multiplies its subschemas' cases, `anyOf` takes every nonempty set of branches, each holding, `oneOf` each branch holding, `if` holding with `then` or failing with `else`, a `dependentSchemas` entry its key present, a `$ref` its target's cases; `not` evaluates nothing. An instance may be in several cases, but each holds of branches that hold on it, so the case of every branch that holds evaluates the most, and an `unevaluated*` holding on any case holds on that one: the union is exact. `if` is the exception, its two outcomes evaluating apart, so each states its own. A `$ref` that reaches itself at one instance, an `anyOf` of more than `_BRANCHES` branches and more than `_EVALUATION_CASES` cases are refused. ##### resolve ``` resolve(reference: str) -> object ``` Return the schema a reference names from the document's root, or raise `Unsupported`. ##### below ``` below(path: Sequence[str | _Item]) -> Validator[Any] ``` Return the values a member of the root holds at `path`, wherever it holds one. Each step is a key of an object, or `ITEM`, any element of an array. A schema object holds where each of its keywords does (Attouche et al. 2024, §4.5), so the values at a step are the meet of what each keyword says of them: an object's field matched by `properties` or a pattern satisfies that subschema (Attouche et al. 2024, §4.4), and one neither matches satisfies `additionalProperties`; an array's element satisfies `items` or the `prefixItems` entry at its place. `allOf` meets its members' readings and `anyOf` and `oneOf` unite their branches' (Attouche et al. 2024, §4.3); a `$ref` reads its target, resolved against the base URI it sits under (Attouche et al. 2024, §4.6). `if` with `else` unites the two branches; a `type` naming no object, or array, and a `propertyNames` refusing the key, leave no value; `enum` and `const` read their listed values' own. The set is an upper bound: a keyword it does not read here, as `not`, a lone `if`, `$dynamicRef` or `unevaluatedProperties`, narrows nothing, and the set holds every value a member holds at `path`. Raises `Unsupported` where a subschema it reads is refused, as `compile` does. #### Interval A numeric schema that is a range and nothing more: its kind, bounds and step. A missing bound is None. A bound is the exact value of the number `json.loads` returned, which is what membership compares against: `1e23` is the double 99999999999999991611392, not 10\*\*23, and `0.1` is the double nearest one tenth. A reading of the decimal written would prove inclusions membership refutes, at the integers between the two. `step` is an integral `multipleOf`: the range then holds only the multiples of it, which are integers whatever `type` says. ##### integer ``` integer: bool ``` ##### low ``` low: Fraction | None = None ``` ##### low\_open ``` low_open: bool = False ``` ##### high ``` high: Fraction | None = None ``` ##### high\_open ``` high_open: bool = False ``` ##### step ``` step: int | None = None ``` ##### \_\_init\_\_ ``` __init__( integer: bool, low: Fraction | None = None, low_open: bool = False, high: Fraction | None = None, high_open: bool = False, step: int | None = None, ) -> None ``` #### Unsupported Bases: `ValueError` A schema uses a keyword or form this compiler does not translate. #### UnsupportedDialect Bases: `Unsupported` A document's `$schema` names a dialect this compiler does not read. The Model Context Protocol has an implementation fail on such a schema with an error saying the dialect is not supported, so a server can tell it from a refused keyword. #### read\_tool ``` read_tool( spec: Mapping[str, Any], *, assert_format: bool = False ) -> Tool ``` Read one entry of a server's tool list into its two contracts. Raises `Unsupported` for an `inputSchema` that is missing or names no object, and for anything `compile_schema` refuses, and `UnsupportedDialect` for a dialect it does not read. `assert_format` reads as it does there. #### branches ``` branches(schema: object) -> list[object] | None ``` Return the subschemas whose union `schema` is, when it is a union and nothing more. An `anyOf` with no other assertion is the union of its branches, and a `type` list with nothing else the union of its kinds; a branch that is itself such a union is flattened. Each branch compiles, against the same root, to a set whose union is the one `schema` compiles to, so a question about the union can be asked of each branch. #### compile\_schema ``` compile_schema( schema: object, *, assert_format: bool = False, documents: Mapping[str, object] | None = None, ) -> Validator[Any] ``` Compile a root schema document, upgrading a 2019-09, -07, -06 or -04 one first. A document with no `$schema` is draft 2020-12, as the Model Context Protocol states, and one naming any other dialect raises `UnsupportedDialect`. With `assert_format`, a `format` this package reads asserts rather than annotates, and any other raises `Unsupported`. `documents` maps a URI to the document a reference to it names; one declaring no `$schema` is read in the dialect of the document compiled. #### compile\_with\_fallbacks ``` compile_with_fallbacks( root: object, schema: object, *, assert_format: bool = False, documents: Mapping[str, object] | None = None, ) -> tuple[Compiler, Validator[Any]] ``` Return a compiler of `root` and the set `schema` compiles to. It is read the first way `_FALLBACKS` lists that stays inside valgebra's limit. #### constants ``` constants(schema: object) -> list[Any] | None ``` Return the JSON values `schema` admits where it spells them out, or `None`. A schema of one `const`, one `enum`, or an `anyOf` or `oneOf` of such schemas, beside annotations alone, admits the values it lists, and `oneOf` those exactly one branch lists under JSON's equality; `false` admits none. A finite set lies inside another exactly where each of its values does, so membership relates such a schema to any other, predicates included \[FCB08, §4.1\]: every leaf answers a value's spellings alike, and the compiler's predicates answer from the value alone. A draft-04 `const` is an annotation, so the document `upgrade` returns is the one to read. #### ecma ``` ecma(pattern: str) -> str ``` Rewrite an ECMA-262 pattern into valgebra's regex dialect, with ECMA-262's meaning. The pattern is read as ECMA-262 reads it under the `u` flag and written back with nothing valgebra's engine could read otherwise: every literal is a `\x{...}` code point, every class a list of code point ranges and General\_Category or Script property escapes, `\d`, `\w`, `\s` and their complements the ASCII and ECMA-262 ranges they denote there, `.` every code point but ECMA-262's four line terminators, and `\b`, `\B` boundaries of its ASCII word characters. Annex B's literals, which every dialect reads as the character -- an escape of punctuation, a lone `]` or `}`, a `{` that opens no count -- are read so. Every other construct ECMA-262 refuses under `u` is refused: an escape it does not define, a quantifier with nothing to repeat, a group form other than `(?:`, a lookaround or a named group, a class range with a class escape at an end. A construct valgebra's engine refuses -- a lookaround, a backreference -- is refused when the set is built. #### finite ``` finite( schema: object, root: object = None, depth: int = 0 ) -> list[Any] | None ``` Return every JSON value `schema` admits when it lists them, else None. A schema with `enum` or `const`, a `boolean` or `null` type, or an `allOf` holding one of these admits only the values listed there, filtered by the rest of the schema. Each integral number is listed in both spellings, `1` and `1.0`, which are one JSON number and two Python values, and a zero also as `-0.0`: membership compares a float by value, so `-0.0` lies wherever `0.0` does, and a predicate written in Python can still tell the two apart. The list is what lets a cell inside such a schema be decided by checking each value rather than by asking about the cell's set. A listed array or object is not enumerated: each number inside it has its spellings too, and a list missing one of the combinations would let a cell holding it be called empty. Such a schema returns None and its cells are left to valgebra, as does an `allOf` nested past valgebra's depth limit, which no compiled schema holds. #### interval ``` interval(schema: object) -> Interval | None ``` Return the range a schema denotes when it is `type`, bounds and a step alone. A fractional `multipleOf` is not a step: it is opaque (`_multiple_of`), so a schema carrying one is not a range. Nor is one with a non-finite bound, which `json.loads` returns for `1e400`: no exact rational denotes it. #### json\_key ``` json_key(value: Any) -> object ``` Return a hashable key under which two JSON values are equal iff JSON Schema says so. Numbers compare by exact value (`1` equals `1.0`) and never equal a boolean; arrays compare in order and objects as sets of key-value pairs. #### older ``` older(schema: object) -> int | None ``` Return the older draft -- 2019, 7, 6 or 4 -- a document's `$schema` names, or None. #### spellings ``` spellings(value: float) -> list[float] ``` Return the Python values that spell one JSON number: `1` and `1.0`. An integer has a float spelling only when the float is the same number. Above 2\*\*53 a float rounds, so `9007199254740993` and `9007199254740992.0` are two numbers, and past the float range there is no float spelling at all. #### upgrade ``` upgrade(schema: object, draft: int = 7) -> object ``` Rewrite an older schema into the draft 2020-12 one with the same meaning. The keywords whose meaning changed: an `items` array is `prefixItems`, with `additionalItems` as `items`; `dependencies` splits into `dependentRequired` and `dependentSchemas`; and a `$ref` overrides its siblings, so they are dropped, but for `definitions` and `$defs`, which a pointer may name. `definitions` keeps its name, so every JSON pointer into the document still resolves. A keyword the draft does not know is an annotation there and is dropped (`_UNKNOWN`). Draft-04 also writes `exclusiveMinimum` and `exclusiveMaximum` as flags on `minimum` and `maximum`, and `$id` as `id`. An `$id` fragment that is a plain name names its schema object as draft 2020-12's `$anchor` does, and is written as one; any other fragment names nothing a reference resolves to. Only the keywords that hold subschemas are descended into: a property named `items` is a name, not a keyword. A keyword holding a value of the wrong shape is copied as it is, for the compiler's shape check to name. Draft 2019-09 differs less: a `$ref` keeps its siblings, `dependencies` is no keyword, and the array `items` is the one change of meaning, beside its recursion. Its `$recursiveAnchor: true` is a `$dynamicAnchor` whose name is empty, on the root of a resource, and its `$recursiveRef: "#"` the `$dynamicRef: "#"` that reads it, as the draft 2020-12 release notes say the two pairs agree. A `$recursiveAnchor: true` starting no resource, and a `$recursiveRef` of any other value, are refused. The empty name is one no draft 2020-12 anchor may spell, so no anchor of a document meets it, and it is written as a `str` no JSON text parses to, which the compiler admits there alone. ### valgebra\_jsonschema.sample.Sampler Draw candidate values for the schemas of one document, from one seeded stream. #### root ``` root = root ``` #### rng ``` rng = rng ``` #### depth ``` depth = depth ``` #### documents ``` documents = documents ``` #### compiler ``` compiler = Compiler(root, documents=documents) ``` #### \_\_init\_\_ ``` __init__( root: object, rng: Random, *, depth: int = 4, documents: Mapping[str, object] | None = None, ) -> None ``` #### draw ``` draw(schema: object, tries: int = 40) -> list[Any] ``` Return up to `tries` distinct candidates that the compiled schema admits.