Compare two versions of a JSON Schema and see what changed for API consumers — removed properties and type changes flagged as breaking, new requirements as warnings, additions as informational.
Show calculation steps
Processed privately in your browser — nothing you paste is uploaded, logged or stored.
An honest API changelog
When a schema changes, the question that matters is: who breaks? This comparison reads two schema versions the way a consumer would. Removed properties, type changes and removed enum values are breaking — data valid yesterday fails today. New requirements and tightened constraints are warnings. Added optional properties and loosened rules are informational. The report reads like the changelog you should be publishing.
Worked example
2 breaking, 2 warning, 2 informational change(s):
BREAKING for consumers:
✖ /id — type changed: integer → string
✖ /plan — enum values removed: "team"
Warnings (stricter contract):
⚠ (root) — property "email" became REQUIRED
⚠ /email — constraint format: "email" added
Informational:
· /createdAt — property added to the schemaWhen to use it
- Pre-release review: any ✖ finding is a semver-major signal.
- Auditing a third-party API upgrade before migrating.
- Writing accurate release notes from the actual contract delta.
Limitations to know
- Compared keywords: type, properties (recursive), required, enum, common constraints, items, additionalProperties. Deep composition (allOf chains, if/then) needs human review.
- Severity is judged for CONSUMERS of validated data; producer impact can differ (a loosened rule is breaking for strict producers).
Related workflow
- To diff instance documents rather than schemas, use JSON Compare; to check whether real data still passes the new version, run it through the Schema Validator.
How to use the JSON Schema Compare
- Paste the old schema version into A and the new version into B.
- Click "Compare schemas".
- Read the report grouped by severity: breaking, warning, informational.
- Use the breaking list as your API changelog review.
Frequently asked questions
What counts as a breaking schema change?
From a consumer's perspective: a property removed from the schema, a type change (string → integer), or enum values removed — data and code that were valid yesterday break today. These are flagged ✖ breaking.
What lands in the warning tier?
Changes that tighten the contract: a property becoming required, new constraints (maxLength, pattern…), or additionalProperties turning false. Existing consumers may survive, but producers of previously-valid data may not.
Which parts of the schemas are compared?
type, properties (recursively), required, enum, the common constraint keywords, items, and additionalProperties. Structural keywords outside that set (allOf compositions, conditional schemas) are not deeply analyzed — review those by hand.
When should I run this?
Before every schema release: diff old vs new, and treat any ✖ finding as a semver-major signal. It also makes an honest reviewer for third-party API upgrade notes.
