OpenAPI Diff and Breaking-Change Checker
See what changed between two API versions, and which changes break existing clients.
Try before you buy.
- Free preview: the change counts and the version step, with the first changes of the list (up to 10; a single change is shown with its details hidden).
- Locked until you unlock it: download and copy.
- Unlock: Premium pass, ₹799 for 30 days or ₹249 for 1 week, a one-time payment that never renews. Unlock: Premium pass, $19.99 for 30 days or $7.99 for 1 week, a one-time payment that never renews.
Ways to unlock shows how to get the full result.
Printing this result is locked in the free preview.
The version clients use today. YAML or JSON, OpenAPI 3.x or Swagger 2.0. A split description: open or drop all its files.
The version you want to release. YAML or JSON, OpenAPI 3.x or Swagger 2.0. A split description: open or drop all its files.
What changed
Problems in the descriptions
Base
Revision
Locked in the free preview. Opens the ways to unlock this result.
Locked in the free preview. Batch runs unlock with a pass.
Locked in the free preview. Query results unlock with a pass.
About the OpenAPI Diff and Breaking-Change Checker
Paste or open the old and the new version of an API description — OpenAPI 3.0, 3.1 or 3.2, or Swagger 2.0, in YAML or JSON — and see every difference that matters to the people who call the API: operations added and removed, parameters, request bodies, responses, schemas, enum values, limits, media types, security requirements and servers. Each change is marked breaking (clients built for the old version can stop working), possibly breaking or non-breaking, with the line where it is written in both files.
References are followed before comparing, so moving a schema into components is not a change, while a property changed inside a shared schema is reported for every operation that uses it. A description split into several files is bundled first. The report suggests the Semantic Versioning step the release needs and, with a Premium pass, exports as Markdown for a pull request or changelog, or as JSON for a script. Everything runs in your browser.
Without a pass the result is a free preview: the summary counts, with the first rows of the change list. The whole report, copying it and the downloads unlock with a Premium pass.
How to use it
- Put the version clients use today in Base and the new one in Revision: paste them, open the files, or drop them on the boxes. For a description split into several files, open all of them at once (or the folder).
- Press Compare (it also runs while you type). If a description cannot be read, the error says where; problems that do not stop the comparison are listed under the report.
- Read the counts and the suggested version step, then the changes: filter by level, search by path or word, and press Base line or Revision line to see where a change is written.
- With a Premium pass, or after unlocking this result, press Copy Markdown for a pull request or a changelog, or download the Markdown or JSON report.
Examples
GET /orders gains: - name: storeId in: query required: true
Breaking — GET /orders: a new required query parameter “storeId”: requests without it are now invalid.
Made optional (or given to the server as a default), the same parameter is a non-breaking change.
OrderStatus: enum [pending, paid, shipped] → [pending, paid, shipped, refunded]
Breaking — GET /orders: the 200 response (application/json): each item’s property “status”: enum value "refunded" was added — clients that switch over the known values may not handle it. Non-breaking — GET /orders: query parameter “status”: enum value "refunded" was added.
The same schema is used in a request and a response: a new value is fine for what clients send, but new for what they receive.
note: maxLength 500 → 200
Breaking — POST /orders: the request body: property “note”: the maximum length went down from 500 to 200.
Non-breaking — GET /orders/{orderId}: the 200 response: property “note”: the maximum length went down from 500 to 200.Common uses
- Reviewing a pull request that changes an API description, with the Markdown report in the review.
- Writing the changelog of an API release, and checking that the version number fits the changes.
- Checking that a regenerated description (from code annotations) did not change the API by accident.
- Moving from Swagger 2.0 to OpenAPI 3.1 and confirming that the API stayed the same.
What counts as breaking
The test is the one oasdiff publishes for its checks: a change is breaking when a client that followed the old description can stop working under the new one. In practice, narrowing what a request may contain, or widening what a response may contain, breaks clients, so the same change can be breaking on one side and harmless on the other:
- Requests: a new required parameter or property, a parameter or body that became required, a type that became narrower (number → integer), a removed enum value, a lower maximum or higher minimum, a new pattern, a removed media type, a removed
oneOfalternative,additionalProperties: false, null no longer accepted. - Responses: a removed status code that meant success, a removed media type, a removed required property or header, a property that became optional or nullable, a wider type (integer → number), a new enum value, a higher maximum, a new
oneOfalternative. - Operations and security: a removed operation (unless it was deprecated first), a new security requirement where none was needed, a removed way of authenticating, an OAuth scope added to a requirement, an API key that moved to another header or the query, serialisation (
style,explode) that changed.
Properties marked readOnly never appear in requests and writeOnly ones never in responses, so changes to them on that side are not breaking. Webhooks are sent by the API, so for them the directions are reversed.
Breaking, possibly breaking and non-breaking
Breaking changes make a request that was valid invalid, or a response that clients understood surprising. Possibly breaking changes depend on how clients and servers behave: a request property that was removed (servers may ignore it or reject it), a changed pattern or format, a removed server URL. Non-breaking changes are additions and relaxations. Header names are compared without regard to case, and a renamed path parameter (/orders/{id} → /orders/{orderId}) is the same path. Each change has a check id (such as request-property-became-required), so a script can filter the JSON report.
Versions, references and split descriptions
Both documents are read into one model before comparing, so a Swagger 2.0 description can be compared with its OpenAPI 3.1 successor: body and form parameters become request bodies, produces and consumes become media types and x-nullable means a "null" type. Every $ref is followed, and changes inside a shared schema are reported under each operation that uses it. Files of a split description are bundled first (by their paths relative to each other, or by unique file names); references to URLs are never fetched.
The version step
The report suggests the Semantic Versioning step the changes need: major for any breaking change (rule 8), minor for new or deprecated features (rule 7), patch for the rest. It also reads info.version in both documents and says when it does not fit — for example 1.4.0 → 1.5.0 with breaking changes. Versions 0.x are for initial development, where anything may change (rule 4).
The JSON report
The JSON has the two documents’ titles and versions, a summary with the counts and the version step, and every change with its id, level, operation, message and the pointer, file and line in each version. A script can act on it — jq -e '.summary.breaking == 0' api-changes.json fails when there is a breaking change. This page runs in a browser; to check every pull request automatically, run a command-line checker in the pipeline.
Limitations
- Callbacks, links, examples and vendor extensions (
x-…) are not compared. - In schemas,
not,if/then/else,patternProperties,dependentSchemasand discriminator mappings are not compared; changes to them are not listed. - Breaking is judged from the descriptions alone: a change the server has always tolerated still counts, and a server that rejects more than its description says is not detected.
- References to other files are matched among the files you open; references to URLs are not loaded.
- Each comparison may run for up to a minute; very large descriptions are compared when you press Compare rather than while you type.
Privacy
On this device: nothing is sent
Everything happens in your browser. What you enter or open here is not uploaded or stored by MySmartCoPilot.
Frequently asked questions
What do I get without a pass?
Without a pass, OpenAPI Diff and Breaking-Change Checker shows the change counts and the version step, with the first changes of the list (up to 10; a single change is shown with its details hidden). Until you unlock it, the result can’t be downloaded or copied. A Premium or Ultimate pass, a one-time payment that never renews, unlocks the full result. The pricing page lists the passes and their prices.
Are my API descriptions uploaded?
No. Reading, bundling and comparing run in your browser, in a background worker; nothing is sent anywhere, and the page works offline once loaded.
Why is a new enum value in a response breaking?
Clients often handle every value they know (a switch with no default, or a generated enum type) and fail on a new one. If the list is meant to grow, write it as an x-extensible-enum — the list of values known today, used instead of enum, as in Zalando’s RESTful API guidelines: then a new value is not reported as breaking, because clients of such a list must handle values they do not know.
Why is a removed request property only “possibly breaking”?
Clients that still send it break only if the server rejects unknown properties. Many servers ignore them, so the change is marked for review rather than as certainly breaking — unless the new schema forbids other properties (additionalProperties: false): then requests that still send it are invalid, and the change is breaking.
Can I compare Swagger 2.0 with OpenAPI 3.1?
Yes. Both are read into the same model, so a Swagger 2.0 description and its OpenAPI 3.1 version that describe the same API show no differences — useful to check an upgrade, for example one made with the OpenAPI / Swagger Editor.
How is this different from a text diff?
A text diff shows changed lines, including reformatting and moved blocks, and cannot tell a harmless change from a breaking one. This compares what the descriptions mean: references are followed, order and formatting do not matter, and each change says whether it can break a client. For raw JSON or YAML differences, use the JSON Diff.