OpenAPI Diff — Breaking Changes
Compare two versions of an OpenAPI description and see which changes break existing clients, which to check, and which are safe — with a report for the pull request.
OpenAPI Diff
Old version
New version
Will this release break your clients?
Paste or open two versions of an OpenAPI description. Every change is judged for clients already using the old one: breaking, worth a check, safe, or documentation only.
OpenAPI 3.0 and 3.1 · YAML or JSON · up to 20 MB each · local $refs followed
How is this calculated?
Operations are matched by method and path shape, so renaming {id} to {orderId} is reported as a rename, not a removal and an addition. Parameters are matched by location and name, path parameters by position. Schemas are compared field by field after local $refs are followed and 3.0’s nullable is written as JSON Schema’s null type, using the same engine as the JSON Schema Diff tool: a request schema that accepts less breaks the clients that send it; a response schema that accepts more — a new enum value, a field no longer required — breaks the clients that read it.Runs in your browser — nothing you enter leaves this device.
About this tool
What it does
When an API changes, the question that matters is whether the apps already using it will keep working. This tool compares two versions of an OpenAPI description — the one clients were written against and the new one — and sorts every difference by that question. Breaking: an old client can fail, because an operation is gone, a parameter became required, a request now accepts less, or a response can now carry something the old one never did. Check: it depends on the client. Safe: old clients carry on. Docs: only words changed. It also tells you when the version number does not match: breaking changes with only a minor version bump.
How to use it
- Paste or open the old description on the left and the new one on the right, YAML or JSON, OpenAPI 3.0 or 3.1 (the two may differ). “Try an example” loads two versions of an Orders API with one change of each kind.
- Read the counts at the top, and the version advice if there is any.
- Go through the changes, grouped by operation. Show only the breaking ones when you are deciding whether to ship.
- Copy the report as Markdown into the pull request or the changelog.
Limits and your data
- Only local references (#/components/…) are followed. A reference to another file is compared as written: if the referenced file changed, that change is not seen.
- allOf, oneOf and anyOf are compared as written, not reasoned about; a reordered oneOf shows as a change to check.
- The tool judges the description, not the server. If the server already behaved differently from the old description, comparing descriptions cannot tell.
- What counts as breaking for a particular client — whether it ignores unknown fields, for example — is for you to judge; the tool takes the strict view and says why.
- Both descriptions are compared in your browser, in a background worker; neither is uploaded, and the page works offline.
Questions
Why is a new enum value in a response breaking?
A client written against the old description may handle every value it knew about and nothing else — a switch statement with no default, or a strict code generator. A value it has never seen can crash it. Adding the value to a request parameter is safe, because old clients simply never send it.
Is adding a new field to a response breaking?
No. Old clients ignore fields they do not know, and the schema now constrains a field it did not mention before, so it accepts less — which is safe on the response side. Removing a field, or making it no longer required, is breaking.
What version number should the new description have?
Under semantic versioning, any breaking change means a new major version (2.x → 3.0.0). The tool says so when the version moved less than that, and also when the major version moved with no breaking change.
Can I compare a 3.0 description with a 3.1 one?
Yes. Each is read by its own rules, and 3.0’s nullable is translated so that moving from 3.0 to 3.1 does not show up as hundreds of changes.