oasdiff

Visit Website

Introduction

oasdiff compares two versions of an OpenAPI specification and tells you what changed. Its most important job is to detect breaking changes: modifications that would break existing API clients, such as removing an endpoint, making an optional parameter required, narrowing an enum or changing a response type.

The CLI has several commands. breaking lists only changes that break existing clients. changelog prints a human-readable list of all changes that can affect consumers, breaking or not. diff shows a full structural diff. validate checks a spec for violations such as invalid types, missing required fields, bad regular expressions and unresolved $refs. breaking-files checks changed spec files against their versions in a Git ref, which powers a pre-commit hook.

The rules that classify changes are documented and listable with oasdiff checks, and they can be customised, for example to change severity levels. The project also documents subtle cases such as nullability, where three equivalent ways of marking a field as nullable behave differently when changed. Output is available in several formats, and a JSON Schema describes the JSON output of breaking and changelog.

oasdiff runs locally, in Docker, or in CI through the official GitHub Action. The website also offers a hosted pull-request review workflow where a reviewer approves or rejects each API change and oasdiff posts a CI commit status. It is written in Go, has about 1,500 GitHub stars and released v1.37.0 on 8 November 2026.

In the quality loop, oasdiff is a release gate for API contracts. It complements a linter such as Spectral (style and correctness of one spec) and contract testing tools such as Pact or Specmatic (behaviour of real implementations): oasdiff focuses on compatibility between versions of the contract itself.

A practical pattern is to run validate first, then breaking against the main branch’s spec on every pull request, and post the changelog output as a comment so reviewers see the consumer impact in plain language.

The source code is at oasdiff/oasdiff on GitHub under the Apache-2.0 licence, with about 1,500 stars; the most recent commit was on 10 November 2026.

The most useful place for oasdiff is the pull request. Comparing the OpenAPI file on the main branch with the version in a change shows reviewers exactly what moved, and the breaking-change check can fail the build before an incompatible API reaches consumers. Teams should agree on what counts as acceptable: some breaking changes are intentional and versioned, so a documented way to override or acknowledge them avoids blocking legitimate work. Generated changelogs also help API consumers, because they describe changes in terms of endpoints and fields rather than raw YAML diffs.

Features

1. Breaking-change detection: Flags changes that break existing clients.
2. Human-readable changelog: Summarises all consumer-facing changes.
3. Full diff: Structural comparison of two specs.
4. Spec validation: Finds invalid types, missing fields and unresolved refs.
5. Git-aware checks: Compare changed files against a Git ref; pre-commit hook.
6. Customisable rules: List and adjust the checks used to classify changes.
7. Coverage map: See which checks cover each possible edit of an OpenAPI document.
8. GitHub Action: Fail pull requests that introduce breaking changes.
9. Hosted PR review: Approve or reject changes with a commit status on oasdiff.com.
10. Docker image: Run without installing Go.

Pros

1. Prevents accidental breakage: Turns API compatibility into an automated check.
2. Simple to adopt: One command in CI.
3. Free to use: Open source under the Apache-2.0 licence, so the core tool costs nothing to use.
4. Actively maintained: The repository had commits as recent as 10 November 2026.

Cons

1. OpenAPI only: No GraphQL, gRPC or AsyncAPI comparison.
2. Spec must be accurate: It checks the document, not the running service.
3. Some cases need judgement: Not every flagged change matters to every consumer.

Usage and Links (Example)

Compare a branch’s spec with main:

git show origin/main:openapi.yaml > /tmp/base.yaml
oasdiff breaking /tmp/base.yaml openapi.yaml --fail-on ERR
oasdiff changelog /tmp/base.yaml openapi.yaml

Or in GitHub Actions:

- uses: oasdiff/oasdiff-action/breaking@main
  with:
    base: 'https://raw.githubusercontent.com/org/repo/main/openapi.yaml'
    revision: 'openapi.yaml'
    fail-on: ERR

Practical tips:

1. Fail CI on breaking changes (--fail-on ERR) and post the changelog as a PR comment.
2. Pair with API versioning rules so intentional breaks go to a new version.
3. Run validate too, so broken specs never reach the comparison step.

Resources:

• oasdiff website
• GitHub repository

Pricing

oasdiff is free and open source under the Apache-2.0 licence.

Recommended for?

1. Teams publishing OpenAPI-described APIs to external or internal consumers.
2. API platform teams enforcing compatibility policies.
3. Not a fit for GraphQL or gRPC APIs.

Conclusion

oasdiff is a focused, actively maintained tool that answers one critical question for API teams: does this change break clients? It does so quickly and with clear, customisable rules.

Adding it to CI is one of the cheapest ways to prevent API incidents.

On CheckOps, oasdiff is filed under the API & contract testing and Release & CI gates stages. Related tools listed here include Spectral, Specmatic, Pact, Schemathesis, Stoplight Prism and Dredd. Before choosing, compare them on licence, supported languages and platforms, hosting model, and how well each fits your existing CI pipeline. Facts on this page were checked against the official website, documentation and repository on 11 November 2026; statements the vendor makes about its own product are marked as vendor claims.