What the OpenAPI Specification Diff Checker does
This OpenAPI diff checker compares two versions of an API description and sorts every change by what it does to the people calling the API: breaking, worth reviewing, non-breaking or purely informational. It reads Swagger 2.0, OpenAPI 3.0 and 3.1, in JSON or YAML, and both documents stay in your browser.
A text diff tells you which lines moved. It cannot tell you that tightening a maxLength in a request will reject payloads clients send today, while the same tightening in a response is harmless. This tool resolves $ref pointers, lines up operations by method and path template, and applies one rule table in both directions, so a pull request that changes the contract can be reviewed on its consequences.
How to use it
- Paste the version currently in production as A and the proposed version as B, or drop the two files. YAML and JSON can be mixed.
- Choose Compare. Each change appears with its impact, the operation and field it affects, and the rule that classified it.
- Open Consumer impact for a grouped summary you can paste into a review, or Changelog for Markdown release notes.
- Check the Rule table if a classification surprises you; every verdict comes from one of its rows.
- Download the list as CSV or JSON if you want to fail a build on breaking changes or track them over releases.
Reading the results
Breaking means an existing, correctly written client can fail after the change: a removed operation, a new required parameter, a request that accepts less, a response that can now contain something it could not before, or authentication added to a public call.
Review marks changes that are usually safe but depend on how clients are written - a new enum value in a response breaks a client with an exhaustive switch, and a new status code breaks one that treats anything unexpected as fatal.
Non-breaking changes add capability without removing any: new paths, optional parameters, wider request types, extra response properties. Info covers version numbers, server URLs and renamed path parameters, which do not change the URL a client calls.
Worked example: an Orders API going from 1.4.0 to 2.0.0
Load the first example. Version 2.0.0 adds a global bearer-token requirement, removes DELETE /orders/{orderId}, lowers the limit maximum from 100 to 50, swaps the cancelled status filter for refunded, adds a required channel to new orders, shortens note from 500 to 200 characters, drops currency and makes total nullable.
The checker reports 17 breaking changes, 5 to review, 2 non-breaking and 4 informational. The count is higher than the list of edits because the Order schema is shared: removing currency breaks three responses (the list, the single order and the create response), and each is reported where a client would feel it.
Renaming {orderId} to {id} is reported as information only - path parameters are positional, so /orders/42 is still /orders/42. The second example, a 1.5.0 release that adds an endpoint, an optional sort parameter and an updatedAt field, and relaxes note to 1,000 characters, reports 6 non-breaking changes and nothing breaking.
Why requests and responses are judged in opposite directions
A request schema is a promise about what the server will accept. Narrowing it - fewer types, a shorter maximum, a removed enum value, a newly required field - rejects input that used to work, so it breaks clients. Widening it is safe.
A response schema is a promise about what the client will receive. Widening it - a new type such as null, a removed required entry, a new enum value - hands clients data they were never told to expect. Narrowing it is safe, because every value still fits the old description. The same keyword can therefore be breaking on one side and harmless on the other, which is exactly what a plain text diff cannot show.
What is compared
Paths and methods; parameters by location and name (path parameters by position); request bodies and their media types; responses by status code and media type; and the effective security of each operation, including OAuth scopes. Schemas are compared recursively through $ref, properties, required, items, enum, type (including OpenAPI 3.0 nullable), length, range, item-count, pattern, format and additionalProperties.
oneOf and anyOf are flagged for review when the number of alternatives changes, but the alternatives are not matched one to one - that needs a human who knows which branch is which.
Limitations: what the result does not prove
- It compares the descriptions, not the running services. If the implementation already differs from its OpenAPI file, the diff inherits that gap.
- Only local
#/...references are resolved. A document split across files must be bundled first, or the external parts are listed as unresolved rather than compared. - Behaviour that OpenAPI cannot express - rate limits, ordering, side effects, error wording - is invisible to any spec diff.
- Descriptions, summaries, examples and extensions (
x-...) are not compared, so a documentation-only release shows as unchanged apart from the version number.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- OpenAPI Specification 3.1.1 - checked 19 Sep 2026
- OpenAPI Specification 3.0.4
- Semantic Versioning 2.0.0
- RFC 9110 HTTP Semantics - status codes and content negotiation
Frequently asked questions
Is adding a new enum value to a response a breaking change?
Formally no - the old values still appear - but a client that switches over every known value and throws on anything else will fail. That is why the checker lists it under Review rather than Non-breaking. Generated clients in strongly typed languages are the usual casualties.
Does renaming a path parameter break clients?
No. The name inside the braces is only a label in the description; the client still calls the same URL. The checker matches path parameters by position and reports a rename as information, while a change to its type or format is still judged as a request change.
Why is making a response field nullable counted as breaking?
Because clients were told the field is always, for example, a number. A strongly typed client, or code that does arithmetic on it, fails on null. Declare the change in a new version, or keep the field non-null and add a separate one.
Can I compare a Swagger 2.0 file with an OpenAPI 3 file?
Yes. Both are normalised first: body and formData parameters become a request body, and response schemas are placed under the produced media types. Expect some media-type changes if the 3.x file lists content types the 2.0 file left implicit.
How do I use this in a pull request review?
Compare the main branch's file with the branch's file, then copy the Changelog or the Consumer impact summary into the review. For an automated gate, download the JSON and fail when the breaking count is above zero, allowing exceptions only with a version bump.
Are my API documents uploaded anywhere?
No. Parsing, reference resolution and comparison all run in this page. That matters because API descriptions often name internal hosts, unreleased endpoints and security schemes.
Last reviewed by the A2Z.Tools team against the sources listed above.
