oasdiff is a Go-based, Apache-2.0 command-line tool that compares OpenAPI specifications and detects breaking changes, built for API engineers and platform teams who need to know whether a spec edit will break existing API clients before it ships.

What it is

oasdiff lives in the OpenAPI tooling ecosystem and ships as a single Go binary with no server component. It compares two OpenAPI specs and classifies every difference between them through the subcommands breaking, changelog, and diff, and it also processes a single spec through validate, upgrade, and flatten. Around that core it adds git integration through breaking-files and git-diff-driver, a companion GitHub Action, and a hosted PR review workflow at oasdiff.com that approves or rejects each change with a CI commit status.

The concrete problem it solves is spec review by hand or by generic textual diff. A plain text diff cannot tell a team that a reworded description is harmless while a narrowed type or a removed response code will break callers, so reviewers either read the whole document or miss the breaking edit. oasdiff replaces that manual reading by classifying each change: changelog reports the changes that can affect API consumers, breaking or not; breaking narrows the report to changes that break existing API clients; diff returns the full machine-readable diff of the API definition, including documentation-only edits, in html, json, markdown, markup, text, or yaml. It also fits into the reviewer's existing git and CI habits rather than asking for a new review tool.

Key capabilities

• breaking lists only changes that break existing API clients, while changelog lists all changes that can affect API consumers in human-readable form.
• diff emits the full diff of the API definition in html, json, markdown, markup, text, or yaml (yaml by default), and summary gives a high-level count of changes built on the same diff engine.
• validate checks one spec for per-RFC violations such as invalid types, missing required fields, bad regex, and unresolved $refs.
• upgrade canonicalizes an OpenAPI 3.0 spec to the latest 3.x, and flatten replaces allOf schemas with a merged equivalent.
• breaking-files checks a list of changed specs against their versions in a git ref, one comparison per spec, and is used by the documented pre-commit hook.
• git-diff-driver runs as a git external diff driver so that git log --patch renders an OpenAPI changelog inline.
• checks changelog and checks validate list the classification rules, which can be customized, checks changelog coverage maps every possible OpenAPI edit to the checks that cover it, and schema prints a JSON Schema for breaking and changelog.

Who uses it and how

• CI pipelines that run the companion GitHub Action on pull requests, so every spec change gets a breaking-change verdict before merge.
• Teams that review API changes in the hosted workflow at oasdiff.com, approving or rejecting each individual change and recording the decision as a CI commit status.
• Local development, where the documented one-liner runs the tufin/oasdiff Docker image against two specs and prints a changelog without any installation.
• Version-control-centric teams that install the pre-commit hook backed by breaking-files, or set git-diff-driver as the external diff driver and read the changelog directly in git log --patch.
• Maintainers of specs that have drifted on schema style, who run upgrade to canonicalize a 3.0 document or flatten to collapse allOf compositions.

Getting started

Install with go install github.com/oasdiff/oasdiff@latest, or with brew install oasdiff, the curl-based install.sh script, asdf, or a pre-built binary for macOS, Linux, or Windows on x86_64 and arm64. To run without installing, use the Docker image tufin/oasdiff, as in docker run --rm -t tufin/oasdiff changelog against two specs.

How it compares

The provided facts name no paid products that oasdiff replaces and no comparable tools, so it stands alone in this registry. There is no licence, hosting, or pricing contrast to draw here, only the Apache-2.0 CLI, the GitHub Action, and the optional hosted workflow on its own homepage.

When to use it — and when not to

The facts describe no database, object storage, or SMTP requirement, so a self-hoster runs a single binary and, at most, a container image. It is a poor fit for teams that do not keep OpenAPI specs in git or have no CI pipeline to attach the check to, and the facts show no Swagger or OpenAPI 2.0 handling, only 3.0-to-3.x conversion through upgrade. The README excerpt also stops mid-sentence in the command reference for schema, so parts of the documentation still read as incomplete.

docker run --rm -t tufin/oasdiff changelog \
  https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml \
  https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test5.yaml

go install github.com/oasdiff/oasdiff@latest

brew install oasdiff

curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh

curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | version=1.11.7 sh