# 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.

- URL: https://tools.itlibra.com/en/openapi-diff
- On-device・No upload
- Last updated: 2026-10-26

## 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.

## 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

## 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.


## Supported formats

### Input

- OpenAPI 3.0.x
- OpenAPI 3.1.x
- Swagger 2.0
- .yaml / .yml / .json
- UTF-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

| Feature | Support | Notes |
| --- | --- | --- |
| Comparing two OpenAPI 3.0, 3.1 or Swagger 2.0 definitions | Supported | — |
| Added and removed paths and operations | Supported | — |
| Parameter changes: required, removed, location (in), type, format and enum | Supported | — |
| Request and response schemas: properties, types, required and enum | Supported | Nesting 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 URLs | Not supported | Nothing 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 supported | Actual usage is unknown, so the verdict follows general compatibility practice |
| Changing the verdict to match an API policy | Not supported | The 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.x | Partial | Only matching items are compared. A change that cannot be matched may not appear in the verdict |
| Per-candidate judgement of oneOf and anyOf | Partial | Only the addition or removal of candidates is shown, as caution |
| Calling the API to check its real behaviour | Not supported | — |
| Offline use | Supported | Works 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.