Most breaking changes in an API are visible in the OpenAPI diff before they ever reach a real client. Paste the old spec and the new spec into the API Breaking Changes Detector & Migration Planner and the tool returns the exact lines that will fail at runtime, with a severity grade and a suggested migration step for each. The rest of this guide is the field notes on what the diff actually catches, how to read the report, and how to turn the report into a release plan your team can ship.
The tool is a schema-aware diff between two OpenAPI 3.x documents (JSON or YAML). It walks every operation, every request body, every response, every parameter, and every schema definition, and it grades each change against the same five questions a human reviewer would ask. A removed endpoint is a different class of problem from a tightened type; the diff keeps the two separate so you can plan the work in proportion to the risk.
What counts as a breaking change, and what does not
The single most useful framing the report gives you is the distinction between additive and breaking. Additive changes add new fields, new endpoints, or new optional parameters. They cannot break a client that does not know about them. Breaking changes remove something the client was relying on, tighten a contract the client was meeting loosely, or rearrange a structure the client was parsing positionally. Every line in the report is labeled one or the other, and the suggested migration only appears for the breaking side.
A few patterns that look additive but are not:
Adding a required field to a request body is breaking. Old clients that omit the field are rejected.
Removing a response field is breaking. Old clients that read the field get undefined and may crash.
Narrowing a type from string to enum is breaking. Old clients that sent values outside the enum now fail validation.
Tightening a regex pattern is breaking. Old clients that sent values outside the new pattern now fail.
And a few that look breaking but are not:
Adding a new endpoint is additive. Old clients never called it.
Adding a new optional field to a response is additive. Old clients ignore it.
Relaxing a type from enum to string is additive. Old clients that sent the old enum values still pass.
Marking an operation deprecated is additive. The operation still works; clients that ignore the warning are unaffected.
The report keeps the two groups separate so a small additive change does not drown out the one breaking change hidden in the same diff.
The five categories the detector actually catches
Five categories of change appear often enough to deserve their own labels in the report. The rest are listed under “Other” but the same logic applies.
Removed paths or operations — An endpoint that existed in the old spec and disappeared in the new spec. Any client calling the path receives a 404 and any retry loop will amplify the failure.
New required fields — A field that was optional or absent in the request body and is now required. Old payloads missing the field are rejected at the schema validator. The migration step is to add the field, with a sensible default if one is available.
Type narrowing — A field that was string and is now enum, or a field that was integer and is now int64, or any other change that tightens the type. Old clients that sent values outside the new type now fail validation. The migration step depends on whether the old value can be coerced or must be rejected.
Response field removal — A field that was in the old response schema and is no longer in the new one. Old clients that read the field get undefined. JavaScript clients may crash on a downstream .toLowerCase() call; Python clients may raise a TypeError on a .format() call. The migration step is to drop the read or to default to a sensible fallback.
Status code shift — A response code that existed and is replaced with a different code. Old clients with code-specific retry logic hit the wrong branch on the new code. A 204 that becomes 200 is harmless; a 200 that becomes 204 can break clients that expected a body.
Format or pattern tightening — A field whose format, pattern, or minLength is now stricter. Old clients that sent values that passed the loose rule but fail the strict rule now see validation errors.
The six categories cover the vast majority of real breaking changes. A migration plan that addresses all six categories systematically is the difference between a release that ships clean and a release that pages the on-call at 3 a.m.
Reading the report: the five columns
The detector returns a report with five columns. The columns map directly to the questions a human reviewer asks, and the order matches the order you ask them.
Path or operation — The endpoint the change touches. For nested changes, the report gives the dotted path inside the spec, so a tightened requestBody.content.'application/json'.schema.properties.email shows up as email under /users:POST.
Change type — One of the six categories above, or “Other” for changes that do not fit. “Other” is rare; if you see it, the diff has found something the report does not have a label for, and the right next step is to read the change by hand.
Severity — CRITICAL, HIGH, MEDIUM, or LOW. Severity is a function of how many clients are likely to break, not how many lines the change touched. A single required field can be CRITICAL if the field is used by every client; a relaxed type is always LOW.
Affected clients — A count of generated SDKs, internal services, or known consumers that depend on the change. This is the closest thing the report has to a blast-radius estimate. The count is conservative; if you have a service that you know is affected but is not in the list, the report is not wrong, it just does not know.
Migration step — A one-line suggestion for how to fix the change. The suggestion is opinionated; treat it as a starting point, not a rule. “Add the field with a default” is the right step for a new required field with a sensible default; “drop the read” is the right step for a response field no downstream code uses.
When the diff is misleading
The detector is not a substitute for a human review. Three patterns trip it up.
Schema-only changes that look like breaking changes — A field renamed from customer_id to customerId shows up as “field removed” and “field added” in the same diff. The report flags both. The right next step is to recognize the rename pattern, mark the old field as deprecated rather than removed, and update the clients in a follow-up release.
Loose-to-loose changes — A field that was string and is still string but now with a pattern constraint. The report flags it as “format or pattern tightening” but the actual impact depends on whether the old client was already meeting the new pattern. If it was, the change is additive; if it was not, the change is breaking. The detector does not have visibility into client behavior, so it defaults to breaking.
Documentation-only changes — A description or summary field that was rewritten. The detector skips these, but a deeply nested doc change inside a requestBody schema can occasionally show up as “Other” if the path is not one of the standard fields. The right next step is to verify by hand that the change is doc-only.
The three patterns are the same patterns that trip up human reviewers. The detector catches the structural changes consistently; the semantic changes still need a human.
How the detector grades a real diff
A diff between two versions of a small OpenAPI spec is the easiest way to see the report in action. Imagine an old spec that defines POST /users with an optional name field, and a new spec that makes name required and adds an optional role field. The diff report has two lines: a HIGH-severity entry for “name becomes required” with the migration step “add the field with a default”, and an INFORMATIONAL entry for “role added” with no migration step. The first line is the breaking change; the second is the additive change.
A more complex diff between two large specs can return forty or fifty lines. The right way to read the report is to sort by severity, address the CRITICAL and HIGH lines first, and treat the MEDIUM and LOW lines as backlog. The severity grade is the tool’s opinion; you can override it, but the override should be a deliberate decision, not a default.
What the detector does not catch
The detector works on the schema layer. It does not catch:
Semantic changes that preserve the schema but change the meaning. A field that was “status code as integer” and is now “status code as enum” is a breaking change, but the detector cannot tell that 0 and pending mean different things in different parts of the system.
Side-effect changes — an endpoint that still returns the same response but now triggers a side effect (a webhook, a queue write, a database mutation). The schema is unchanged; the impact is not.
Authentication changes that move from API key to OAuth. The schema is unchanged; the auth header is different. The detector does not walk the security schemes.
Rate-limit changes that tighten the limit or change the error response. The schema is unchanged; the response is the same on the happy path.
These are all real breaking changes, and the detector does not catch them. The detector is the first pass; the human review is the second pass. Together, they cover most of the surface area a release can break.
How the detector fits a release pipeline
The right place to run the detector is between “spec is finalized” and “SDK generation starts”. The diff output becomes a checklist for the SDK team and a checklist for the platform team that owns the API. A release that has zero CRITICAL lines in the diff is a release that can ship without a coordinated migration. A release that has one or more CRITICAL lines needs a migration plan, a deprecation window, and a comms plan for the affected clients.
The detector is also a good fit for the pre-commit hook on the spec repository. Every PR that touches the spec gets a diff against main; every PR that introduces a CRITICAL line blocks the merge. This catches breaking changes before they reach the release branch, which is the cheapest place to catch them.
For more on the spec side of an API release, see the JSON Schema Validator and the OpenAPI Example Generator. The diff is the gate; the validator and the example generator are the tools you reach for on the other side of the gate.
The close-first summary in one paragraph
The API Breaking Changes Detector & Migration Planner is the diff between the spec you wrote and the spec you are about to ship, graded by the question every reviewer asks first: will the existing client still parse? Paste the two OpenAPI 3.x documents, pick the categories that matter to your release, and the report returns the breaking lines with a severity grade and a one-step migration suggestion. Use it as the gate between a finalized spec and a generated SDK, as a pre-commit check on the spec repository, and as the source of truth when the platform team needs to communicate the breaking changes to consumers. The detector is the first pass; the human review is the second pass; together they cover the surface area a release can break.
Explore more tools at elysiatools.com.
