---
title: Specdiff Overview
description: Detect breaking changes between two versions of a JSON Schema or OpenAPI document with Specdiff.
url: https://pr-1-ff84656b4b8a.thally.app/specdiff/overview
---

# Specdiff Overview

Detect breaking changes between two versions of a JSON Schema or OpenAPI document with Specdiff.

Specdiff detects breaking changes between two versions of a JSON Schema or OpenAPI document. It compares the before and after documents structurally, reports every difference it finds, and classifies each one by severity so you can decide whether a release is safe.

Specdiff is part of the Seamline toolkit.

## Packages

Specdiff ships as three packages. All are version 0.1.0, MIT-licensed, ESM-only, and require Node.js 22 or later.

| Package | Purpose | Runtime dependencies |
|---|---|---|
| `@specdiff/core` | Zero-dependency library for diffing, formatting, and rule lookup | None |
| `@specdiff/cli` | Command-line tool that wraps the core library | `@specdiff/core`, `yaml` |
| `@specdiff/mcp` | Model Context Protocol server exposing Specdiff as MCP tools | `@specdiff/core`, `yaml`, `@modelcontextprotocol/sdk`, `zod` |

## Key concepts

### Severity levels

Every detected change is assigned one of three severity levels:

- **breaking** -- A change that will break existing consumers of the API or schema.
- **warning** -- A change that might cause problems and deserves attention.
- **info** -- A non-breaking change reported for awareness.

### Direction awareness

Some changes are only breaking in one direction. Adding a required property to a request body is breaking for callers, but adding a required property to a response body is merely informational for consumers.

Specdiff tracks three directions:

- **request** -- The schema describes data sent by the client.
- **response** -- The schema describes data returned by the server.
- **neutral** -- No direction context; the default for standalone JSON Schema comparisons.

Twelve of the 45 built-in rules have direction-dependent severities. When comparing OpenAPI documents, Specdiff derives the direction automatically from each schema's position (request body schemas use request direction, response schemas use response direction). For standalone JSON Schema comparisons you can set the direction explicitly.

### Document kind detection

Specdiff supports two document kinds:

- **openapi** -- OpenAPI 3.0 and 3.1 documents.
- **json-schema** -- JSON Schema documents from draft-04 through 2020-12.

By default, Specdiff auto-detects the kind: if either document has a string `openapi` key at the top level, both are treated as OpenAPI; otherwise they are treated as JSON Schema.

## Built-in rules

Specdiff includes 45 built-in rules:

- **24 JSON Schema rules** that apply to both standalone schemas and schemas inside OpenAPI documents. These cover type changes, property additions and removals, enum mutations, constraint tightening and relaxing, composition variants, and more.
- **21 OpenAPI-only rules** that cover endpoints, operations, parameters, request bodies, responses, security requirements, and servers.

See the [Rules reference](/specdiff/rules) for the complete catalogue.

## Supported formats

- JSON Schema draft-04, draft-06, draft-07, 2019-09, and 2020-12 (structural comparison, no meta-schema validation).
- OpenAPI 3.0 and 3.1.
- Both `definitions` and `$defs` are understood.
- OpenAPI 3.0 `nullable: true` and OpenAPI 3.1 `"null"` in a type array are handled equivalently.
- Only local `$ref` resolution (`#/...`). Remote or missing refs produce an `unresolved-ref` warning.

## Installation

```sh
# Library (zero dependencies)
npm install @specdiff/core

# CLI (typically as a dev dependency for CI and scripts)
npm install -D @specdiff/cli

# MCP server (typically via npx)
npx -y @specdiff/mcp
```

## Requirements

- Node.js >= 22
- ESM only (no CommonJS export)

## Next steps

#### [CLI reference](/specdiff/cli)

    Run comparisons from the command line with the specdiff command.

#### [Core API](/specdiff/core-api)

    Use the library directly in your TypeScript or JavaScript code.

#### [Rules reference](/specdiff/rules)

    Browse every built-in rule with its default severity and description.

#### [CI integration](/specdiff/ci-integration)

    Block merges on breaking changes in your CI pipeline.

#### [MCP server](/specdiff/mcp)

    Expose Specdiff to AI tools via the Model Context Protocol.