---
title: Specdiff Overview
description: Detect breaking changes in JSON Schema and OpenAPI documents
url: https://pr-1-8289d63b6330.thally.app/specdiff/overview
---

# Specdiff Overview

Detect breaking changes in JSON Schema and OpenAPI documents

Specdiff is a breaking-change detection tool for JSON Schema and OpenAPI specifications. It analyzes differences between document versions and categorizes them by severity, helping teams identify what impacts consumers of their APIs.

## What does Specdiff do?

Specdiff compares two versions of a JSON Schema or OpenAPI 3.x document and reports all changes. Each change is:

- **Classified by severity**: breaking, warning, or info
- **Assigned a rule code**: one of 45 built-in rules that describe the type of change
- **Located precisely**: with an RFC 6901 JSON pointer to the changed element
- **Direction-aware** (for JSON Schema): the same constraint change can be breaking in one direction (request) and safe in another (response)

This helps API teams understand compatibility, automate CI checks, and document changes systematically.

## Three packages

Specdiff is distributed as a monorepo with complementary packages:

### @specdiff/core

The core library with all comparison logic, rule catalogue, and formatters. No dependencies.

```bash
npm install @specdiff/core
```

Use this for programmatic access to diffing and rule metadata.

### @specdiff/cli

The `specdiff` command-line tool for CI pipelines and ad-hoc comparison. Depends on `yaml` for YAML parsing.

```bash
npm install -D @specdiff/cli
npx specdiff --help
```

Useful for GitHub Actions, GitLab CI, local development, and build scripts.

### @specdiff/mcp

A Model Context Protocol (MCP) server for use with Claude and other AI assistants. Runs as a stdio subprocess.

Add to `.mcp.json` or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "specdiff": {
      "command": "npx",
      "args": ["-y", "@specdiff/mcp"]
    }
  }
}
```

Once configured, Claude can compare API specs directly in conversation.

## Key features

- **45 built-in rules**: Each rule detects a specific type of change (required field added, type changed, endpoint removed, etc.)
- **Direction-aware severity**: JSON Schema rules understand whether they're applied to request or response schemas; the same change can have different severity in each direction
- **Multiple output formats**: Text, Markdown (for GitHub summaries), and JSON (for tooling)
- **$ref resolution**: Follows local references (`#/...`) to compare composed schemas; reports unresolved refs as warnings
- **CI-ready exit codes**: Exit 1 when changes exceed your threshold (breaking, warning, info, or none), facilitating automation
- **Fine-grained control**: Ignore specific rules, paths, or sets of rules per-diff

## Compatibility

- **JSON Schema**: Drafts 04 through 2020-12. Understands `definitions` and `$defs`, keyword-based comparison (no meta-schema validation), `nullable` from OpenAPI 3.0, and boolean/numeric `exclusiveMinimum`/`exclusiveMaximum`
- **OpenAPI**: 3.x only (not 2.0/Swagger). Normalizes path templates, matches parameters by `(in, name)` pair, and derives direction from operation semantics
- **Refs**: Only local fragment references (`#/...`) are followed; remote and missing refs produce warnings and are skipped
- **Node.js**: Requires Node >=22, ESM only

## Next steps

- **Using the library**: See [Core API Reference](core-api) for all exports, types, and code examples
- **Comparing documents**: See [CLI Reference](cli) for command-line usage
- **Understanding rules**: See [Rules](rules) for all 45 rule codes and when they apply
- **MCP integration**: See [MCP Server](mcp) for Claude integration
- **CI pipelines**: See [CI Integration](ci-integration) for automated breaking-change detection