oasdiff

oasdiff is a tool for comparing OpenAPI specifications and reviewing API changes before release. It suits teams that want contract checks in scripts or pull requests, as well as a browser option for occasional reviews. Its OpenAPI change coverage is broad, but it does not cover AsyncAPI or GraphQL.

Overview

oasdiff compares OpenAPI specifications, creates changelogs, and identifies breaking and non-breaking changes. It supports OpenAPI 3.0, 3.1, and 3.2, with detection for 755 distinct types of change. That makes it useful for ongoing contract review, not only for catching obvious compatibility breaks at release time. Its scope is deliberately narrow: teams using AsyncAPI or GraphQL contracts will need another tool.

The comparison engine, CLI, and GitHub Action are open source under Apache 2.0. A browser diff and hosted review plans extend the same workflow, while self-hosted deployment is also supported.

Key features

Fits automation and manual review

The CLI installs through Homebrew, a shell installer, Docker, or pre-built Linux, macOS, and Windows binaries. It produces text, JSON, YAML, HTML, Markdown, and GitHub Actions annotations, which gives teams options for scripts, reports, and CI output. Composed mode compares collections of OpenAPI files together, a useful distinction for APIs divided among multiple services.

The GitHub Action compares a pull-request specification with its base branch and adds inline breaking-change annotations. That puts compatibility issues where reviewers can act on them, rather than leaving them to be found in a separate report. For ad hoc comparisons, the web diff tool works without installation or sign-up and can export text, YAML, JSON, Markdown, or HTML.

Review workflow and privacy

Specs and changelogs are encrypted in the browser before upload; the server retains ciphertext that oasdiff cannot read. Free review links last seven days, which is adequate for short review cycles but can be inconvenient for teams that need a durable record. Pro reviews remain for the life of the pull request. Enterprise can instead load specs directly from GitHub at review time using each reviewer's access, without uploading or storing the specs.

A hosted MCP server connects oasdiff to Claude, Cursor, and other Streamable HTTP MCP clients. It adds an AI-client entry point, though the core product remains centered on comparing OpenAPI contracts.

Pricing

oasdiff uses a freemium model, with a free plan and a 30-day trial. The free tier is billed Free forever and costs nothing. It includes CLI diffing, breaking-change detection and changelogs, GitHub Action inline pull-request annotations, side-by-side review, and encrypted spec storage, with no account required. That is a capable starting point for individuals or teams willing to work without formal review controls; its review links expire after seven days.

Pro costs $100 a month, billed $100/month. It adds an approval workflow, audit trail, and merge gate, and supports up to 5 reviewers across 5 repositories. This is the practical tier for teams that need enforced review steps and a record of decisions, but the reviewer and repository ceilings may constrain larger groups.

Enterprise has custom pricing. It includes unlimited repositories and reviewers, an SLA, dedicated support, and an optional no-upload GitHub mode. It fits organizations that need those scale and service commitments or a stricter data-handling path; the price is custom rather than a fixed monthly amount.

Platforms

oasdiff supports API, Linux, macOS, Windows, web, and self-hosted use. The multiple CLI distribution routes make it accessible across the major desktop environments, while the browser tool removes setup for one-off comparisons. Teams can also run a self-hosted deployment, but the product's contract-format support remains limited to OpenAPI 3.0, 3.1, and 3.2 in JSON and YAML.

Who it's for

Choose oasdiff if your API contracts are OpenAPI-based and you want change detection available in the terminal, a pull request, or a browser. Its open-source engine and no-account free plan suit teams starting with automated checks; Pro is more appropriate when approvals, audit history, or merge blocking are required. Look elsewhere if you need AsyncAPI or GraphQL support, or if your review process exceeds Pro's stated limits and does not justify Enterprise.

Pros and cons

Pros: Broad detection across 755 breaking and non-breaking change types helps surface more than compatibility failures alone.

Pros: CLI, GitHub Action, browser diff, and composed comparisons accommodate both automated checks and multi-service specifications.

Pros: Client-side encryption and Enterprise's optional no-upload GitHub mode address different levels of sensitivity.

Cons: No AsyncAPI or GraphQL support rules it out for teams whose contracts use those formats.

Cons: Free review links expire after seven days, while Pro's $100/month plan caps use at five reviewers and five repositories.

Alternatives

For broader contract-testing choices, compare the Contract Testing Tools, API Governance Software, and API Design Tools directories.

Pick Pact if you want free open-source contract-testing tooling rather than an OpenAPI comparison and review workflow. Microcks is a free, fully open-source option if a community-driven CNCF Incubating project is a better fit. Choose Pact Broker for contract-testing coordination, including a free Starter plan with unlimited users, two integrations, and bi-directional contract testing.

Confluent Cloud is worth considering when you want its free Basic tier for managed Kafka clusters, autoscaling resources, and more than 80 managed connectors. If your work centers on GraphQL schemas, GraphQL Hive is the more relevant choice; its Hobby tier includes 1M operations per month and seven-day usage-data retention. Karate may suit teams seeking a free MIT-licensed framework spanning REST, GraphQL, and SOAP API testing as well as browser and desktop UI automation. Choose Specmatic if you need contract testing across OpenAPI, WSDL, or MCP alongside resilience testing and service virtualization. PactFlow is another freemium option for teams looking at a contract-testing platform.

Verdict

oasdiff is a strong choice for OpenAPI teams that want extensive change detection and a path from free CLI or pull-request checks to structured review controls. Its open-source core and flexible comparison routes are the main reasons to choose it. Look elsewhere if your contracts are GraphQL or AsyncAPI, or if five reviewers and five repositories are too restrictive and Enterprise's custom plan is not a fit.