What counts as a breaking change in an OpenAPI spec?

Updated October 2026 · 7 minute read

A breaking change is any change to your API contract that can make an existing, correctly written client fail. Whether a change breaks clients depends on the direction data flows: tightening what the API accepts breaks requests, and loosening what it returns breaks code that reads responses.

Breaking: almost always

  • Removing an endpoint or method (DELETE /payments/{id} disappears).
  • Adding a required parameter or request field. Existing clients don't send it.
  • Making an optional parameter or field required.
  • Removing a field from a response. Clients that read it get undefined.
  • Changing a type – integer to string, object to array.
  • Removing an accepted enum value from a request field.
  • Removing a success response code or a response content type clients rely on.
  • Removing a security scheme clients authenticate with.

Usually safe, but worth checking

  • Adding an enum value to a response. Clients with exhaustive switch statements or strict deserializers can fail.
  • Deprecating an endpoint or parameter. Not breaking yet, but a signal to plan.
  • Changing security requirements on an operation.
  • A response field no longer marked required. It may now be missing.
  • Removing an optional request parameter. Usually ignored, sometimes rejected.

Safe: additive changes

  • Adding endpoints, optional parameters or optional request fields.
  • Adding response fields (assuming clients ignore unknown fields).
  • Description, summary and example changes.

Path parameter renames are not breaking

Renaming /pets/{petId} to /pets/{id} doesn't change any URL a client calls. Good diff tools treat the paths as the same endpoint.

How to catch breaking changes

  1. In CI: run an OpenAPI diff tool (for example the open-source oasdiff) against the spec on your main branch and fail the build on breaking changes unless the version is bumped.
  2. In code review: keep the spec in the same repository as the code, so contract changes show up in the pull request.
  3. For everyone else: the people who need to know – support, solutions engineers, partner managers – don't read pull requests. Publish the spec where they work and tell them when the contract changes.

That last step is why we built API Docket for Confluence. It records every version of a linked specification, applies the rules above, and shows a changelog on the page with breaking changes flagged – so the people reading your docs see what changed without reading a diff.