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.patternsholds 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 andITEM, any element of an array, read through every keyword that narrows them and a$refresolved 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 throughpropertiesalone or a$reffrom the document's root, reads less, or another resource's schema.
Fixed¶
Samplerdraws a conjunction merged keyword by keyword: anallOfwith the schema around it, ananyOforoneOfbranch with its siblings, and a reference's target with the keywords beside it,propertiesmet key by key,requiredunited,typekeeping the kinds both name and each bound the tighter. A member'spropertiesreplaced the outer schema's, so a record anallOfnarrows drew no member. A required keypropertiesdoes not name is drawn fromadditionalProperties, a pattern holding a group, an alternation or.is drawn inside it, and a schema naming notypedraws 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.ymlas written underzensical build --strict: its own search, the redirects from each page's former address,llms.txtandllms-full.txt, the Mermaid diagrams and the API reference through the mkdocstrings Python handler. No page moves. -
A
propertyNamesspelling its names out, anenum, aconst, or ananyOforoneOfof them, compiles to the closed record of those keys, each optional, rather than to an opaque predicate:{"propertyNames": {"enum": ["k", "j"]}}issubsetof the object whosepropertiesarekandjwithadditionalProperties: false, and the converse too, where both readundecided. Membership is unchanged; the suite'spropertyNamescases 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
minPropertiesandmaxProperties:{"propertyNames": {"enum": ["k", "j"]}, "minProperties": 2}issubsetof the object requiringkandj, and{"required": ["k"], "maxProperties": 1}of the closed record ofk, where both readundecided. 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 aconst, which draft 4 does not have, and one in draft 2020-12'sunsatisfiable/dynamicRef.jsonon{"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.txtandllms-full.txtfor 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
Documentationlink 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_schemareads JSON Schema drafts 2020-12, 07, 06 and 04 into valgebra's sets over the valuesjson.loadsreturns, and raisesUnsupportednaming a keyword it does not read.- Draft 2019-09 reads through
upgrade, and a document naming any other dialect raisesUnsupportedDialect, a kind ofUnsupported, whose message says it is not supported. - A
$refresolves against the base URI it sits under: an embedded$idstarts 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$idfragment that is a plain name reads as the$anchorit names. A URI two schema objects of one document claim, and an anchor two of one resource set, name neither, and a$refor$dynamicRefnaming 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, andSamplertakes 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$idits canonical URI (section 9.1.1), so a document supplied at that URI is not read.$dynamicRefreads the dynamic scope across every document: where its target sets a$dynamicAnchorof 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$dynamicAnchornames its schema object as$anchordoes. Draft 2019-09's$recursiveAnchor: trueon 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.unevaluatedPropertiesandunevaluatedItemsare 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.patternPropertiesup to four patterns, and apropertyNamesof words, are clauses over keys narrowed by a pattern, so a relation reads them.propertyNames: truenames every key, andpropertyNames: falsenone, so it admits the empty object alone.- A
patternopening 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 aTypedDictnames whole. uniqueItemsis one predicate in every schema, and a fractionalmultipleOfone per step, so a schema holding either is proved below itself.oneOfleaves 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
oneOfas 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_fallbacksis the cascadecompile_schemaandSamplershare. constants(schema)lists the values a schema spells out withconst,enum, or ananyOforoneOfof 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.loadsreads one past the float range. read_toolreads an MCP server's tool listing into its two contracts.assert_format=Truereadsdate,duration,ipv4,uuid,date-time,time,email,hostnameandipv6as assertions, and refuses any otherformat. It is off by default.- The package requires valgebra 0.0.28 and below 0.0.29, since a
0.0.xminor 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
jsonschemapackage'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.