{{ summaryHeading }} {{ summaryPrimary }} {{ summaryLine }}

Use the version already relied on by producers, clients, validators, or stored documents.
{{ releasedFileStatus || 'Drop one JSON, schema, or text file onto the editor.' }}
This label identifies copied and downloaded review evidence.
Use contract-strict for a release gate; lighter profiles are early design-review filters.
Resolve local pointers for normal reviews; pin opaque mode only when reference strings are the comparison target.
Use the candidate version intended to replace the released contract.
{{ proposedFileStatus || 'Drop one JSON, schema, or text file onto the editor.' }}
The reactive report uses the current editor contents; no schema is uploaded.
Coverage notes
  • {{ warning }}
Choose 50–500 rows to keep large comparisons responsive without changing the result.
rows
Turn on for documentation or code-generation review; leave off for the release-blocker view.
{{ include_annotations ? 'Include annotation-only changes' : 'Ignore annotation-only changes' }}
SeverityChangeJSON PointerReleasedProposedRelease actionCopy
{{ severityLabel(row.severity) }}{{ row.change }}{{ row.pointer }}{{ row.released }}{{ row.proposed }}{{ row.action }}
No compatibility signals were found in the selected heuristic coverage. Validate representative old instances before release.
Review areaCurrent valueEvidenceNext actionCopy
{{ row.area }}{{ row.value }}{{ row.evidence }}{{ row.action }}
JSON Schema Generator Turn sample JSON into a draft-aware JSON Schema with explicit inference choices and review warnings for assumptions that need broader test data.
Test Data Generator Generate repeatable synthetic test records from a field recipe and seed, with format-aware output and checks for blanks or normalized fields.
Bug Report Generator Draft a tracker-ready bug report with structured reproduction details, triage fields, readiness checks, and local sensitive-data warnings.
ENV Converter Convert ENV text into common configuration formats with controlled expansion, duplicate-key handling and secret-like value checks before deployment.

A published JSON Schema becomes a promise about which JSON values a system will accept. Once producers, stored documents, generated clients, or downstream services rely on that promise, tightening the schema can reject data that was valid under the released contract.

Compatibility is therefore about accepted instance sets, not the number of changed lines. Adding a required property, removing an enum value, narrowing a type, raising a minimum, lowering a maximum, or closing an object can all reduce the accepted set. Relaxing a schema widens that set, which avoids rejecting old data but may still surprise code that assumes a fixed group of values or fields.

ChangeLikely effectWhat to verify
New required propertyOlder objects without the property failExisting producers and stored records
Removed type or enum valuePreviously accepted values failPayload samples and generated clients
Tighter numeric, length, or array boundValues near the old boundary failExact boundary cases in production data
Closed object or arrayExtension fields or extra items failForward-compatible producers and vendor data
Relaxed ruleMore values pass validationDownstream code that may reject the wider shape

Some differences resist a purely structural answer. Composition keywords such as oneOf, not, and conditional schemas can change acceptance in ways that require real instances. Remote references may hide decisive rules, and format enforcement varies by validator configuration. Annotation changes can alter documentation or code generation without changing validation.

Backward compatibility also depends on direction. This review asks whether values accepted by the released schema remain accepted by the proposed schema. It does not prove that every new value will be understood by old consumers, nor does it prove semantic compatibility in business rules that JSON Schema cannot express.

A reliable release gate combines a structural comparison with representative old payloads, the same schema draft and validator used in production, fully resolved dependencies, and a versioning plan for intentionally breaking changes.

How to Use This Tool:

Compare the contract already relied on in production with the exact candidate intended to replace it.

  1. Paste the published contract into Released schema and the candidate into Proposed schema. Correct JSON syntax errors before reading compatibility findings.
  2. Use Contract-strict release review for a release gate. The lighter API and structure profiles deliberately omit some constraint or closure checks.
  3. Resolve local $ref pointers for normal reviews. Choose opaque handling only when reference strings themselves are the object of comparison.
  4. Review critical, high, and medium findings as breaking signals, then inspect low and informational rows for coverage or downstream-client effects.
  5. Validate representative released instances with the production validator before approving the change.

Interpreting Results:

Breaking signals detected means at least one critical, high, or medium heuristic matched. It is a release warning, not a formal proof that every old instance fails. No breaking signals detected means the selected structural rules found none; unexpanded references, composition semantics, validator options, and business meaning can still matter.

Pay particular attention to coverage warnings. An opaque, remote, unresolved, circular, or depth-limited branch is a reason to test real instances rather than treating the summary as complete.

Technical Details:

The comparison walks corresponding schema locations using JSON Pointer paths. Local references can be dereferenced into their target shapes; remote references are never fetched. Findings are deduplicated, then sorted by severity, pointer, and change label.

Rule Core

Rule familyBreaking directionSeverity used
TypesAccepted type removed or replacedHigh or critical
Required propertiesProperty becomes requiredCritical
Properties and enumsDefined property or accepted value removedHigh or critical
Bounds and constraintsMinimum rises, maximum falls, or a new restriction appearsMedium or high
ClosureAdditional or unevaluated content becomes restrictedHigh
CompositionallOf, anyOf, oneOf, not, conditionals, or dependent schemas changeMedium, with instance testing required

Critical, high, and medium rows contribute to the breaking count. Low rows report coverage limits, and informational rows describe widening, relaxation, or optional annotation changes. The structure-only profile still checks required and property removal rules, but skips enums, constraints, closure, and composition. API surface review adds enums and composition; strict review enables every rule family.

Reference and comparison limits

Only fragment references beginning with # can be resolved. Circular references are not expanded repeatedly, and recursion stops after 48 levels. Each schema is limited to 250,000 characters; the visible finding limit of 50 to 500 changes rendering only, not the computed totals.

Privacy and Accuracy Notes:

Both schemas are parsed and compared in the browser. Remote references are not downloaded. Keep proprietary examples and secrets out of schema annotations before sharing reports, and treat the result as a heuristic until representative instances pass the production validator.

Worked Examples:

Required currency field

A released order accepts objects without currency. Adding currency to required produces a critical finding because every older order that omits it becomes invalid. A safer sequence introduces the field as optional, migrates producers and stored data, then requires it in a breaking contract version.

Wider plan enum

Changing ["starter", "team"] to include "enterprise" widens validation and appears as informational rather than breaking. Strict client switch statements can still fail on the new value, so consumer testing remains necessary.

References: