---
title: Specdiff Overview
description: Breaking-change detection for JSON Schema and OpenAPI documents.
url: https://pr-1-7cfcfe393d12.thally.app/specdiff-overview
---

# Specdiff Overview

Breaking-change detection for JSON Schema and OpenAPI documents.

Specdiff compares a before and after version of a JSON Schema or OpenAPI
document and classifies every change as `breaking`, `warning`, or `info`. Each
reported change includes a JSON-pointer path, a stable rule code, and a
human-readable message.

## Key capabilities

- **45 built-in rules** covering JSON Schema and OpenAPI 3.0/3.1 constructs.
- **Direction-aware severity** — 12 rules adjust their severity depending on
  whether a schema describes a request, a response, or is direction-neutral.
- **Three output formats**: plain text, Markdown (GFM), and JSON.
- **Local `$ref` resolution** only. Remote references produce an `unresolved-ref`
  warning. Bundle remote refs into your document before diffing.

## Packages

| Package | Purpose |
| --- | --- |
| `@specdiff/core` | Library API — diff, format, inspect rules |
| `@specdiff/cli` | Command-line binary (`specdiff`) |
| `@specdiff/mcp` | MCP server for coding agents (`specdiff-mcp`) |

## Requirements

- **Node.js 22** or later
- **ESM only** — all three packages use ECMAScript modules
- TypeScript declarations included in every package
- MIT license, copyright 2026 Seamline

## Installation

```bash
# Core library
npm install @specdiff/core

# CLI (as a dev dependency)
npm install -D @specdiff/cli

# MCP server
npm install @specdiff/mcp
```

## Quick usage

### Library

```ts
import { diffOpenApi, formatText } from "@specdiff/core";

const result = diffOpenApi(beforeDocument, afterDocument);
console.log(formatText(result));

if (result.maxSeverity === "breaking") {
  process.exit(1);
}
```

### CLI

```bash
# Compare two files (default threshold is breaking)
specdiff before.yaml after.yaml

# JSON output, fail on any warning or above
specdiff before.json after.json --format json --fail-on warning

# List all rules
specdiff rules

# Explain a single rule
specdiff explain property-removed
```

### MCP server

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

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

The server exposes four tools over stdio: `specdiff_compare`,
`specdiff_explain_rule`, `specdiff_list_rules`, and `specdiff_format`.

## Supported specifications

- **OpenAPI 3.0** (including `nullable`) and **3.1** (including `type` arrays
  with `"null"`)
- **JSON Schema** draft-04 through 2020-12 — structural keyword comparison,
  no meta-schema validation

## Further reading

- [@specdiff/core API](/specdiff-core-api) — complete library reference
- [@specdiff/cli Reference](/specdiff-cli) — command-line flags, exit codes,
  and programmatic embedding
- [@specdiff/mcp Server](/specdiff-mcp-server) — MCP tool descriptions and
  server setup
- [Rules Reference](/specdiff-rules) — all 45 rules with direction-aware
  severity details