My OpenAPI differ flagged a breaking change that broke nobody — the enum shrank on the response side

Description and use

The OpenAPI diff tool now considers schema direction: shrinking an enum in a response is non‑breaking, while in a request it is breaking. Spec normalization prevents false diffs.

Problem

A naive OpenAPI diff tool flagged a breaking change when an enum shrank in a response schema, but the change did not affect clients.

Outcome

The updated tool correctly identifies breaking changes based on schema direction and avoids false positives caused by spec ordering differences.

Workflow

• 1. Diff two OpenAPI specs with the tool.
• 2. Detect textual differences such as enum changes.
• 3. Apply direction‑aware logic: if the change is in a response schema, treat enum shrinking as non‑breaking; if in a request schema, treat it as breaking.
• 4. Normalize specs by expanding $refs, sorting keys, and canonicalizing before diffing.
• 5. Generate a human‑readable changelog and a machine‑readable change list.

Evidence

First real dogfood run — comparing my own API's v3 spec against v2 — it flagged exactly one breaking change.

Source

The delta: a status field's enum went from ['queued','shipped','failed'] to ['queued','shipped']. Textbook breaking change, the differ said.

Source

A server returning fewer enum values cannot surprise a client that already handles all three — the client's switch statement still compiles.

Source

I now normalize specs before diffing — expand $refs, sort keys, canonicalize.

Source