How can breaking changes in OpenAPI documents be detected automatically?

How can breaking changes in OpenAPI documents be detected automatically? #

One of the most disruptive events in an API program is an accidental breaking change — a modification to the API that breaks existing consumers without warning. As APIs scale across teams, products, and external partners, manually reviewing every change for consumer impact becomes impractical. Automated breaking change detection, powered by comparing OpenAPI documents across versions, is the solution. This article explains what constitutes a breaking change in OpenAPI, the tools that detect them, and how to integrate this capability into a CI/CD workflow.

What is a Breaking Change in OpenAPI? #

A breaking change is any modification to an API that causes existing, correctly-written clients to fail. In the context of OpenAPI documents, breaking changes include:

Removals:

  • Removing a path or operation that clients depend on
  • Removing a required request parameter
  • Removing a response field that clients read
  • Removing a security scheme

Additions that are required:

  • Adding a new required request parameter or required property in a request body — clients that don’t send the new field will now fail validation

Type and format changes:

  • Changing a property’s type (e.g., string → integer)
  • Narrowing an enum — removing a value that clients may send
  • Changing a path parameter name

Behavioral changes expressible in schemas:

  • Reducing maxLength — values that were previously accepted may now be rejected
  • Adding minLength, minimum, maximum, or pattern constraints
  • Changing nullable: true to type: string (removing null acceptability)

Non-breaking changes (consumers are unaffected):

  • Adding a new optional request parameter
  • Adding new optional properties to a response body
  • Adding a new path or operation
  • Adding a new enum value (for response enums — adding to request enums can be breaking)
  • Relaxing constraints (increasing maxLength, removing minimum)

oasdiff: Open-Source OpenAPI Diffing #

oasdiff is the leading open-source tool for detecting breaking changes between two OpenAPI 3.x documents. Written in Go, it is available as a CLI tool and Go library.

Installation #

brew install tufin/tufin/oasdiff
# or
go install github.com/tufin/oasdiff@latest

Basic Usage #

oasdiff breaking openapi-base.yaml openapi-revision.yaml

Output lists each breaking change with its location and a human-readable description:

1 breaking changes: 1 error, 0 warning
error   [response-property-removed] at ./openapi-revision.yaml
        in API GET /users/{id} response 200/application/json
        removed the response property 'email'

Exit Codes for CI Integration #

oasdiff exits with a non-zero code when breaking changes are found, making it straightforward to use as a CI gate:

oasdiff breaking openapi-base.yaml openapi-revision.yaml
if [ $? -ne 0 ]; then
  echo "Breaking changes detected — review required"
  exit 1
fi

Changelog Generation #

oasdiff can also produce a full changelog — listing both breaking and non-breaking changes between two versions:

oasdiff changelog openapi-base.yaml openapi-revision.yaml

This is useful for generating release notes or populating an API changelog automatically.

openapi-diff #

openapi-diff is a Java-based tool that compares two OpenAPI documents and classifies changes as compatible, incompatible (breaking), or unknown. It supports OpenAPI 2.0 and 3.x and can output results as text, HTML, or JSON.

java -jar openapi-diff.jar openapi-base.yaml openapi-revision.yaml --fail-on-incompatible

The --fail-on-incompatible flag causes the process to exit with a non-zero code when breaking changes are detected, suitable for CI pipelines.

Optic: Traffic-Aware Breaking Change Detection #

Optic takes a more comprehensive approach to breaking change detection. In addition to document-to-document comparison, Optic can capture real API traffic and compare it against the OpenAPI document, detecting divergences between the specification and the actual API behavior.

For pull request workflows, Optic integrates directly with GitHub:

# .github/workflows/api-check.yml
- name: Optic API check
  uses: opticdev/action@v1
  with:
    openapi_path: openapi.yaml

Optic posts a comment on each pull request summarizing what changed in the OpenAPI document — breaking changes in red, non-breaking additions in green — giving reviewers immediate visibility into the API impact of code changes.

Redocly CLI #

Redocly CLI includes a diff command for comparing two OpenAPI documents:

redocly diff openapi-base.yaml openapi-revision.yaml

While less specialized for breaking change classification than oasdiff, Redocly’s diff provides a human-readable summary useful during design reviews.

Integrating into GitHub Actions #

A complete breaking change detection workflow for GitHub Actions:

name: OpenAPI Breaking Change Check
on:
  pull_request:
    paths:
      - 'openapi.yaml'

jobs:
  breaking-change-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install oasdiff
        run: |
          wget https://github.com/tufin/oasdiff/releases/latest/download/oasdiff_linux_amd64.tar.gz
          tar -xzf oasdiff_linux_amd64.tar.gz
          chmod +x oasdiff          

      - name: Get base OpenAPI document
        run: git show origin/${{ github.base_ref }}:openapi.yaml > openapi-base.yaml

      - name: Check for breaking changes
        run: ./oasdiff breaking openapi-base.yaml openapi.yaml --fail-on-err

This workflow runs on every pull request that touches the OpenAPI document, comparing the PR’s version against the base branch. Breaking changes cause the check to fail, requiring explicit review and approval before merging.

Semantic Versioning from Breaking Changes #

oasdiff supports automated semantic version suggestion based on the nature of detected changes:

oasdiff diff openapi-base.yaml openapi-revision.yaml --format json | jq '.breakingChanges | length'

Teams can use this to enforce that:

  • PRs with breaking changes must bump the major version.
  • PRs with non-breaking additions must bump the minor version.
  • PRs with only documentation or description changes may use a patch version.

Managing Intentional Breaking Changes #

Not all breaking changes are accidents. Planned deprecations and major version bumps are legitimate. A robust breaking change workflow handles this by:

  1. Requiring an override label — in GitHub, require a breaking-change-approved label on PRs that introduce intentional breaking changes. The CI workflow checks for this label before failing.
  2. Documenting the change — require a changelog entry describing the breaking change and migration path.
  3. Sunset notifications — use OpenAPI’s deprecated: true flag and x-sunset extension to communicate planned removals to consumers well in advance.

Conclusion #

Automated breaking change detection transforms API governance from a reactive, incident-driven process into a proactive quality gate. Tools like oasdiff, openapi-diff, and Optic make it straightforward to compare OpenAPI documents across versions and surface breaking changes before they reach consumers. Integrating these tools into pull request CI/CD workflows ensures that every API change is reviewed for consumer impact, making accidental breaking changes a thing of the past.

Last updated on April 30, 2026.

This website is not affiliated with the OpenAPI Initiative.