oasdiff vs Optic

What each tool is

oasdiff

An open-source Go CLI (Apache-2.0) with commands such as breaking, changelog, diff and validate. It ranks each change ERR (breaking), WARN (possibly breaking) or INFO, and --fail-on ERR makes it exit with code 1, which is how a CI job fails on a breaking change. You can change the severity of any check, or ignore a known change, with a config file. The GitHub Action adds annotations to the pull request and a side-by-side review link. oasdiff Pro adds approve or reject for each change from the PR comment, an audit trail, and a gate that blocks merging until every change is approved.

Optic

An MIT-licensed npm CLI (@useoptic/optic) for OpenAPI linting, diffing and testing. optic diff openapi.yml --base main compares the spec on your branch with the one on main, and --web opens the result as an HTML report. Built-in rulesets cover breaking changes, consistent naming and required descriptions, and it can run Spectral rules. optic capture sends your test traffic through a local proxy, checks each request and response against the spec, and --update patches the differences into the file. The repository was archived by its owner on January 12, 2026, and is read-only. Its README says Optic Labs is now part of Atlassian.

At a glance

oasdiff and Optic facts as of 2026-11-09, from their GitHub repositories, documentation and oasdiff.com/pricing. “Not listed” means we did not find it on their pages; it does not mean it does not exist.

oasdiff or Optic?

• oasdiff if you are setting up a breaking-change check now: it is maintained, can fail CI with --fail-on, and lets you tune the severity of each check.
• Optic if it already runs in your pipeline and you can own an archived MIT codebase, or you rely on optic capture or its lint rulesets.

Where Graphwake fits

oasdiff and Optic both tell the person who changed the spec what changed. Neither one’s pages describe telling the teams that call the endpoint, and the author of a pull request rarely knows who those teams are. Graphwake is the third option for that job. It finds the breaking changes in your OpenAPI spec, keeps a list of consumer teams (each team subscribes to the endpoints it calls), and sends each breaking change only to those teams, in Slack, Microsoft Teams or email. If the spec came through CI, the alert goes out while the change is still a pull request.

• Alerts to subscribed teams

  Only the teams subscribed to an endpoint hear about its breaking changes, in Slack, Microsoft Teams or email.

• Impact score before the merge

  Each change set gets a 0-100 score with public rules: breaking changes, affected teams, people to notify, blind spots.

• Ownership map

  Owners and orphan endpoints, with a weekly ownership report.

• Hosted: nothing to run

  A published spec URL checked every 30 minutes, or one CI step that never fails or blocks a build.

Moving from Optic to oasdiff

If the job you need is the breaking-change check, the move is small, because both tools read the same OpenAPI files. The jobs oasdiff does not do need their own answer.

1. Keep your spec files

   oasdiff reads the same OpenAPI files Optic did. Nothing in the spec changes.

2. Swap the CI step

   Replace optic diff openapi.yml --base main with the oasdiff GitHub Action below. It compares the spec on the pull-request branch with the base branch. Use fail-on: ERR to fail only on definite breaking changes, or leave fail-on out to report without failing. fail-on: WARN also fails on possibly-breaking changes.

3. Move the style rules

   oasdiff checks breaking changes, not style. If you used Optic’s naming or description rules, run a linter such as Spectral next to it.

4. Decide what replaces capture

   If you used optic capture to keep the spec in step with traffic, oasdiff has no equivalent. Keep Optic for that one job, or generate the spec from your code.

name: oasdiff
on:
  pull_request:
    branches: [ "main" ]
permissions:
  contents: read
  pull-requests: write   # lets the action post the review link as a PR comment
jobs:
  breaking-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: git fetch --depth=1 origin ${{ github.base_ref }}
      - uses: oasdiff/oasdiff-action/breaking@v0
        with:
          base: 'origin/${{ github.base_ref }}:openapi.yaml'
          revision: 'HEAD:openapi.yaml'
          fail-on: WARN
          github-token: ${{ github.token }}

Using oasdiff and Graphwake together

Keep the oasdiff Action in the pull request so the author sees the diff, and add the Graphwake CI step or point Graphwake at your published spec URL, which it checks every 30 minutes. The author gets the diff; the consumer teams get the alert. More on why those are different jobs in API breaking change alerts.

Questions

Sources and last verified

• github.com/oasdiff/oasdiff
• github.com/oasdiff/oasdiff/blob/main/docs/BREAKING-CHANGES.md
• github.com/oasdiff/oasdiff-action
• oasdiff.com/pricing
• github.com/opticdev/optic
• github.com/opticdev/optic/wiki/Diff-and-Lint-OpenAPI
• github.com/opticdev/optic/wiki/Using-Optic-Capture-with-Integration-Tests
• npmjs.com/package/@useoptic/optic
• atlassian.com/blog/company-news/optic-acquisition
• github.com/stoplightio/spectral

Competitor facts were checked on 2026-11-09; check their pages for the latest.

Related

• CompareCompare API breaking change tools
• Compareoasdiff vs Graphwake
• AlternativesLooking for an Optic alternative?
• Alternativesoasdiff alternatives for API breaking changes
• GuideThe oasdiff GitHub Action, step by step
• GuideAPI breaking change alerts: how to tell the right teams