openapi-breaking-diff

npm install @ferrow/openapi-breaking-diff

Compare two OpenAPI 3 documents and categorize changes as breaking or non-breaking, with JSON paths to each change. Strict TypeScript, zero runtime dependencies.

Why

CI pipelines need a fast, dependency-free way to catch accidental breaking changes between API spec versions — without pulling in a full OpenAPI validation/tooling stack. This library takes plain parsed JSON objects in (you load them however you like) and walks paths, parameters, request/response schemas to flag exactly what broke and where.

Quickstart

import { checkBreaking } from "openapi-breaking-diff";

const { exitCode, result } = checkBreaking(oldSpecJson, newSpecJson);
for (const change of result.breaking) {
  console.error(`[${change.kind}] ${change.path} — ${change.message}`);
}
process.exit(exitCode);

API

diffOpenApi(oldDoc, newDoc): DiffResult

{ changes, breaking, nonBreaking } — each Change has { category, kind, path, message }.

checkBreaking(oldDoc, newDoc)

CI-friendly wrapper: { exitCode: 0 | 1, result }.

Classification

BREAKING: removed path/method, new required parameter, request field newly required, request body newly required, removed response field, response removed, schema type change, enum narrowed.

NON-BREAKING: new endpoint/method, added optional parameter/field, response added, enum widened, description changed, request field no longer accepted (server-side relaxation).

Limits

• Operates on plain objects you supply — it does not fetch, parse YAML, or resolve $ref pointers. Dereference your spec before diffing if it uses $ref.
• Path-level (as opposed to operation-level) parameters are not merged in; only operation-level parameters are compared.
• Schema comparison covers type, properties, required, enum, and items — it does not walk oneOf/anyOf/allOf composition.

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow