Flag likely breaking API changes before release

The job to be done

Catch the contract change before a client does.

An OpenAPI file can change in a pull request without anyone noticing that a response field disappeared, a query parameter became required, or an enum lost a value. In a long specification, edits like these hide among formatting changes and new endpoints.

Diff Anything compares the released specification and the candidate as parsed documents in API Schema mode and labels changes that match its breaking-change rules with a rule code. The labels give you a short list to read first; deciding whether clients are affected remains your call.

Recommended path

From the released spec to a reviewed list of changes.

Use the specification clients depend on today as the left side and the proposed version as the right side.

1. Open both specifications

   Choose OpenAPI, Swagger, or JSON Schema files written in JSON or YAML. Auto recognises them from their top-level openapi, swagger, or $schema key and opens API Schema mode.

2. Read the verdict

   A note above the result gives the count of potentially breaking changes, or says the schemas are equivalent. When no rule matches, it reminds you that manual contract review is still required.

3. Filter to Breaking

   Choose Breaking in the Differences pane filter. Each entry shows its rule code, such as API001 for a removed operation or API004 for a new required input, and the path of the change.

4. Read what the rules leave unlabelled

   Switch back to All. A changed pattern or a renamed parameter appears without a rule code, and inserting a parameter can shift the positions of the ones after it.

5. Gate the build

   With Pro in the Microsoft Store version on Windows, run --mode api --fail-on breaking, or set failOn: breaking for the pair in a batch manifest that writes JUnit or SARIF. Identical schemas pass, and the job fails only on breaking or unclassified changes.

Capabilities involved

How the three capabilities fit an API review.

Limits to know

Read the labels as a starting point.

The rules judge a change by its location in the document. They do not resolve $ref and treat request and response schemas alike, so some flagged items are harmless, and some breaking edits, such as a renamed parameter, a removed components entry, or added additionalProperties: false, carry no rule code.

A passing --fail-on breaking check means no rule matched, not that clients are unaffected. Keep a person in the loop for changes the rules cannot judge.

Semantic rules such as Ignore paths do not apply in API Schema mode. Free shows complete API results in the app within the 5 MB and 10-per-day limits; the api command-line mode and batch manifests need Pro.

Related manual

Use Diff Anything from the CLI, Git, and CI

Run repeatable comparisons, read highlighted terminal output, interpret exit codes, integrate with Git, and publish machine-readable CI results.

Its sections cover find the installed executable, enter explicit cli mode, interpret exit codes, choose output for the consumer, configure git difftool, use diff anything for git diff, run batch manifests, debug automation failures. Use it when you are ready to reproduce this workflow with your own project data.

Direct answers

Questions about this use case.