Skip to content
Skills Library
Programming · Review & audit

openapi-contract-diff

/openapi-contract-diff

Diffs two OpenAPI versions for breaking changes (removed endpoints, deleted schemas, narrowed enums, response shape changes) using `oasdiff breaking`, severity-classifies the findings (ERR / WARN / INFO), and gates CI with `--fail-on`. Use when reviewing an OpenAPI spec change in a PR or on a release tag.

Repository
qa ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Diffs two OpenAPI versions for breaking changes (removed endpoints, deleted schemas, narrowed enums, response shape changes) using `oasdiff breaking`, severity-classifies the findings (ERR / WARN / INFO), and gates CI with `--fail-on`. Use when reviewing an OpenAPI spec change in a PR or on a release tag.

Original author description

Diffs two OpenAPI versions for breaking changes (removed endpoints, deleted schemas, narrowed enums, response shape changes) using `oasdiff breaking`, severity-classifies the findings (ERR / WARN / INFO), and gates CI with `--fail-on`. Use when reviewing an OpenAPI spec change in a PR or on a release tag.

How it works

  1. Overview
  2. When to use
  3. Authoring (no authoring - the spec is the contract)
  4. Install
  5. Running
  6. What counts as breaking
  7. Reading the report
  8. CI integration
  9. References
Original SKILL.md headings · 227 lines, 885 words
SKILL.md preview
---
name: openapi-contract-diff
description: "Diffs two OpenAPI versions for breaking changes (removed endpoints, deleted schemas, narrowed enums, response shape changes) using `oasdiff breaking`, severity-classifies the findings (ERR / WARN / INFO), and gates CI with `--fail-on`. Use when reviewing an OpenAPI spec change in a PR or on a release tag."
---

# openapi-contract-diff

## Overview

`oasdiff` is the canonical CLI for comparing two OpenAPI specifications
and reporting **breaking changes** ([oasdiff-readme][readme]). It runs
over 250 checks against the diff and classifies each finding into one
of three severity tiers ([oasdiff-breaking][breaking]):

| Severity | Meaning                                                        |
|----------|----------------------------------------------------------------|
| `ERR`    | Definite breaking change - should be avoided.                 |
| `WARN`   | Potential breaking change - developers should be aware.        |
| `INFO`   | Non-breaking change.                                           |

[readme]: https://github.com/oasdiff/oasdiff
[breaking]: https://github.com/oasdiff/oasdiff/blob/main/docs/BREAKING-CHANGES.md

This is the schema-driven counterpart to
`pact-contract-testing`: use
oasdiff when **you don't control the consumers** (public APIs, third-
party integrations) and need to gate breaking-change shipment based on
the spec alone.

## When to use

- The repo defines an OpenAPI 3 spec (`openapi.yaml`, `openapi.json`,
  or split-file equivalent).
- The team wants a CI gate that fails the build on breaking spec
  changes between the PR and the deployed version.
- The API has external consumers (no Pact possible) or the team isn't
  ready to invest in consumer-driven contracts yet.
- You need a one-shot review tool for "is this PR going to break
  consumers?"

## Authoring (no authoring - the spec is the contract)

Unlike Pact, oasdiff doesn't add tests to the repo. Instead it consumes
two OpenAPI specs and emits a diff. Authoring effort goes into
**keeping the spec authoritative** - i.e. ensuring the OpenAPI file in
the repo accurately describes the implementation. Tools that close the
spec-vs-implementation gap (Schemathesis, Spectral lint) pair well with
this skill but are out of scope.

## Install

```bash
# Go install (preferred for native CLI)
go install github.com/oasdiff/oasdiff@latest

# Docker (CI-friendly, no Go toolchain required)
docker pull tufin/oasdiff
```

(Per [oasdiff-readme][readme].)

## Running

### Local diff

```bash
oasdiff breaking openapi-old.yaml openapi-new.yaml
```

(Per [oasdiff-breaking][breaking].)

By default oasdiff prints colorized text. For machine consumption, use
`--format`:

```bash
oasdiff breaking --format json openapi-old.yaml openapi-new.yaml > breaking.json
oasdiff breaking --format yaml openapi-old.yaml openapi-new.yaml
oasdiff breaking --format markdown openapi-old.yaml openapi-new.yaml
oasdiff breaking --format html openapi-old.yaml openapi-new.yaml > breaking.html
```

Available formats: text (default), JSON, YAML, markdown, HTML, plus
single-line ([oasdiff-breaking][breaking]).

### Comparing remote specs

The CLI accepts URLs directly:

```bash
oasdiff breaking \
  https://raw.githubusercontent.com/.../openapi-test1.yaml \
  https://raw.githubusercontent.com/.../openapi-test3.yaml
```

(Adapted from [oasdiff-readme][readme].)

### Docker variant

```bash
docker run --rm -t -v "$PWD:/specs" tufin/oasdiff breaking \
  /specs/openapi-old.yaml /specs/openapi-new.yaml
```

### `--fail-on` for CI gating

The exit code is the gate signal ([oasdiff-breaking][breaking]):

```bash
oasdiff breaking --fail-on ERR  ...   # exit 1 on ERR; default behavior most teams want
oasdiff breaking --fail-on WARN ...   # exit 1 on ERR or WARN; stricter
oasdiff breaking --fail-on INFO ...   # exit 1 on any reported change
```

Default for production gates: `--fail-on ERR`. Use `--fail-on WARN` for
stricter projects (financial APIs, public SDKs) where even potentially-
breaking changes need explicit acceptance.

## What counts as breaking

oasdiff ships 250+ checks. The headline breaking patterns
([oasdiff-breaking][breaking]):

- **Endpoint deletion** - removing a path or HTTP method.
- **Removed success response** - e.g. dropping the 200 from a `responses` block.
- **Deleted schemas from `components.schemas`** - even if no longer referenced.
- **Enum value removal** - removing a value from an `enum` array.
  Mark the enum `x-extensible-enum: true` to treat removals as
  non-breaking (clients should ignore unknown values).
- **Response shape narrowing** - changing a property type from `string`
  to `integer`, removing a `required` array entry, etc.
- **Request shape widening into `required`** - making a previously-
  optional request field required.

For the full list, run `oasdiff checks` to dump the active rule set.

## Reading the report

Text output (default) example:

```
1 changes: 1 error, 0 warning, 0 info
error	[response-success-status-removed] at openapi-new.yaml
	in API GET /pets
	the success response status '200' was removed
```

JSON output (for downstream parsing):

```json
[
  {
    "id": "response-success-status-removed",
    "level": 3,
    "operation": "GET",
    "operationId": "listPets",
    "path": "/pets",
    "source": "openapi-new.yaml",
    "section": "paths",
    "text": "the success response status '200' was removed"
  }
]
```

`level: 3` is `ERR`, `2` is `WARN`, `1` is `INFO` per the standard
oasdiff convention. Pipe to `jq` for triage:

```bash
jq -r '.[] | select(.level==3) | "ERR " + .operation + " " + .path + " :: " + .text' breaking.json
```

## CI integration

GitHub Actions example using the Docker image and the `--fail-on ERR`
default:

```yaml
# .github/workflows/openapi-diff.yml
name: openapi-diff

on:
  pull_request:

jobs:
  oasdiff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # need merge-base SHA for `git show <base>:openapi.yaml`

      - name: Extract base spec
        run: |
          BASE_SHA=$(git merge-base origin/main HEAD)
          git show $BASE_SHA:openapi.yaml > /tmp/openapi-base.yaml

      - name: Run oasdiff
        run: |
          docker run --rm -v "$PWD:/specs" -v /tmp:/tmp tufin/oasdiff breaking \
            --fail-on ERR \
            --format text \
            /tmp/openapi-base.yaml \
            /specs/openapi.yaml | tee oasdiff-report.txt

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: openapi-breaking-report
          path: oasdiff-report.txt
          retention-days: 14
```

`fetch-depth: 0` is required so the merge-base of the PR resolves; the
shallow clone GitHub uses by default doesn't include the merge-base
commit.

For a PR comment workflow, generate `--format markdown` and post via
`actions/github-script@v7` - the markdown table format includes a
clickable per-finding rationale.

## References

- [oasdiff-readme][readme] - install (Go + Docker), output formats, key
  flags.
- [oasdiff-breaking][breaking] - `breaking` subcommand, severity tiers,
  `--fail-on` semantics, breaking-change categories.
- `pact-contract-testing` - the
  consumer-driven counterpart for cases where you control consumers.
- `contract-compatibility-gate` - the gate skill that aggregates oasdiff output with Pact and
  Protobuf verdicts.
Files in this package (12)
  • SKILL.md 7 KB
  • .tessl-plugin/plugin.json 1 KB
  • evals/clean-diff-on-a-route-that-was-never-documented/criteria.json 5 KB
  • evals/clean-diff-on-a-route-that-was-never-documented/task.md 12 KB
  • evals/every-additive-change-fails-the-build/criteria.json 5 KB
  • evals/every-additive-change-fails-the-build/task.md 11 KB
  • evals/friday-spec-pr-the-api-team-calls-cosmetic/criteria.json 5 KB
  • evals/friday-spec-pr-the-api-team-calls-cosmetic/task.md 8 KB
  • evals/partner-integration-broke-while-the-check-stayed-green/criteria.json 5 KB
  • evals/partner-integration-broke-while-the-check-stayed-green/task.md 10 KB
  • evals/release-gate-printed-go-on-a-removed-200/criteria.json 5 KB
  • evals/release-gate-printed-go-on-a-removed-200/task.md 9 KB

Versions

The database has no other skills named openapi-contract-diff.

Database snapshot: 13.11.2026 · package version 26ad23dfe316 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100openapi-breaking-change-report
    Compares two versions of an OpenAPI 3.x spec and reports breaking, risky and safe changes for API consumers, with a semver bump suggestion and migration notes. Use when asked to diff OpenAPI or Swagger specs, check for breaking changes, review an API PR, compare openapi.yaml files, or run oasdiff.
  • 100api-changelog
    Drafts API changelog entries from two versions of an OpenAPI spec. Use when asked to write release notes or a changelog for API changes, compare two OpenAPI files, or find breaking changes between spec versions. Runs oasdiff for the facts, then writes the entries in plain…
  • 95openapi-hub
    OpenAPI spec versioning, breaking change detection, and SDK publishing. Tracks spec versions, blocks PRs that introduce breaking API changes without a major version bump, and auto-publishes updated docs. Use when managing a public API, releasing a new API version, or detecting…
  • 100api-diff
    Compare two OpenAPI 3.x specifications and detect breaking changes before a release, version bump, or SDK regeneration. Reports deleted endpoints, newly required or tightened parameters, type and enum changes, removed response fields/status codes/content types, new auth…
  • 100api-design-reviewer
    Review REST API designs for quality, consistency, and breaking changes. Lints OpenAPI specs, generates scorecards, and detects breaking changes between versions. Use when designing APIs, reviewing contracts, or managing API versioning.
  • 100apirev-contract
    Keeps an API and its spec honest. `validate` checks a new HAR's responses against the spec (missing required fields, type changes, undocumented fields, unknown endpoints, status codes not in the spec); `diff` compares two specs and sorts changes into breaking, warning and info,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.