---
title: Rule Catalogue
description: The 45 built-in rules in Specdiff detect breaking changes, warnings, and informational changes in JSON Schema and OpenAPI documents.
url: https://pr-1-8289d63b6330.thally.app/specdiff/rules
---

# Rule Catalogue

The 45 built-in rules in Specdiff detect breaking changes, warnings, and informational changes in JSON Schema and OpenAPI documents.

Specdiff classifies every change it detects with a **rule code**, which determines its default **severity** and explains what changed. You can customize severity levels, ignore specific rules, or ignore changes in specific paths.

## How the rule system works

When comparing two documents, Specdiff generates a list of changes. Each change has:

- **Rule code** (e.g., `required-added`, `parameter-removed`) — identifies what changed
- **Default severity** — `breaking`, `warning`, or `info`
- **Path** — RFC 6901 JSON pointer to the location of the change
- **Message** — human-readable description
- **Before/after values** — the old and new values (if applicable)

The **default severity** is based on the rule itself and, for some rules, the document's direction (request vs. response context). You can override severity levels using `DiffOptions.overrides` to tune Specdiff's behavior for your API.

## JSON Schema rules

These 24 rules apply when comparing JSON Schema documents or schemas nested within OpenAPI documents.

| Rule code | Default severity |
| --- | --- |
| `type-changed` | breaking |
| `property-removed` | breaking |
| `property-added` | info |
| `required-property-added` | breaking |
| `required-added` | breaking |
| `required-removed` | info |
| `enum-value-removed` | breaking |
| `enum-value-added` | info |
| `additional-properties-restricted` | breaking |
| `additional-properties-relaxed` | info |
| `constraint-tightened` | breaking |
| `constraint-relaxed` | info |
| `format-changed` | warning |
| `nullable-removed` | breaking |
| `nullable-added` | info |
| `default-changed` | warning |
| `description-changed` | info |
| `composition-variant-removed` | breaking |
| `composition-variant-added` | info |
| `items-changed` | breaking |
| `const-changed` | breaking |
| `deprecated-added` | warning |
| `readonly-writeonly-changed` | warning |
| `unresolved-ref` | warning |

## OpenAPI rules

These 21 rules apply only when comparing OpenAPI documents. They cover endpoints, operations, parameters, request bodies, responses, and security requirements.

| Rule code | Default severity |
| --- | --- |
| `endpoint-removed` | breaking |
| `endpoint-added` | info |
| `operation-removed` | breaking |
| `operation-added` | info |
| `operation-id-changed` | warning |
| `parameter-removed` | breaking |
| `required-parameter-added` | breaking |
| `optional-parameter-added` | info |
| `parameter-required-changed` | breaking |
| `request-body-required-added` | breaking |
| `request-body-media-type-removed` | breaking |
| `request-body-media-type-added` | info |
| `response-removed` | breaking |
| `response-added` | info |
| `response-media-type-removed` | breaking |
| `response-media-type-added` | info |
| `security-requirement-added` | breaking |
| `security-requirement-removed` | info |
| `server-removed` | warning |
| `server-added` | info |
| `deprecated-operation` | warning |

## Direction-aware severity

When comparing JSON Schema documents, you can specify a **direction** to model how breaking changes depend on context:

- **`request`** — incoming data from a client (the schema validates what you accept)
- **`response`** — outgoing data to a client (the schema validates what you return)
- **`neutral`** — no context (default; symmetric view)

For example, adding a required field is breaking in a **request** context (clients must provide it) but only informational in a **response** context (you can return it to older clients). Specdiff adjusts severity for 12 rules based on direction.

### Direction severity table

These 12 rules change severity depending on the direction:

| Rule | Request | Response | Neutral |
| --- | --- | --- | --- |
| `required-added` | breaking | info | breaking |
| `required-property-added` | breaking | info | breaking |
| `required-removed` | info | breaking | info |
| `enum-value-added` | info | warning | info |
| `enum-value-removed` | breaking | info | breaking |
| `constraint-tightened` | breaking | info | breaking |
| `constraint-relaxed` | info | warning | info |
| `additional-properties-restricted` | breaking | info | breaking |
| `nullable-added` | info | breaking | info |
| `nullable-removed` | breaking | info | breaking |
| `composition-variant-added` | info | warning | info |
| `composition-variant-removed` | breaking | info | breaking |

All other rules maintain their default severity in every direction.

## Customizing rules

The `DiffOptions` interface gives you fine-grained control over which changes are reported and their severity:

```ts
interface DiffOptions {
  ignoreRules?: RuleCode[];                              // Drop changes from these rules
  overrides?: Partial<Record<RuleCode, Severity>>;      // Override severity for specific rules
  ignorePaths?: string[];                                // Drop changes at/beneath these JSON pointers
  direction?: Direction;                                 // "request", "response", or "neutral" (JSON Schema only)
}
```

- **`ignoreRules`** — completely suppress changes from specified rules
- **`overrides`** — change severity for specific rules (e.g., treat `description-changed` as breaking)
- **`ignorePaths`** — ignore changes in specific branches of the document (e.g., `#/paths/~1internal` to ignore the `/internal` path)
- **`direction`** — affects severity for direction-aware rules (OpenAPI ignores this; it derives direction from the operation context)

### Example: customizing rules and severity

```ts
import { diffDocuments } from "@specdiff/core";

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

This configuration:
- Ignores all `description-changed` changes
- Treats `default-changed` as breaking (instead of warning)
- Applies direction-aware severity adjustments (if comparing JSON Schema in request/response mode)