How to Detect Breaking Changes in OpenAPI

What is an API contract change?

An OpenAPI document describes operations, parameters, request bodies, responses, and schemas. Compatibility is directional: requiring a new request field affects callers that omit it, while removing a response field affects callers that read it.

How to compare two specifications

• Use the released contract as the source and the proposed contract as the target. Reversing them reverses additions and removals.
• Paste the two YAML or JSON documents with a line containing === TARGET === between them.
• Run OpenAPI Diff for operation additions, removals, and changes; run Breaking Change Checker for selected compatibility warnings.
• Review Schema Diff and Migration Report separately, then exercise representative clients against the changed API.

Example: removing an endpoint

The source below exposes GET /users. The target removes it. OpenAPI Diff reports Removed: GET /users; the breaking change checker reports Breaking change: GET /users was removed.

openapi: 3.0.3
info:
  title: Example API
  version: "1.0"
paths:
  /users:
    get:
      responses:
        "200":
          description: Users returned
=== TARGET ===
openapi: 3.0.3
info:
  title: Example API
  version: "2.0"
paths: {}

Common mistakes

• Comparing implementation branches without keeping a released baseline: consumers may still use an older deployed contract.
• Treating every textual change as a break: descriptions and formatting can change without changing behavior.
• Ignoring an added required query parameter or request field: existing clients might not send it.
• Assuming a successful structural check proves full OpenAPI compliance or runtime compatibility: those are separate checks.

Limitations of these local checks

The tools inspect inline operations and selected schema differences. They do not fetch external references, fully resolve $ref relationships, or model every composition, serialization, security, and compatibility rule. The basic validator checks common document structure rather than the complete specification.

A 'no common breaking changes' result is a starting point for review. Inspect referenced schemas, authentication changes, enum restrictions, response types, and client code; supplement the review with a contract checker and integration tests suited to your API.

Practical use cases and security

Include a saved before/after contract in release review, identify affected operations, and document migration steps for each consuming client. For a removed endpoint, plan a replacement and deprecation period before deployment.

The comparison runs locally and does not contact the servers listed in the specification. Remove embedded example credentials and private infrastructure names before sharing the resulting report.

Related tools

• OpenAPI Diff — Compare endpoint and operation changes between two OpenAPI documents.
• OpenAPI Breaking Change Checker — Flag removed operations and newly required request fields between API specs.
• OpenAPI Schema Diff — Compare named component schemas between two OpenAPI documents.
• OpenAPI Migration Report — Summarize endpoint, component schema, version, and server URL changes between two specifications.
• OpenAPI Validator — Check OpenAPI documents for valid YAML or JSON and essential structure.

References

• OpenAPI Specification 3.0.3