OPENAPI BREAKING CHANGE CHECK · RUNS IN YOUR BROWSER

Did this API version break existing clients?

Paste the OpenAPI 3.0/3.1 JSON document from before and after a change and this page reports exactly which differences would break an existing client — a removed endpoint, a parameter that became required, a narrowed type, a removed enum value, a request body that became required — separately from the non-breaking additions that happen every release.

Nothing is uploaded. Both documents you paste are read in this browser and never leave your device, and this tool makes no network calls of its own.

1. Paste both OpenAPI documents (JSON)

OpenAPI 3.0 and 3.1 are both understood, including specs that use $ref to shared components.parameters. Swagger 2.0 is detected and rejected rather than misread.

Paste a before and after OpenAPI document above and click Check.

Prefer a CLI, or want this in your own CI?

Same logic, zero dependencies, one file:

python3 openapi_diff.py old.json new.json                    # human-readable
python3 openapi_diff.py old.json new.json --format json       # machine-readable
python3 openapi_diff.py old.json new.json --fail-on-breaking  # exit 2 only if a breaking change is found

Get openapi_diff.py from the repo — stdlib only, nothing to install, no network calls. --fail-on-breaking only fails the build on an actual breaking change, not on every routine addition, so it is safe to run on every pull request that touches the spec.

Common questions

Why not just read the diff of the two spec files?

A raw text diff of two OpenAPI documents shows every reordered key and reworded description alongside the one parameter that quietly became required. On a real spec with dozens of operations, the change that would actually break a client is a needle in that haystack. This tool ignores everything that does not affect the contract and classifies only what remains as breaking or not.

What counts as a breaking change here?

An operation (method + path) removed; a parameter that is new or became required; an existing parameter's declared type changed; an enum value removed from a parameter's schema, including a parameter newly restricted to an enum where it previously accepted any value, so a client could still send a value the new API no longer accepts; and a request body that became required where it previously was not. Everything else — a new optional parameter, a new endpoint, a widened enum, an enum constraint removed entirely — is reported separately as non-breaking.

Does this deep-diff my request and response body schemas?

No, not beyond a request body's own required flag. This is a shallow, structural diff of paths, operations, and parameter/request-body shape. A field added or removed deep inside a request or response body's JSON Schema is not reported. Treat a clean result as evidence about the surface this tool actually checks, not a full compatibility guarantee.

Does it upload my API spec anywhere?

No. Both documents you paste are read in this browser and never leave your device. An OpenAPI spec can describe an unreleased API surface, so this page makes no network requests of its own — pasting is the only way it sees anything.

Does it support Swagger 2.0 or YAML specs?

Not yet. This tool reads OpenAPI 3.0 and 3.1 JSON documents only. A Swagger 2.0 document is detected and explicitly rejected — its parameter and body shape differ enough that silently reading it as OpenAPI 3 would misreport rather than just refuse. Convert a YAML spec to JSON first with any OpenAPI tool's own export, or a YAML-to-JSON converter, before pasting it here.

More: how this compares to manually reading a diff of the spec files, or how this compares to oasdiff, the open-source CLI with a much deeper change catalogue. If a result surprised you, see why adding an enum to a parameter counts as breaking.