OpenAPI Breaking Changes: The Complete List of Rules

How oasdiff decides what is breaking

oasdiff judges a change against the API contract your OpenAPI definition declares, not against what a particular server happens to accept. A change is breaking if a consumer that followed the old contract can stop working under the new one.

This matters because an OpenAPI definition declares which requests and responses are valid, but most servers do not enforce it at runtime, and a server may quietly accept a request the contract says is invalid. oasdiff still reports the change as breaking, because other consumers of the same contract do enforce it: API gateways and validators reject non-conforming requests, and generated client SDKs turn the contract into typed code that no longer compiles. Whether your own server is lenient is your choice to make; it does not mean the contract is unchanged.

Each check's severity is derived from two things: which side of the API the change is on, and its effect on the set of valid messages (shown on every rule page below). Requests flow from the client, responses to it, so the same effect breaks in opposite directions:

• Narrowing a request is breaking: a request that was valid before can now be rejected. Widening a request is not, since everything clients already send stays valid. For example, adding a required request property is breaking, whether or not the property has a default: a default is a server-side fallback value, and a request that omits the property is invalid under the new contract.
• Widening a response is breaking: the API can now return something clients were never written to handle. Narrowing a response is not, since everything clients can still receive was already possible before. The exception is a response option the client selects or relies on, such as a status code or a media type: withdrawing one is breaking even though it narrows the response.
• A change whose effect the definition cannot determine is a warning, with a note saying what is missing, such as a change to an object parameter whose serialization the definition leaves unspecified. A warning is not used for changes that break some setups and not others; those are errors.
• Violating a deprecation promise, such as removing an endpoint before its sunset date, is breaking by policy even when the wire contract question does not apply.

When a change cannot be proven safe, oasdiff reports it as breaking: reporting a safe change as breaking costs a reviewer one look, while reporting a breaking change as safe ships it to production. This derivation is enforced by tests in the oasdiff codebase, so a check's severity cannot drift from the rule above.

The definition itself can also show that a specific change is safe. A property marked readOnly never appears in a request, so restricting it cannot invalidate one; the same holds for writeOnly properties in responses. Such a change is reported at info, below its check's listed severity, with a comment stating the reason.

If a check's default severity does not match your API's compatibility policy, you can raise, lower, or disable it per check with a severity-levels file.

Every possible change, decided

OpenAPI gave API definitions a formal model. oasdiff does the same for API changes: every field of the specification, and every way each one can change, is enumerated, more than 15,000 possible edits. Every one of them is either covered by a check or excluded with a written reason. None are undecided, and the build fails if a new OpenAPI field appears that we have not classified. You can inspect this yourself: oasdiff checks changelog coverage lists every edit with the checks that cover it or the reason it is excluded.

Combined with the severity derivation above, this is what lets oasdiff promise that no breaking change your contract can express gets through unnoticed. Breaking changes stop being accidents and become decisions: seen, reviewed, and approved by a person, or not shipped.

The model itself is public: the vocabulary, the severity law, every named change with the document locations it covers, and the full coverage listing are published as one machine-readable file in the OpenAPI Changes Model repository, regenerated from every oasdiff release. If you believe a change is classified wrongly, open an issue there; disagreement with a verdict is the most valuable contribution.

The contract is the boundary of the promise: a change in behavior your definition does not describe is invisible to any specification-based tool, which is one more reason to keep the definition faithful to the API.