OpenAPI Diff

What this differ checks — and what breaking actually means

A change is breaking when a client written correctly against the old spec can fail against the new one without changing a line of its own code. That definition drives every verdict on this page. Removing a path or an operation is breaking because existing calls have nowhere to go. Removing a response status — above all a 2xx — is breaking because client error handling was written around the old set. Adding a required parameter or a required request property is breaking because yesterday’s valid request is suddenly rejected. Changing a field’s type or format is breaking because parsers, validators and generated SDKs all key off the declared type. Removing an enum value is breaking because a client may still send it, or may receive data it can no longer interpret. Everything else — a new endpoint, an optional parameter, a new response field, a new enum value, a new status code — is reported as non-breaking: old clients keep working, even if they cannot use the new capability yet.

The comparison is structural, not textual. Both documents are normalised into the same model before anything is compared: every path and operation, its parameters keyed by name and location, its request body and each response reduced to a schema signature — a deterministic summary of types, formats, property names, required lists and enum values, built recursively with local $ref references resolved. That is why reordering keys, reformatting whitespace or rewriting every description produces an empty diff: none of those change the contract. It is also why a change buried three levels inside a referenced schema is still found — the signature expands the reference instead of comparing its name.

Two input shapes are accepted because the ecosystem publishes both: JSON is tried first, and when that fails the text is parsed as YAML, the format most hand-written OpenAPI documents use. Swagger 2.0 documents work too, including their in: body parameters and per-response schemas. There is deliberately no live fetching and no upload: paste the documents or drop the files, exactly as you would with a HAR capture, and the comparison runs when you press the button — not on every keystroke — so two large pasted specs stay responsive.

Use the result as a release gate, not as decoration. In a review, the breaking list is the agenda: each entry needs either a fix, a version bump, a deprecation window or a written decision that the break is intended and communicated. The non-breaking list is the changelog draft. Exporting the diff as JSON lets you archive that decision next to the release, and the copyable summary drops straight into a pull request — the same discipline you would apply to a webhook contract change, where a silently altered payload breaks every subscriber at once.

Honest limits, stated plainly. This differ compares the declared contract: it cannot see behaviour the spec does not declare, such as a field that keeps its type but changes its meaning, a new business rule, tighter rate limits, or an error message clients were (unwisely) parsing. It follows local references and compares schemas to a bounded depth, so pathological deeply-nested or mutually recursive schemas are summarised rather than expanded forever. And a diff with zero breaking changes is not a promise that an upgrade is safe — it is evidence that the documented contract held, which is exactly the evidence worth having before you deploy.