---
title: Specdiff Overview
description: Breaking-change detection for JSON Schema and OpenAPI 3.x. Compare API specifications and classify every change as breaking, warning, or info.
url: https://pr-1-b9e16090e83d.thally.app/specdiff/overview
---

# Specdiff Overview

Breaking-change detection for JSON Schema and OpenAPI 3.x. Compare API specifications and classify every change as breaking, warning, or info.

Specdiff compares a "before" and "after" JSON Schema or OpenAPI 3.x document and
classifies every change as `breaking`, `warning`, or `info`. It produces
deterministic output with RFC 6901 JSON-pointer paths, stable rule codes from a
45-rule catalogue, and human-readable messages. Direction-aware diffing means
request-side and response-side schemas receive appropriate severities
automatically.

Specdiff ships as three packages that share version 0.1.0.

## Packages

| Package | What it provides |
|---|---|
| `@specdiff/core` | Zero-dependency diffing engine, formatters, rule catalogue, and pointer helpers. Use this as a library in your own tools. |
| `@specdiff/cli` | The `specdiff` command-line binary. Reads JSON and YAML files, supports multiple output formats, and returns structured exit codes for CI. |
| `@specdiff/mcp` | An MCP server (`specdiff-mcp`) that exposes four tools for AI assistants: compare documents, explain rules, list rules, and format results. |

## Requirements

- **Node.js 22** or later
- **ESM only** -- all three packages use ES modules exclusively

## Installation

### Core library

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

### CLI

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

After installation, run with `npx`:

```bash
npx specdiff --help
```

### MCP server

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

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

## Basic usage

The core library exposes `diffDocuments` for auto-detecting the document kind
and `formatText` for human-readable output.

```ts
import { readFileSync } from "node:fs";
import { diffDocuments, formatText, exceedsThreshold } from "@specdiff/core";

const before = JSON.parse(readFileSync("openapi-v1.json", "utf8"));
const after = JSON.parse(readFileSync("openapi-v2.json", "utf8"));

const result = diffDocuments(before, after, {
  ignoreRules: ["description-changed"],
  overrides: { "default-changed": "breaking" },
});

console.log(formatText(result));

if (exceedsThreshold(result, "breaking")) {
  process.exit(1);
}
```

`diffDocuments` returns a `DiffResult` containing an array of `SchemaChange`
objects sorted by severity, path, and rule code, plus a summary with counts and
the highest severity found.

## Next steps

- [Core library API reference](/specdiff/core-api) -- every type, function, and constant exported by `@specdiff/core`
- [CLI reference](/specdiff/cli) -- commands, flags, exit codes, and CI recipes for `@specdiff/cli`
- [MCP server reference](/specdiff/mcp) -- tool definitions and programmatic setup for `@specdiff/mcp`
- [Rules reference](/specdiff/rules) -- the full 45-rule catalogue with severity, direction, and remediation details