---
title: Rules catalogue
description: All 45 Specdiff rules — the stable codes, default severities, and what each rule detects.
url: https://pr-1-7abef52380a8.thally.app/specdiff-rules
---

# Rules catalogue

All 45 Specdiff rules — the stable codes, default severities, and what each rule detects.

Every change Specdiff reports carries one of the codes below. Run
`specdiff rules` or call `listRules()` for the same table at runtime, and
`specdiff explain <code>` / `explainRule(code)` for remediation advice.

"Default severity" is what the rule reports when no
[direction rule](/specdiff-overview#request-and-response-direction) or user
override applies. "Applies to" says whether the rule fires for JSON Schema
documents, OpenAPI documents, or both (JSON Schema rules also fire inside
OpenAPI parameter, request-body, and response schemas).

## JSON Schema rules

These rules fire for both standalone JSON Schema documents and schemas embedded
in OpenAPI documents.

| Code | Default | Description |
| --- | --- | --- |
| `type-changed` | breaking | The `type` of a schema changed, was added, or was removed (ignoring `null`, which is covered by the nullable rules). |
| `property-removed` | breaking | A property under `properties` or `patternProperties` no longer exists. |
| `property-added` | info | A new optional property was added under `properties`. |
| `required-property-added` | breaking | A new property was added and is listed in `required`. |
| `required-added` | breaking | A property that already existed was added to `required`. |
| `required-removed` | info | A property was removed from `required`. |
| `enum-value-removed` | breaking | A value was removed from an `enum`. |
| `enum-value-added` | info | A value was added to an `enum`. |
| `additional-properties-restricted` | breaking | `additionalProperties` went from open (`true` or absent) to `false` or to a schema, or from a schema to `false`. |
| `additional-properties-relaxed` | info | `additionalProperties` became more permissive. |
| `constraint-tightened` | breaking | A validation keyword became stricter: `minimum`/`minLength`/`minItems`/`minProperties` raised, `maximum`/`maxLength`/`maxItems`/`maxProperties` lowered, `pattern` added or changed, `multipleOf` changed, `uniqueItems` enabled, or an `enum` introduced where none existed. |
| `constraint-relaxed` | info | A validation keyword became more permissive. |
| `format-changed` | warning | The `format` annotation was added, removed, or changed. |
| `nullable-removed` | breaking | `null` was removed from the accepted types. |
| `nullable-added` | info | `null` became an accepted value. |
| `default-changed` | warning | The `default` value was added, removed, or changed. |
| `description-changed` | info | The `description` text changed. Purely informational. |
| `composition-variant-removed` | breaking | A subschema was removed from `oneOf`, `anyOf`, or `allOf`. |
| `composition-variant-added` | info | A subschema was added to `oneOf`, `anyOf`, or `allOf`. |
| `items-changed` | breaking | `items` or `prefixItems` was added, removed, or structurally changed. When both sides are schemas, Specdiff recurses into them and reports specific rules under the `items` path instead. |
| `const-changed` | breaking | The `const` value was added, removed, or changed. |
| `deprecated-added` | warning | `deprecated: true` was added to a schema or parameter. |
| `readonly-writeonly-changed` | warning | `readOnly` or `writeOnly` changed. |
| `unresolved-ref` | warning | A `$ref` could not be resolved. Only local references are followed; remote and missing references are skipped. |

## OpenAPI rules

These rules apply only to OpenAPI documents.

| Code | Default | Description |
| --- | --- | --- |
| `endpoint-removed` | breaking | A path under `paths` no longer exists. |
| `endpoint-added` | info | A new path was added. |
| `operation-removed` | breaking | An HTTP method was removed from a path. |
| `operation-added` | info | A new HTTP method was added. |
| `operation-id-changed` | warning | `operationId` changed. Generated SDKs use it for method names. |
| `parameter-removed` | breaking | A parameter (matched by `name` and `in`) was removed. |
| `required-parameter-added` | breaking | A new parameter with `required: true` was added. |
| `optional-parameter-added` | info | A new optional parameter was added. |
| `parameter-required-changed` | breaking | A parameter's `required` flag changed. Optional to required is breaking; required to optional is info. |
| `request-body-required-added` | breaking | The request body gained `required: true`. |
| `request-body-media-type-removed` | breaking | A media type was removed from `requestBody.content`. |
| `request-body-media-type-added` | info | A media type was added to `requestBody.content`. |
| `response-removed` | breaking | A status code or `default` was removed from `responses`. |
| `response-added` | info | A new status code was documented. |
| `response-media-type-removed` | breaking | A media type was removed from a response's `content`. |
| `response-media-type-added` | info | A media type was added to a response's `content`. |
| `security-requirement-added` | breaking | An operation now requires a security scheme it did not before, or anonymous access was removed. |
| `security-requirement-removed` | info | A security scheme is no longer listed for an operation. |
| `server-removed` | warning | A URL was removed from the top-level `servers` list. |
| `server-added` | info | A URL was added to the `servers` list. |
| `deprecated-operation` | warning | An operation gained `deprecated: true`. |

## Tuning rules

### Ignore a rule entirely

Pass `ignoreRules` in `DiffOptions` or `--ignore-rule` on the CLI:

```ts
const result = diffOpenApi(before, after, {
  ignoreRules: ["description-changed"],
});
```

```bash
npx specdiff before.yaml after.yaml --ignore-rule description-changed
```

### Override a rule's severity

Pass `overrides` in `DiffOptions`:

```ts
const result = diffOpenApi(before, after, {
  overrides: { "default-changed": "breaking" },
});
```

Overrides are applied after the direction table and always win.

### Ignore paths

Drop all changes under a JSON-pointer prefix:

```ts
const result = diffOpenApi(before, after, {
  ignorePaths: ["#/paths/~1internal"],
});
```

```bash
npx specdiff before.yaml after.yaml --ignore-path "#/paths/~1internal"
```

The leading `#` is optional.