oasdiff breaking: Detect Breaking OpenAPI Changes
oasdiff breaking base revision reports backward-incompatible changes between two OpenAPI specs and can exit non-zero when breaking changes are found.
Breaking-change detection is the highest-value API gate: it stops a PR that would break existing clients. oasdiff compares a baseline spec against the PR spec and classifies each change.
What it does
oasdiff has three modes: diff (full structural diff), changelog (human changes), and breaking (only backward-incompatible changes). breaking base revision prints each breaking change with an ID, level (ERR/WARN/INFO), and location.
Common usage
oasdiff breaking openapi-base.yaml openapi-revision.yaml
# fail the job when any ERR-level breaking change appears
oasdiff breaking base.yaml revision.yaml --fail-on ERR
# machine output for a PR comment
oasdiff breaking base.yaml revision.yaml -f jsonOptions
| Flag | What it does |
|---|---|
| --fail-on <level> | Exit non-zero at ERR or WARN (breaking mode) |
| -f, --format <fmt> | text, json, yaml, githubactions, junit, singleline |
| --exclude-elements <list> | Ignore parts, e.g. examples, description |
| --match-path <regex> | Limit comparison to matching paths |
| -l, --level <ERR|WARN|INFO> | Filter the severity shown |
| --composed | Treat inputs as globs of many spec files |
In CI
Keep the last released spec as a committed baseline (or fetch the merge-base version), then run oasdiff breaking base revision --fail-on ERR as a required check. Use -f githubactions so each breaking change annotates the diff. Store baselines per released version to catch regressions across the whole surface.
Common errors in CI
With no --fail-on, oasdiff exits 0 even when it lists breaking changes; you must pass --fail-on ERR to gate. Output lines look like error, in API GET /users removed the success response with the status '200' [response-success-status-removed]. "failed to load spec" means a bad path or invalid YAML. A summary such as 1 breaking changes: 1 error, 0 warning precedes the non-zero exit when --fail-on is set.