JSON Schema Diff

When a JSON Schema changes — the contract for an API body, an event, a config file — the question is whether anything that worked before will now break. This tool compares two versions keyword by keyword and sorts every change by which way it cuts. Narrower changes make the schema accept less: a new required field, a lower maxLength, a removed enum value; data that passed before may now be rejected, which breaks whoever sends it. Wider changes make it accept more: a new type, an extra enum value, a dropped limit; code that reads the data and relied on the old limits may now see values it never handled. Changes whose direction cannot be known from the schemas alone are marked for a person to check, and annotations such as descriptions are marked as documentation only.

1. Paste the old schema on the left and the new one on the right, or open the files.
2. Read the list: each change shows its kind, the JSON Pointer to where it is, and what changed.
3. Filter by kind — for a request body, the narrower changes are the ones that break clients; for a response, the wider ones.
4. Copy the list as text for a pull request or a release note.

• $ref is compared as written, not resolved: a reference that now points to a different definition is flagged, and each definition under $defs is compared on its own. Follow the flagged reference to judge it.
• allOf, anyOf and oneOf are compared position by position. A change inside oneOf is marked “check”, because narrowing one branch can make a value match exactly one branch where it used to match two — which oneOf then accepts.
• format only rejects values when the validator is set to assert formats (off by default from draft 2019-09), so a format change is reported with that caveat.
• Drafts 4 to 2020-12 are understood, including draft 4’s boolean exclusiveMinimum, which is flagged for a closer look. Keywords outside the specification (x-… extensions, vocabulary of your own) are listed as changes to check by hand, never ignored.
• Schemas up to 5 MB each.
• Everything runs in your browser. Schemas often describe internal systems; nothing you paste is uploaded, stored or logged.

It depends on additionalProperties. If the object was open (the default), describing a new property constrains it, so the change is narrower — a client that already sent that property with a different type would now fail. If the object was closed with additionalProperties: false, the property was rejected before and is allowed now, so the change is wider.

For data clients send — request bodies, query parameters — narrower changes can break them. For data clients receive — responses, webhooks, events — wider changes can, because a client may not handle a new enum value or a field that can now be null. A change marked “check” could go either way.

Every integer is a number, so a schema that accepts any number accepts everything the integer schema did, plus 1.5. The reverse, number → integer, is narrower.

It compares them as they are written. To check that a schema itself is well formed, or that data matches it, use the JSON Schema Validator.