json‑schema‑compat

What this tool does — and its honest limits

What it does. json-schema-compat compares two versions of a JSON Schema and returns a verdict — compatible, breaking, or needs manual review — with every detected change listed by JSON-pointer path (/properties/email/type) so you can point at the exact line in review. The frame is always reader-backward compatibility of stored documents: a document that validated under the old schema must stay valid under the new one. That is the right question when you own the writers and worry about stored data — API request bodies, event payloads, config files, database document validators. Forward compatibility (old readers against new documents) is a different question and is deliberately not computed.

A review rail, not a prover. This is a conservative checker: a “compatible” verdict is only ever produced from flat, covered keywords, and anything the checker cannot decide with certainty lands in needs review — never silently assumed safe. Concretely: composition keywords (allOf/anyOf/oneOf/not/if) are never composed, so a schema built mostly out of them will come back “review” with little detail — that is intentional, not a bug. Uncovered keywords (patternProperties, dependentRequired, …) are flagged by name rather than ignored.

Honest limits. There is no regex analysis: comparing the languages of two regexes is undecidable in general, so any change to a pattern’s value goes to review even when it plainly widens (^a$ → ^a?$). The one pattern change that needs no regex reasoning — dropping the keyword altogether — is a strict relaxation and is reported safe. There are no format semantics (any format change is review, including removing one), and external $refs are never fetched — zero network — so they route to review too. Internal #/… refs are resolved, so a change to a referenced definition is classified normally.