01 / THE THREE CATEGORIES
Breaking, additive, and cosmetic — a taxonomy, not a highlight.
An OpenAPI spec changes for many reasons. A bug fix removes a path that was never used in production. A new feature adds an optional query parameter. A documentation pass rewrites twenty descriptions. A text diff treats all three edits the same way: deleted lines and added lines. But the risk to clients is different in each case.
Apibreak classifies every difference into one of three categories. Breaking changes cause existing clients to fail — a removed endpoint, a required parameter, a narrowed type. Additive changes add new capabilities without affecting clients that ignore them — a new endpoint, an optional parameter, a new response field. Cosmetic changes have no semantic impact — description rewrites, example updates, key reordering. The categories follow directly from OpenAPI specification semantics.
02 / ENDPOINT REMOVAL
A deleted path is the clearest breaking change.
Removing an entire path or a specific HTTP method from an existing path means every client that calls that endpoint receives a 404 response. There is no graceful upgrade path — the client must stop calling the endpoint or handle the error. This is always breaking, regardless of how long the endpoint has been deprecated in documentation.
Renaming a path parameter — for example, changing /users/{id} to /users/{userId} — is also a breaking change under the specification, because the parameter name is part of the contract. Old clients that reference the old parameter name in their code will not match the new template.
03 / PARAMETER CHANGES
Query, path, header, and cookie parameters all carry breaking risk.
A parameter that was optional becoming required is breaking. Existing clients that omit the parameter will begin sending malformed requests. Conversely, removing a parameter entirely is also breaking — clients that were sending it will include stale data or trigger validation errors.
Narrowing a parameter type is breaking too. Changing a parameter from string to integer, from any type to enum, or from a broad pattern to a stricter one means existing values that once passed validation may now fail. Adding new constraints — a new minimum length, a new regular expression — has the same effect. Widening a type (adding an accepted value to an enum) is additive, not breaking, because existing values remain valid.
04 / RESPONSE CHANGES
Clients depend on the shape of what comes back.
Removing a response status code that clients handle — for example, dropping the 200 response from a GET endpoint and keeping only 201 — forces every client that parses the 200 response to deal with a missing case. This is breaking.
Removing a property from a response schema is also breaking. If a client deserialises the response body and expects a field that no longer appears, the client breaks at runtime. Changing the type of a response field — from string to integer, or from number to integer — narrows the contract and breaks clients that have already handled the wider type. Adding new optional fields to a response is additive, not breaking, as long as existing required fields remain unchanged.
05 / SCHEMA AND TYPE NARROWING
Schema changes cascade across every path that references them.
When a reused schema component — defined under components/schemas — changes, every endpoint that references it is affected. Changing a schema property from type: string to an enum with a fixed set of values is breaking: clients that have been sending arbitrary strings now face rejection. Changing from integer to number is additive (the set widens), but changing from number to integer is breaking (the set narrows).
Format changes behave the same way. Narrowing a format — from format: date-time to format: date, for example — restricts the set of valid values. Adding a minimum or maxLength constraint that did not exist before is breaking for any client whose data falls outside the new bounds. These patterns are often missed in textual reviews because a single line in a schema file propagates across dozens of endpoints.
06 / CATCH BREAKING CHANGES BEFORE YOUR CLIENTS DO
Try Apibreak on your own specs.
Upload or paste two OpenAPI or Swagger specs — your spec today against last week's version, or your feature branch against main. Apibreak normalises both specs, walks the structural tree, and classifies every difference as breaking, additive, or cosmetic. No account, no upload to a server, no stored data.