---
title: Rule catalogue
description: Complete reference for all 45 Specdiff rules covering JSON Schema and OpenAPI breaking-change detection, including direction-dependent severity.
url: https://pr-1-ee19382a0710.thally.app/specdiff/rules
---

# Rule catalogue

Complete reference for all 45 Specdiff rules covering JSON Schema and OpenAPI breaking-change detection, including direction-dependent severity.

Specdiff ships 45 built-in rules. Twenty-four apply to JSON Schema documents (and
also fire inside OpenAPI schema objects). Twenty-one apply only to OpenAPI
structural elements such as endpoints, parameters, and responses.

Every change Specdiff reports carries one of three severity levels:

- **breaking** -- the change will break existing consumers.
- **warning** -- the change is worth reviewing but may not break consumers.
- **info** -- the change is informational and typically safe.

## JSON Schema rules

These rules fire when comparing standalone JSON Schema documents and when
comparing the schema objects embedded inside OpenAPI `requestBody`, `parameters`,
and `responses`.

| Code | Default severity | Description |
|---|---|---|
| `type-changed` | breaking | `type` changed, added, or removed (ignoring null) |
| `property-removed` | breaking | Property removed from `properties` or `patternProperties` |
| `property-added` | info | New optional property added |
| `required-property-added` | breaking | New property added that is also in `required` |
| `required-added` | breaking | Existing property added to `required` |
| `required-removed` | info | Property removed from `required` |
| `enum-value-removed` | breaking | Value removed from `enum` |
| `enum-value-added` | info | Value added to `enum` |
| `additional-properties-restricted` | breaking | `additionalProperties` became more restrictive |
| `additional-properties-relaxed` | info | `additionalProperties` became more permissive |
| `constraint-tightened` | breaking | Validation keyword made stricter (min raised, max lowered, pattern added/changed, etc.) |
| `constraint-relaxed` | info | Validation keyword made more permissive |
| `format-changed` | warning | `format` added, removed, or changed |
| `nullable-removed` | breaking | Null no longer accepted |
| `nullable-added` | info | Null now accepted |
| `default-changed` | warning | `default` added, removed, or changed |
| `description-changed` | info | `description` text changed |
| `composition-variant-removed` | breaking | Subschema removed from `oneOf`, `anyOf`, or `allOf` |
| `composition-variant-added` | info | Subschema added to `oneOf`, `anyOf`, or `allOf` |
| `items-changed` | breaking | `items` or `prefixItems` added, removed, or shape changed |
| `const-changed` | breaking | `const` value added, removed, or changed |
| `deprecated-added` | warning | `deprecated: true` added |
| `readonly-writeonly-changed` | warning | `readOnly` or `writeOnly` changed |
| `unresolved-ref` | warning | `$ref` could not be resolved |

## OpenAPI-only rules

These rules detect structural changes in OpenAPI 3.x documents outside of
individual schema objects.

| Code | Default severity | Description |
|---|---|---|
| `endpoint-removed` | breaking | Path removed from `paths` |
| `endpoint-added` | info | New path added |
| `operation-removed` | breaking | HTTP method removed from an existing path |
| `operation-added` | info | New HTTP method added |
| `operation-id-changed` | warning | `operationId` changed |
| `parameter-removed` | breaking | Parameter removed (matched by name and location) |
| `required-parameter-added` | breaking | New required parameter added |
| `optional-parameter-added` | info | New optional parameter added |
| `parameter-required-changed` | breaking | Parameter `required` flag changed (optional to required is breaking; required to optional is info) |
| `request-body-required-added` | breaking | Request body gained `required: true` |
| `request-body-media-type-removed` | breaking | Media type removed from `requestBody.content` |
| `request-body-media-type-added` | info | Media type added to `requestBody.content` |
| `response-removed` | breaking | Status code removed from responses |
| `response-added` | info | New status code documented |
| `response-media-type-removed` | breaking | Media type removed from response content |
| `response-media-type-added` | info | Media type added to response content |
| `security-requirement-added` | breaking | New security scheme required or anonymous access removed |
| `security-requirement-removed` | info | Security scheme removed |
| `server-removed` | warning | URL removed from top-level `servers` |
| `server-added` | info | URL added to `servers` |
| `deprecated-operation` | warning | Operation gained `deprecated: true` |

## Direction-dependent severity

Twelve rules change severity depending on whether the schema appears in a
**request** context (parameters, request body), a **response** context
(response bodies), or **neutral** (the default, used for standalone JSON Schema).

When comparing OpenAPI documents, Specdiff derives direction automatically:
schemas under parameters and request bodies use request direction, and schemas
under responses use response direction.

When comparing standalone JSON Schema documents, direction defaults to neutral.
You can override it with the `--direction` CLI flag or the `options.direction`
parameter in `diffJsonSchema`.

| Rule | request | response | neutral (default) |
|---|---|---|---|
| `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 |

Rules not listed in this table keep their default severity regardless of
direction.

## Getting remediation guidance

### CLI

Use `specdiff explain` followed by a rule code to see the rule title,
description, and remediation advice:

```bash
specdiff explain required-parameter-added
```

### Programmatic

Use `explainRule` from `@specdiff/core` to look up any rule by code. It returns
a `RuleInfo` object with `code`, `defaultSeverity`, `title`, `description`,
`remediation`, and `appliesTo` fields, or `undefined` for unknown codes.

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

const info = explainRule("required-parameter-added");
if (info) {
  console.log(info.title);
  console.log(info.remediation);
}
```

You can also retrieve the full catalogue as an array with `listRules()`:

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

for (const rule of listRules()) {
  console.log(`${rule.code} (${rule.defaultSeverity}): ${rule.title}`);
}
```