API Breaking Change Detector

DataFormatter API Breaking Change Detector is a free, browser-based tool that compares two JSON APIs or JSON Schemas, classifies every difference as breaking, potentially-breaking, non-breaking or informational, and builds a compatibility report — with no signup and no upload.

About this tool

What is it?: DataFormatter API Breaking Change Detector is a free online tool that compares two JSON APIs or JSON Schemas and classifies every difference as breaking, potentially-breaking, non-breaking or informational.
Who is it for?: Backend and integration developers reviewing release branches, third-party API upgrades or contract changes before shipping.
What makes DataFormatter's tool different?: It is schema-aware — new required fields, enum removals and type tightenings count as breaking — and runs fully locally with no upload.

What the API diff detector does

Shipping a new API version is risky when you cannot see what actually changed. Paste the previous and current version side by side and this workbench reduces the delta to a prioritized report: breaking changes first, then potentially-breaking, non-breaking and informational ones — each with its exact JSON path and the before / after values that produced it.

Schema-aware analysis — when the documents use JSON Schema keywords, the detector understands them: a newly required field, a removed enum value, a type narrowed away from null or a field removed from properties are breaking, while relaxed types and enum additions are not.
Plain JSON fallback — comparing raw payloads still works: removed fields and type/shape changes surface as breaking, added fields as non-breaking.
Shape-flip detection — containers that flip between object and array are called out explicitly instead of being lost in field-level noise.
Prioritized report — changes are sorted breaking → informational, with a count summary, a side-by-side editor, and a filterable list you can search by severity.
Local and private — both documents are analyzed entirely in your browser. Nothing is uploaded or stored.

A breaking change in practice

Removing a field that consumers already send or read, or tightening a type so the old values stop parsing, is the classic release-blocking problem. Compare these two schema versions and the report walks you through why each change matters.

Current version

{
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "string" }
  }
}

Proposed version

{
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "age": { "type": "integer" }
  }
}

Removed field email — classified breaking: clients that post a name + email payload now send an unknown field, and anything that read email back receives nothing.
Type change on age from string to integer — classified potentially-breaking: existing consumers that sent a numeric string ("25") are now invalid and need a code change.

Reading the classifications

Each change is an observation, presented with its evidence (the path and the before → after values). Breaking and potentially-breaking entries are candidates to block a release; non-breaking entries rarely need attention; informational entries describe nested structure or scalar value changes you may want to eyeball. When schema keywords are missing, required-vs-optional assumptions cannot be made — the description says so explicitly.

Reviewing a release branch

Take the schemas from main and the release branch, and scan the breaking list before approving the merge.

Checking a third-party API upgrade

Compare the documented response shapes from the old and new versions of an SDK you depend on, so you know what to fix before switching.

Auditing a contract change

Confirm that a change you intended as backward-compatible (an added field, a relaxed type) shows up as non-breaking rather than breaking.

Frequently asked questions

Is the API breaking change detector free and does it need a signup?

Yes, it is completely free with no account or signup. Paste two API versions and the comparison runs instantly in the browser.

Does the tool upload my JSON schemas or API payloads?

No. The two documents never leave your machine — comparison and classification run locally in your tab, exactly like the rest of DataFormatter.

What kinds of documents can I compare?

Plain JSON responses and JSON-Schema-style documents. When schema keywords like required, type and enum are present, the detector accounts for them (a new required field, a removed enum value or a tightened type are flagged as breaking).

Are the classifications guaranteed to be correct?

No — every flagged change is a heuristic observation, not a verdict. Breaking, potentially-breaking, non-breaking and informational groups give you a review order; a change classified as non-breaking can still break a consumer that depended on it.

Related tools

Last reviewed September 2026 · DataFormatter team — this tool processes data locally in your browser.