{{ summary.heading }}
{{ summary.primary }}
{{ summary.line }}
{{ badge.label }}
Use the API body, event contract, or configuration object name being reviewed.
Choose how broad the breaking-change scan should be before release review.
Keep local resolution on for schemas that use $defs, definitions, or internal reusable fragments.
Paste the schema already published to clients, producers, or stored data validators.
{{ oldFileStatus || 'Drop JSON or TXT onto the textarea.' }}
Paste the schema you plan to ship and review compatibility signals before release.
{{ newFileStatus || 'Drop JSON or TXT onto the textarea.' }}
Results update as either schema changes.
Use 50 to 500 findings; lower values keep large comparisons responsive.
rows
Leave off for release-blocker reviews; turn on when documentation drift also needs handoff notes.
Include annotation-only notes
Severity Change JSON Pointer Released Proposed Release action Copy
{{ severityLabel(row.severity) }} {{ row.change }} {{ row.pointer }} {{ row.oldValue }} {{ row.newValue }} {{ row.action }}
No compatibility findings
The current schemas did not produce ledger rows for the selected review coverage.
Area Value Evidence Next action Copy
{{ row.area }} {{ row.value }} {{ row.evidence }} {{ row.action }}
No rule summary rows
Load sample schemas or paste two valid JSON Schemas to populate this export.
Tags: Data Format, Devtools
JSON Schema Generator Generate JSON Schema from sample JSON, choose draft and inference rules, and review property ledgers before copying a validator-ready draft.
Test Data Generator Generate repeatable synthetic test data from field recipes and seeds, with CSV, JSON, NDJSON, SQL output and recipe quality checks.
Bug Report Generator Draft a tracker-ready bug report with Markdown, triage fields, a reproducibility checklist, and local privacy-pattern warnings before filing.
ENV Converter Convert .env files to YAML, JSON, runtime env, INI, and properties output with parser traces, expansion checks, and secret-like value review.
Customize
Advanced
:

JSON Schema compatibility is about the JSON values that remain valid after a contract changes. Two schema documents can look similar while accepting different data, and two documents that look different can still accept the same practical shape. The release question is usually simple to state: can older producers, clients, stored records, and replayed events still pass the proposed schema?

That question matters wherever a schema sits between independent systems. API request bodies, event payloads, webhooks, configuration files, import formats, and stored document validators all become promises once other code depends on them. Tightening a keyword too early can reject data that was valid yesterday. Relaxing a keyword can admit new values that validators accept but downstream switch statements, generated clients, reports, or database mappings still do not understand.

Instance
The JSON value being checked, such as an object, array, string, number, boolean, or null.
Assertion
A validation rule such as type, required, enum, minimum, or pattern.
Applicator
A keyword that applies subschemas, including properties, items, allOf, oneOf, and if/then.
Annotation
Metadata such as title, description, default, or examples. It can affect documentation and generated code even when validation does not change.

Most breaking changes shrink the accepted instance set. A new required property rejects objects that omit it. A removed enum value rejects values that older senders may still emit. A stricter minimum, maximum, string length, array length, uniqueness rule, or object-closure rule rejects values that previously passed. The same release can also contain relaxed changes, such as adding an optional property or widening an enum, but those are still worth reviewing when other code treats the contract as a fixed type model.

JSON Schema compatibility review A diagram showing older valid JSON values passing through a released schema and then being tested against a proposed schema with stricter required, enum, and closure rules. Released schema required: id status: draft, paid Older JSON values valid before release Proposed schema currency now required status narrowed Backward compatibility means old valid JSON still passes when the proposed rules are applied.

Compatibility review is not the same as a line-by-line diff. It depends on keyword meaning, validator behavior, the schema draft in use, and real data samples. A change to format may be only annotation in one setup and enforced as an assertion in another. A change under oneOf or not can reverse acceptance for particular instances. A remote $ref can hide the rule that decides whether an old payload is still valid.

Change direction Compatibility meaning Release review question
Stricter validation Some old valid instances may fail. Which producers, clients, files, or stored records still use the older shape?
Relaxed validation More values may pass than before. Can downstream code handle the wider type, enum value, object shape, or array shape?
Annotation change Validation may stay the same while generated docs or clients change. Does the release need documentation, SDK, or code-generation review?
Reference or composition change The effect may depend on resolved schemas and representative instances. Have old samples been validated with the same draft and validator used in production?

A schema change report is therefore a triage artifact. It points to rules that deserve release notes, migrations, sample validation, or a versioned contract. The final decision should still include representative old payloads, resolved referenced schemas, and the validator configuration that will enforce the proposed contract.

How to Use This Tool:

Use the checker when you have one released JSON Schema and one proposed replacement. The comparison runs in your browser and updates the ledger as either schema changes.

  1. Set Schema label to the contract being reviewed, such as an API body, event name, configuration object, webhook payload, or stored document type. The label carries into the report evidence.
  2. Choose Review coverage. Use Contract-strict release review for release gates, API surface review when detailed constraint and closure checks are covered elsewhere, or Structure-only scan for an early shape pass.
  3. Choose Local $ref handling. Keep Resolve local $ref pointers on when schemas use $defs, definitions, or internal reusable fragments. Use opaque handling only when the reference string itself is the comparison target.
  4. Paste or browse the current published contract into Released schema, then paste or browse the candidate contract into Proposed schema. Use Format after fixing JSON syntax errors.
  5. Load Breaking sample or Compatible sample when you want to see the expected ledger shape before reviewing a real contract.
  6. Open Advanced only when needed. Finding render limit keeps very large ledgers readable, and Annotation notes adds informational rows for title, description, default, examples, deprecated, readOnly, and writeOnly changes.
  7. Start with Compatibility Ledger, confirm selected coverage and reference status in Rule Summary, and use Schema Risk Mix as a severity snapshot rather than the release decision by itself.

If either schema cannot be parsed as JSON, treat the result as a blocking input error. Compatibility findings are meaningful only after both sides parse successfully.

Interpreting Results:

Critical, High, and Medium rows count as breaking signals in this checker. A nonzero breaking count means the proposed schema should not silently replace the released schema without a versioned release, migration window, compatibility exception, or sample-payload proof.

The ledger is strongest for direct keyword changes: new required properties, removed accepted types, removed enum values, tighter numeric or string constraints, object closure, array item restrictions, and changed composition keywords. A clean ledger means the selected rule set did not detect a signal. It does not prove that every real instance, validator configuration, remote reference, or application rule is safe.

Output What to read Best next check
Compatibility Ledger One row per detected change, including severity, change label, JSON Pointer, released value, proposed value, and release action. Review Critical and High rows first, then test older payload samples for Medium rows.
Rule Summary The verdict, selected coverage, parsed schema size, local-reference status, and annotation setting. Confirm the profile did not skip a rule family that matters for the release gate.
Schema Risk Mix A chart of ledger rows by severity. Use it for triage and reporting, then return to the ledger for exact release actions.
JSON The structured report with inputs, summary counts, schema statistics, findings, and warnings. Keep it with review evidence when a contract change needs audit history.
Reference warnings Remote references are kept opaque, and unresolved or circular local references are reported as warnings. Resolve or vendor referenced schemas before treating the report as complete compatibility evidence.

Do not average severity counts into a release decision. One newly required root field can matter more than many informational annotation rows, and one unresolved reference can hide the property rules that matter most.

Technical Details:

JSON Schema describes valid JSON instances with assertion keywords, applicator keywords, annotation keywords, and reference keywords. Backward compatibility for validation means the proposed accepted-instance set does not shrink for data that older producers, clients, or stored documents may still send.

The comparison is rule based rather than mathematical. It parses both JSON documents, optionally resolves local JSON Pointer references, compares matching schema locations, records keyword-level changes, deduplicates repeated findings, sorts by severity, and counts Critical, High, Medium, Low, and Info rows.

Rule Core:

Rule family Breaking or review signal Severity used here
Parse Released or proposed input is empty or not valid JSON. Critical.
Required fields A property becomes newly required, or a dependent requirement is introduced. Critical for new required fields; High for dependent requirements.
Properties A defined property disappears, or a new property appears as required. Critical for required-property loss or addition; High for removed optional definitions.
Types An accepted type is removed, replaced, widened, introduced, or removed as a constraint. Critical or High for removed accepted types; Medium for introduced type constraints; Info for widening or removal.
Enum and const Allowed values are removed, a fixed value set is introduced, a restriction is removed, or enum values are added. Critical for removed values; High for new restrictions; Info for relaxation or added enum values.
Constraints Minimums increase, maximums decrease, patterns appear or change, formats change, uniqueness appears, divisibility changes, or property-name rules appear. High or Medium for stricter checks; Info for relaxation.
Closure additionalProperties, unevaluatedProperties, additionalItems, or unevaluatedItems becomes more restrictive. High when old extension fields or extra array items may be rejected.
Composition allOf, anyOf, oneOf, not, if, then, else, or dependentSchemas changes. Medium because local classification depends on representative instances.
Annotations Documentation or code-generation hints change when annotation notes are enabled. Info.

Review Coverage:

Review coverage Rule families included Best fit
Contract-strict release review Types, enums, constraints, closures, composition, required fields, properties, arrays, and local reference handling. Release-gate review for contracts that validate real producer or client data.
API surface review Types, enums, composition, required fields, properties, arrays, and references; detailed constraints and closure rules are skipped. Broad API compatibility review when separate tests cover numeric, string, and object-closure constraints.
Structure-only scan Types, required fields, properties, arrays, and references; enum, constraint, closure, and composition checks are skipped. Fast first pass for large schema redesigns or early design review.

Pointer and Reference Details:

JSON Pointer identifies a location inside a JSON document. Pointer tokens are separated by /, and literal ~ and / characters inside a token are escaped as ~0 and ~1. A row at #/properties/status/enum points to the enum rule for the status property in the root schema.

Case Behavior Review impact
Local pointer such as #/$defs/User Can be resolved against the same schema document when local resolution is enabled. Common definitions are compared by shape rather than only by reference text.
Remote reference Kept opaque. Vendor or resolve the external schema separately when it contains validation rules.
Unresolved local reference Reported as a warning. The report may miss type, property, or constraint changes hidden behind the reference.
Circular local reference Not expanded repeatedly. Review recursive branches with representative payloads and the production validator.

Composition and format deserve manual review even when they produce only Medium or informational rows. Keywords such as oneOf and not can accept or reject values in ways that are difficult to classify from a local schema comparison alone. The format keyword may be annotation-only in one validator configuration and assertion-like in another, so release evidence should match the validator behavior used in production.

The visible ledger can be capped by Finding render limit to keep the page responsive, but the structured JSON report includes the full finding list. Use the cap to control display size, not to reduce the compatibility scope.

Privacy and Accuracy Notes:

The comparison runs in the browser, so pasted schemas and loaded files are not uploaded for the compatibility analysis. Treat schemas as sensitive anyway when they contain private field names, partner contracts, unreleased API shapes, or example values copied from production data.

  • Remove secrets, personal data, and production examples before sharing exported reports.
  • Use a full validator pass with representative old payloads before shipping critical contract changes.
  • Resolve remote references outside this checker when referenced schemas affect accepted values.
  • Review generated clients, switch statements, and documentation when enums, annotations, or formats change.

Worked Examples:

A proposed order schema that adds currency to the root required list should produce a Critical New required property row. Older order payloads that omit currency were valid before and can fail after the release, so the safer path is to add the field as optional, migrate producers, then require it in a breaking version.

Changing a field from {"type":"number"} to {"type":"string","pattern":"^[0-9]+\\.[0-9]{2}$"} should produce a type replacement and a pattern-related signal. The new schema may express money formatting better, but old numeric totals cannot pass without transformation.

An enum change from ["draft","paid","cancelled"] to ["paid","cancelled"] should produce a Critical enum row because draft is no longer accepted. Adding "refunded" instead is usually a validation relaxation, but strict clients may still need tests and release notes.

If a report warns that local references were unresolved, make the reviewed schema self-contained or fix the pointer path before relying on the result. A missing reference can hide the exact property, type, or closure rule that decides compatibility.

FAQ:

What counts as a breaking signal?

Critical, High, and Medium findings count as breaking signals here. They mark changes that can reject old valid data or need manual compatibility proof before release.

Can a clean ledger prove the new schema is safe?

No. A clean ledger means the selected rule set did not detect a compatibility signal. Important contracts still need old payload validation, resolved references, and review against the production validator.

Why can adding enum values still matter?

JSON Schema validation usually treats added enum values as a relaxation. Generated clients, switch statements, dashboards, and downstream rules can still need updates when new values appear.

Should local references be resolved?

Yes for most release reviews. Resolving local $ref pointers lets shared definitions be compared by their rules instead of only by reference text.

Why are composition changes marked for manual review?

Composition keywords can combine, exclude, or conditionally apply schemas. Their real compatibility effect depends on actual JSON instances, so representative payload validation is safer than trusting a local comparison alone.

Glossary:

Released schema
The current contract already used by clients, producers, validators, or stored data.
Proposed schema
The candidate schema that may replace the released contract.
JSON Pointer
A path syntax for identifying a specific value inside a JSON document.
Breaking signal
A Critical, High, or Medium finding that can reject old valid data or requires manual compatibility proof.
Local reference
A $ref that points to another location inside the same schema document.
Annotation
Schema information such as title, description, default, examples, deprecated, readOnly, or writeOnly that may affect documentation or generated code without directly changing validation.

References: