Schema Difference Analyzer
Paste two schemas and find out whether the change is safe to ship — a real recursive diff classified as added / removed / type / constraint, distilled into a backward / forward / breaking verdict with a precise reason for every breaking change. Analyzed entirely in your browser.
Target B violates the contract — existing consumers or producers will break.
- properties.note — Field `note` removed — clients reading it will break.
- properties.qty.minimum — `minimum` raised 1 → 2 — values valid before may now be rejected.
- properties.total.type — Type changed string→integer — clients expecting `string` will break.
- required[3] — Field `currency` is now required — payloads that omitted it are now invalid.
## Schema compatibility report
**Verdict: Breaking** — Target B violates the contract — existing consumers or producers will break.
> 2 added · 1 removed · 3 changed · 4 breaking
### ⚠️ Breaking changes
- Field `note` removed — clients reading it will break. (`properties.note`)
- `minimum` raised 1 → 2 — values valid before may now be rejected. (`properties.qty.minimum`)
- Type changed string→integer — clients expecting `string` will break. (`properties.total.type`)
- Field `currency` is now required — payloads that omitted it are now invalid. (`required[3]`)
### ➕ Added
- `properties.currency` — added (`{"type":"string","enum":["USD","EUR","GBP"]}`)
- `properties.status.enum[3]` — enum value added (`"refunded"`)
### ➖ Removed
- `properties.note` — removed (was `{"type":"string","description":"Internal note"}`)
### 🔧 Type & constraint changes
- `properties.qty.minimum` — minimum narrowed: `1` → `2`
- `properties.total.type` — type changed (string → integer): `string` → `integer`
- `required[3]` — newly required (`"currency"`)
Will this schema change break my consumers?
A changelog tells you what changed; a compatibility analysis tells you whether it's safe to ship. Those are different questions, and the second one is what actually wakes you at 3am. This tool runs a real structural diff — walking both schemas key-by-key, unioning object keys and aligning arrays by index, reporting every difference with its exact dotted path like properties.total.type — and then maps each difference onto the contract between a producer and its consumers. The output isn't a list of edits; it's a single verdict, backward compatible, forward compatible or breaking, with the reasoning to back it up.
The distinction between backward and forward compatibility is the heart of schema evolution. Backward compatible means new schema, old data: B still accepts everything A produced, which is true when you only add optional fields — old clients keep working. Forward compatible is the other direction, old reader, new data: you can loosen a constraint or add an enum value and a tolerant consumer still copes. Breaking violates one of those contracts outright. The analyzer encodes the rules that decide it: removing a field, flipping a type, promoting a field to required, or narrowing a constraint — raising a minimum, shrinking a maxLength, dropping an enum value — each rejects data that used to be valid, so each is flagged breaking with a specific reason.
This is, in miniature, what contract testing does for a producer/consumer relationship: it freezes the agreement so neither side can drift without the other noticing. Full consumer-driven contract tests belong in CI, but most breakages are obvious at the schema level — a removed field, a string that became an integer, a newly-required key — and catching them while you're still editing the schema is far cheaper than discovering them in a partner's integration. Lead with the breaking-changes callout: it doubles as the migration checklist you'll hand to consumers, and the Markdown report drops straight into an RFC or a pull request.
For the neighbouring views: turn a release into versioned notes with the API Changelog Generator, drill into a single model's types and constraints with the JSON Schema Explorer, and generate reference docs from a whole spec with the OpenAPI Documentation Generator.
Trusted by API & Data Engineers
“We gate every schema PR on this now. It caught a total field flipping string→integer and a newly-required currency that would have broken three downstream services, and the verdict banner went straight to red. The why-it-breaks lines are basically our migration notes — I paste the Markdown into the PR description.”
“The narrowing-vs-widening logic on constraints is the part other diff tools get wrong. Raising a minimum is correctly flagged breaking, relaxing a maxLength is forward-compatible. I'd like oneOf/anyOf awareness eventually, but for object schemas it's exactly the contract check I wanted, and it's all local.”
“Backward vs forward compatible is exactly the framing our data team thinks in for producer/consumer evolution. We use it before changing event schemas — added optional field stays green, removed field goes red with a clear reason. It's settled a lot of 'is this safe to ship' debates.”
“A genuine recursive diff with sensible compatibility heuristics, not a line diff. The enum handling — added value is forward-safe, removed value is breaking — matches how validators actually behave. The copy-ready report drops into our RFC template and the breaking callout is the headline reviewers read first.”
Love using our calculator?
Related API tools
Related Articles
Dive deeper with our expert guides and tutorials related to Schema Difference Analyzer
structural diff · compatibility verdict · breaking callout · Markdown report · in-browser · Last reviewed: 2026-06