A breaking change is any API change that breaks an existing client. They're easy to introduce and easy to miss in review — and they're exactly what driftwire diff catches automatically.
OpenAPI doesn't flag breaking changes for you — a diff tool must. The changes that break real clients:
| Change | Why it breaks clients |
|---|---|
| Removed endpoint or HTTP method | Calls start returning 404/405. |
| Removed field / parameter / enum value | Request or response payloads change shape. |
Added a required field | Existing requests are rejected as invalid. |
| Changed a field's type or format | Client deserialization fails silently. |
| Removed or narrowed a response code | Client error handling paths break. |
Spec diffs are dense and easy to misread by eye. A single renamed enum value or a required added deep in a nested schema is invisible in a normal PR. Teams that catch these manually usually catch them after a customer reports the outage.
# compare two spec versions and fail on any breaking change
driftwire diff openapi@v1.yaml openapi@v2.yaml
# exit 1 when a breaking change is found — blocks the mergeIt also runs as a GitHub Action (Haswell119/driftwire@main): drop it into on: [pull_request] and every spec change is gated automatically.
Paste two OpenAPI specs into the live demo and see every breaking change, severity-colored:
▶ Open the live demo View source (MIT)Related: API drift detection — is your live API still matching its spec?