Contract Watch

Contract Watch is a tiny TypeScript CLI that compares two OpenAPI JSON contracts and reports breaking API changes before they surprise clients.

It is designed for pull requests, release checks, and backend teams that want a fast contract-safety signal without wiring up a full API gateway.

What It Detects

• Removed paths
• Removed HTTP methods
• Removed response status codes
• Newly required request fields
• Changed response media types

Quick Start

npm install
npm run build
npm run dev -- examples/base.openapi.json examples/next.openapi.json

Example output:

Contract Watch found 3 breaking changes

[high] GET /users/{id}
Removed response status 200.

[critical] POST /users
Request field "email" became required.

CLI

contract-watch BASE_SPEC NEXT_SPEC [--json]

During local development:

npm run dev -- BASE_SPEC NEXT_SPEC

JSON output is useful in CI:

npm run dev -- examples/base.openapi.json examples/next.openapi.json --json

CI Usage

npm run dev -- openapi/main.json openapi/pr.json

The command exits with:

• 0 when no breaking changes are detected
• 1 when breaking changes are found
• 2 for invalid input or CLI usage errors

Development

npm install
npm run check

Why This Project Exists

API compatibility is a practical engineering problem: small backend changes can break mobile apps, dashboards, integrations, and partner systems. Contract Watch shows how to turn that risk into an automated, explainable check.

License

MIT