日本語English

OpenAPI Diff (Breaking Change Checker)

Paste the old and new OpenAPI (or Swagger 2.0) definitions to list the changes that break clients: removed paths, newly required fields, type changes and more. Each change is sorted into breaking, caution or non-breaking, with the reason on its row. Nothing leaves your browser.

On-device・No uploadMobile friendlyWorks offline

Your files and input are processed only inside your browser on this device and are never uploaded to our servers.

Before (old definition)
0 / 2,000,000
After (new definition)
0 / 2,000,000
Up to 2 million characters and 3,000 operations per definition. Press Ctrl (⌘) + Enter to run.
Press “Compare” to see the results.
Rules
  • Breaking Changes that often break existing clients
  • Caution Changes whose effect depends on the implementation or the call
  • Non-breaking Changes existing clients can ignore
LevelWhy
BreakingThe path was removed. Clients calling it fail, for example with 404.
BreakingThe operation (method) was removed. Clients calling it fail.
Non-breakingAn operation was added. Existing calls are not affected.
BreakingAuthentication or authorization is now required. Clients that send no credentials are rejected.
CautionAuthentication is no longer required. Behaviour widens; check that this was intended.
BreakingA success (2xx) status code was removed. Clients that rely on that response change behaviour.
CautionA non-success status code was removed. Error handling may no longer be needed, or an unexpected code may arrive.
Non-breakingA response status code was added. Existing handling is unchanged.
BreakingA request Content-Type that was accepted is gone. Clients sending that type fail.
Non-breakingA request Content-Type was added.
BreakingA response Content-Type is gone. Clients that expect that type break.
Non-breakingA response Content-Type was added. Existing clients are unchanged.
BreakingA required request body was added. Clients that did not send one fail.
Non-breakingAn optional request body was added.
CautionThe request body was removed. Whether sent values are ignored or rejected depends on the implementation.
BreakingThe request body went from optional to required. Clients that omitted it fail.
Non-breakingThe request body went from required to optional.
BreakingA required parameter was added. Clients that did not send it fail.
Non-breakingAn optional parameter was added.
CautionA parameter was removed. Whether sent values are ignored depends on the implementation.
BreakingAn optional parameter became required. Clients that omitted it fail.
Non-breakingA required parameter became optional.
BreakingThe location (in) of a parameter with the same name changed. Clients send it to the wrong place and fail.
BreakingThe parameter type or format changed. Current values may no longer be accepted.
BreakingThe parameter accepts fewer values. Clients sending a removed value fail.
Non-breakingThe parameter accepts more values.
BreakingA required property was added to a request. Clients that did not send it fail.
Non-breakingA property was added. In a request it is optional; in a response clients can ignore it.
CautionA request property was removed. Whether it is ignored depends on the implementation (rejected if additionalProperties is false).
BreakingA response property is gone. Clients that read it break.
BreakingA request property went from optional to required. Clients that omitted it fail.
Non-breakingA request property went from required to optional.
Non-breakingA response property is now always present.
CautionA response property went from required to optional. Clients that assume it is always there should be checked.
BreakingThe type changed (for example string to integer). Values are read differently and clients break.
CautionThe format changed. The meaning may differ, so check it.
BreakingThe request accepts fewer values. Clients sending a removed value fail.
Non-breakingThe request accepts more values.
Non-breakingThe response has fewer possible values. Only branches for those values become unnecessary.
CautionThe response has new values. Clients may receive a value they do not know.
CautionThe oneOf / anyOf candidates were added or removed. Each candidate is not judged, so review the content.
CautionThis $ref points to a file or URL that is not loaded, so this place was not compared. A change here would not be detected, so review the content.
The verdict follows general compatibility practice. Each API may have its own policy.

How to use

  1. Paste the old definition on the left and the new one on the right, or open files with “Open file” (YAML or JSON; OpenAPI 3.0 or 3.1; Swagger 2.0). “Try a sample” also works.

  2. Press “Compare” (or Ctrl / ⌘ + Enter). The counts for breaking, caution and non-breaking changes and a one-line verdict appear. If there is a breaking change, the verdict is equivalent to exit code 1.

  3. Filter the list by level. Each row shows the path, method, location, detail and the reason for its level. The rules are listed below the results.

  4. Use “Copy Markdown” to paste a table into a pull request description, or “Save JSON” to keep the verdict, counts and changes in a form a program can read.

What it does

Sorts breaking changes

Removed paths and operations, newly required fields, type changes and removed response properties are grouped as breaking. Caution and non-breaking changes are shown separately.

A reason on every row

Each row says, in English, which rule put it in its level. The full rule list is on the page, so the basis of a verdict can be used directly in a review.

Resolves $ref before comparing

Follows $ref inside the same definition (#/components/... or #/definitions/...) and compares the schema contents. A circular definition still stops.

Markdown and JSON export

Save a Markdown table for a pull request, or JSON that a program can read. The verdict is also shown as one line, like an exit code.

Runs only in your browser

The definitions are compared in a Web Worker inside your browser. Nothing is sent, and external $ref values are not fetched.

Use cases

  • Check whether an API revision breaks existing clients before opening a pull request
  • Find added required fields and removed paths before a review
  • Compare internal API definitions without sending them outside
  • Get just the one-line verdict on whether a change is breaking

Supported formats

Input

OpenAPI 3.0.xOpenAPI 3.1.xSwagger 2.0.yaml / .yml / .jsonUTF-8 (with or without BOM)

Output

On-screen list (filter by level)Markdown (table for a pull request)JSON (verdict, counts and changes)

Capability matrix

FeatureSupportNotes
Comparing two OpenAPI 3.0, 3.1 or Swagger 2.0 definitionsSupported—
Added and removed paths and operationsSupported—
Parameter changes: required, removed, location (in), type, format and enumSupported—
Request and response schemas: properties, types, required and enumSupportedNesting is followed to depth 12. Deeper parts are not compared and are noted
$ref inside the same definition (#/components/... and #/definitions/...)Supported—
Fetching $ref in other files or at URLsNot supportedNothing is fetched, because the tool does not connect to the network. They are shown as unresolved
Impact on real clients (which callers would break)Not supportedActual usage is unknown, so the verdict follows general compatibility practice
Changing the verdict to match an API policyNot supportedThe rules can be read on the page, but there is no setting that changes the levels
Mixed comparison of Swagger 2.0 and OpenAPI 3.xPartialOnly matching items are compared. A change that cannot be matched may not appear in the verdict
Per-candidate judgement of oneOf and anyOfPartialOnly the addition or removal of candidates is shown, as caution
Calling the API to check its real behaviourNot supported—
Offline useSupportedWorks without a connection once the page has loaded

Limits & notes

  • Up to 2 million characters and 3,000 operations per definition. Files up to 5 MB.
  • Up to 1,000 changes are listed and exported. The counts cover every change.
  • Schemas are followed to depth 12, and up to 20,000 schema comparisons are made. The rest is not compared and is noted.
  • When comparing Swagger 2.0 with OpenAPI 3.x, some matching items may not be found.
  • The verdict follows general compatibility practice. Each API may have its own policy.

Privacy & safety

Definitions are compared only inside your browser. Nothing is sent or stored, and external $ref values are not fetched. Closing the page discards the content. Analytics only record that a run happened, with no content or counts.

FAQ

What is a breaking change in OpenAPI?
A change after which existing clients stop working as before. Removing a path, adding a required request field and changing a type are examples. This tool judges by general compatibility practice.
Is the breaking verdict accurate?
It follows general compatibility practice. It cannot know your API policy or which clients use what. The rules are shown on the page, so the final decision should be made in review.
Can it compare Swagger 2.0 with OpenAPI 3.0?
Yes, but the two versions are written differently, so only matching items are compared. Comparing two definitions of the same version is more reliable.
Are $ref values in other files compared?
No. The tool resolves $ref only inside one definition. References to other files or URLs are not fetched and are shown as unresolved.
How do I paste the result into a pull request?
Use “Copy Markdown” to copy the verdict, counts and the table of changes. The first line states whether a breaking change exists.

OpenAPI Studio — Viewer & Validator

Paste an OpenAPI 3.0 / 3.1 or Swagger 2.0 definition to browse endpoints by tag and schemas as trees, and to check it against the official schemas with line and column. It never calls the API or fetches external files, and nothing leaves your device.

No upload

Diff Tool — Text & Code Compare

Paste or drop two versions and see added and removed lines, plus the exact words that changed inside each line. Copy or save the result as a unified patch. Nothing leaves your browser.

No upload

JSON Studio — Formatter & Validator

Paste JSON to format, minify or validate it instantly. Errors are shown with the exact line, column and cause, and comments or trailing commas can be auto-repaired. Your data never leaves your device.

No upload

UUID / ULID / NanoID / Token Generator

A UUID is ready the moment the page opens. Switch to UUID v7, ULID, NanoID or a random token, generate up to 10,000 at once and save them as .txt, .csv or .json. Paste an existing UUID or ULID to read its embedded time and version.

No upload

Regex Tester

Type a pattern and matches light up in the test string instantly. Capture groups, replacement output and what each part of the pattern means are all on one screen — and patterns that would freeze your browser are stopped after one second.

No upload

Code Formatter — Format & Minify

Paste code to format it with the language auto-detected. Choose indent, line width, semicolons, quotes and trailing commas; JavaScript, CSS and HTML can also be minified with before/after size and reduction. Your code never leaves the browser.

No upload

Last updated: