May 15, 2026 · 6 min read

OpenAPI Diffing Tools Compared: API Contract Guardian vs Spectral vs OAS Diff

A no-nonsense comparison of three tools that catch breaking API changes — when to use each, and why you might want all three in your pipeline.

Your API is a contract between your backend and every consumer — mobile apps, SPAs, third-party integrations, internal microservices. When that contract breaks silently, the result is a production incident that's hard to trace: a mobile client crashes on a renamed field, an integration partner sees 4xx errors for no obvious reason, a frontend renders empty data because an endpoint response shape changed.

Three tools have emerged as the leaders in preventing these incidents: Spectral (the most well-known API linter), OAS Diff (the dedicated diff engine), and API Contract Guardian (our CI-first entry). Each takes a fundamentally different approach. Here's how they compare and when you should use each.

At a Glance

Spectral: The API Style Linter

Spectral is the most widely adopted OpenAPI linting tool, and for good reason: its rule engine is powerful, extensible, and backed by Stoplight's ecosystem. You define rules in a declarative YAML format and Spectral checks your OpenAPI spec against them.

What Spectral Does Well

• Style enforcement — "Every endpoint must have a summary", "operationIds must be camelCase", "all responses must have examples". Spectral excels at consistency.
• Custom rule DSL — The spectral:extends and custom function support is the most mature rule system of any OpenAPI tool.
• Ecosystem — Pre-built rule sets for common standards (OWASP, RESTful API guidelines, Stoplight style guide).
• SARIF output — Integrates with GitHub Code Scanning, making violations visible in PR diffs.

Where Spectral Falls Short

• Not a diffing tool — Spectral validates a single spec file. It doesn't compare two versions of your API to find breaking changes. You can hack this with custom rules and two passes, but it's not the tool's purpose.
• Breaking change detection is bolted on — Community rules exist for detecting removed endpoints or renamed fields, but they're fragile and not comprehensive. Spectral won't catch a required field being added to an existing response, for example.
• Node.js dependency — If your stack is Python or Go, adding npm to your CI just for linting feels heavy.

Best for: Teams that need API style consistency across many services, with pre-built rule sets for REST best practices.

OAS Diff: The Schema Diff Specialist

OAS Diff (by the OpenAPI Technical Steering Committee) is specifically built for comparing two OpenAPI specs. It produces detailed diff reports showing what changed between versions: added endpoints, removed fields, modified schemas, and more.

What OAS Diff Does Well

• Comprehensive diffing — It catches everything: endpoint changes, schema additions and removals, parameter shifts, response body modifications.
• Multiple output formats — Markdown reports, HTML pages, and JSON machine-readable output make it flexible for both human review and CI integration.
• OpenAPI standards-aligned — It's maintained by the OAS community, so it tracks the spec closely.

Where OAS Diff Falls Short

• No migration guide — It tells you what changed but doesn't generate upgrade instructions or migration steps for API consumers.
• CI-first design is second-class — The CLI works, but there's no built-in concept of git branch comparison (you have to check out both files yourself and run the diff command).
• Exit codes are binary — It either found changes or it didn't. No way to say "breaking changes should fail CI, but additions should pass."
• npm-only install — Like Spectral, it assumes a Node.js environment.

Best for: Deep schema audits, release-to-release diff reports, and documentation-driven API reviews.

API Contract Guardian: The CI Pipeline Gate

API Contract Guardian is our entry — built from scratch with CI pipelines as the primary use case. It combines breaking change detection with severity-based gating, git branch awareness, and automatic migration guide generation.

What ACG Does Well

• Git-first design — The --base main --head feature-branch flags are designed for PR workflows. One command compares your feature branch spec against main, exits non-zero if blocking changes are detected.
• Severity-gated exit codes — Breaking changes fail the pipeline (exit 1). Non-breaking additions pass with a warning (exit 0). This lets you use ACG as a merge gate without blocking on non-critical changes.
• Auto-generated migration guides — When a breaking change is detected, ACG generates MIGRATION.md with the exact changes, affected consumers, and upgrade steps. This is unique — no other tool does it.
• Python-native — Install with pip, no npm dependency. Fits naturally into Python stacks and general CI runners.
• CI-optimized output — --output silent mode keeps CI logs clean. JSON mode for machine processing. Table mode for human review.

Where ACG Is Newer

• No custom rule DSL — You can configure severity per rule type, but there's no equivalent to Spectral's function-based rule system. For style enforcement, you'll still want Spectral.
• Smaller ecosystem — Being newer, there are fewer pre-built configs and community integrations. We're working on GitHub Action, GitLab CI template, and SARIF output.
• OpenAPI only (for now) — Unlike Spectral (which also handles AsyncAPI and JSON Schema), ACG is focused on OpenAPI 3.0 and 3.1.

Best for: CI pipeline gating on PRs, automated breaking change detection, and teams that want a migration guide with every API change.

When to Use Each (And When to Use All)

These tools aren't mutually exclusive — they solve different layers of the same problem:

In our own pipeline, we run Spectral for style → ACG for breaking changes → OAS Diff for release reports. Each tool fills a gap the others don't address.

Quick Comparison: Breaking Change Detection

Here's how the three tools handle a set of common API contract violations (tested against the same spec pair):

The Bottom Line

If you're already using Spectral for API linting (and you should be), adding API Contract Guardian to your PR pipeline isn't a replacement — it's a complementary layer. Spectral solves "does this spec follow our style?" ACG solves "would deploying this spec break a consumer?" They work best together.

OAS Diff is ideal for release-level changelog generation. Its detailed output is great for documentation but too verbose for per-PR gating.

Our recommendation: use Spectral + ACG on every PR, and OAS Diff on release. It takes 5 minutes to set up and catches the kind of API contract violations that cause production incidents — the ones tests alone don't catch.

Disclosure: API Contract Guardian is built by Revenue Holdings. Spectral and OAS Diff are independent open-source projects. This comparison is based on publicly available information and our own testing as of May 2026.