An OpenAPI file can make an API change easy to see, but it cannot decide whether that change is safe. The useful question is narrower: would a client built against yesterday’s contract still send a valid request, parse the response and preserve the same business meaning?

That is what a breaking-change review should test. A green schema diff is helpful evidence, not a substitute for client examples, rollout rules and observed behaviour.

Treat the contract as an interface, not a document

The OpenAPI Specification defines a language-independent description of an HTTP API. Tools can use that description for documentation, client generation, server stubs and tests. Those uses make the file operational: a changed path, parameter or schema can alter generated code and validation even before a person notices the release note.

The top-level openapi field identifies the version of the OpenAPI Specification used to interpret the file. It is not the same as info.version, which describes the API document. Increasing info.version therefore records a release; it does not prove that old clients remain compatible.

Start a review by comparing the last contract that consumers could use with the proposed contract. A diff against an arbitrary branch or an unpublished intermediate file can produce the wrong answer.

Breakage depends on direction

Requests and responses have different compatibility risks.

For a request, the server receives data from an existing client. Making a previously optional field required can reject old traffic. Tightening a pattern, shortening a maximum length or removing an accepted enum value can do the same.

For a response, the client receives data from the server. Removing a field or changing its type can break parsing. Adding a new field is usually easier for clients that ignore unknown properties, but not every generated model or validator does. Adding a response enum value is also risky when a client treats the known set as exhaustive.

This direction test catches more real problems than a simple “added is safe, removed is breaking” rule.

Contract change Request risk Response risk
Add an optional property Usually low if the old default behaviour remains Usually low if clients tolerate unknown fields
Add a required property High: existing clients do not send it Depends on whether the server always supplies it and clients can parse it
Remove a property Existing clients may still send it High if clients read it
Change string to number High High
Narrow a range or pattern Previously valid requests may fail Previously returned values may no longer match client assumptions
Add an enum value Usually low for requests Can break exhaustive client code
Remove or rename an operation High High for every consumer that calls it

A rename is not a cosmetic edit. To a client, it is normally the removal of one component and the addition of another.

Seven changes that deserve a blocking review

1. Paths, operations and parameter locations

Removing /orders/{id}, changing GET to POST, or moving a value from a query parameter to a header changes how the request is constructed. Even when the new endpoint returns the same data, old integrations cannot discover the move by themselves.

2. Required request input

A new field can be added compatibly only when an omitted value keeps the old behaviour. Google’s API compatibility guidance states that new required fields must not be added to existing requests or resources, and that client-populated fields need a default matching the behaviour before introduction.

3. Types, formats and nullability

Changing an integer to a string can affect generated code, validation and comparison logic. Changing whether null is accepted can reject payloads or break a client that relied on a value always being present. Review the composed schema too: a change inside allOf, oneOf or a referenced component may affect many operations.

4. Enum values

Removing a value is plainly incompatible. Adding one to a response looks additive, but a mobile app or generated client may use a closed switch statement. Google’s guidance specifically calls for caution when response enums can receive new values.

5. Status codes and error shapes

Changing a successful 200 response to 202 introduces asynchronous behaviour even if both codes are valid HTTP. Replacing one error schema with another can break retry logic or remove an error identifier used by support. Diff the status and the business meaning, not only the JSON fields.

6. Security requirements

Adding a new required scope, replacing one authentication scheme or removing anonymous access changes who can call the operation. OpenAPI can describe alternative security requirements, but the review still needs to confirm the deployed authorization policy and transition plan.

7. Visible semantics

The file may remain structurally identical while behaviour changes. Pagination can gain a smaller default. Sorting can change. A field called amount can keep its number type while moving from major currency units to minor units. Google’s compatibility guidance treats visible semantic changes that are likely to break reasonable client code as breaking changes.

Use the diff to ask better questions

A contract-diff tool should classify changes, point to the affected operations and fail the build on agreed high-risk categories. It should not have the final word.

For every flagged change, record:

  • whether it appears in a request, response or both;
  • whether a field is read, written or generated;
  • which public clients or internal services use it;
  • whether old behaviour remains available;
  • whether code generation or strict validation is involved;
  • the earliest client version that understands the replacement;
  • the rollback path if traffic or errors change.

For every change the tool calls safe, sample at least one generated client and one real payload. Tool classifications differ, especially around enums, union schemas, additional properties and nullable values.

Put the contract check before deployment

A practical pipeline has four gates.

  1. Validate the proposed file. Confirm that references resolve, required OpenAPI fields are present and the document matches the intended specification version.
  2. Diff against the released baseline. Store that baseline as an immutable build artifact or release tag.
  3. Run consumer examples. Regenerate representative clients and replay request-response fixtures that include old optional fields, unknown response fields, enum handling and errors.
  4. Check the running service. Contract tests should confirm that deployed responses match the file and that authorization and business behaviour have not drifted.

The contract belongs in the same change review as the implementation. Updating it after deployment turns the diff into documentation of an incident rather than a release gate.

Deprecate before removal

OpenAPI allows fields and operations to be marked deprecated. The specification keeps deprecated features usable; the marker tells authors and tooling that a replacement should be preferred. It does not disable the old surface.

A useful deprecation plan names the replacement, gives consumers a date or condition for migration, keeps telemetry on old use and tests both paths during the overlap. Removal should wait until the promised support window ends and remaining callers are understood.

When incompatible change is unavoidable, a parallel path or major API version gives clients somewhere to move. A version label alone is not a migration: the new surface still needs a mapping, coexistence period and observable adoption.

A release checklist

Before approving an OpenAPI change, ask:

  • Is the baseline the last published contract?
  • Does the proposed file match the implementation?
  • Are any paths, operations or parameters removed or renamed?
  • Did a request become more restrictive?
  • Did a response remove data, change type or gain an enum value?
  • Did status codes, errors, pagination or ordering change meaning?
  • Did authentication or required scopes change?
  • Have generated clients and old payloads been tested?
  • Is a deprecation window documented where needed?
  • Can the release be rolled back without corrupting client state?

A contract review works when it turns an abstract compatibility debate into named consumers, concrete payloads and a reversible rollout.

When a request may be retried during a rollout, pair the contract review with our guide to API idempotency and duplicate operations.