Back to Directory/Developer Tools

io.github.sethclawd-prog/schemaguard

API Schema Drift Monitor — detect breaking changes in OpenAPI specs

Developer ToolsTypeScriptv0.1.2
View on GitHub

SchemGuard

API Schema Drift Monitor — detect breaking changes in OpenAPI specs before they break your consumers.

npm version License: MIT

Why

APIs break silently. A field gets renamed, an endpoint gets removed, an enum value disappears — and downstream consumers break in production. SchemGuard catches these before deploy.

Install

bash
npm install -g schemaguard

Usage

Diff two specs

bash
schemaguard diff old-api.yaml new-api.yaml

Output:

text
Found 11 change(s):

❌ BREAKING CHANGES (9):
──────────────────────────────────────────────────
  ⛔ [endpoint-removed]
     Endpoint removed: DELETE /pets/{petId}
     at: DELETE /pets/{petId}

  ⛔ [field-type-changed]
     Parameter type changed: petId (string → integer)
     at: GET /pets/{petId} > param petId
  ...

🚨 9 breaking change(s) detected — deployment blocked.

CI mode

bash
schemaguard ci --spec ./openapi.yaml --baseline ./main-openapi.yaml
  • Exit 0 = no breaking changes, safe to deploy
  • Exit 1 = breaking changes detected, blocks the pipeline
  • Exit 2 = error (invalid spec, file not found)

Lint a spec

bash
schemaguard lint ./openapi.yaml

Checks for missing operationId, missing descriptions, no security schemes, etc.

JSON output

bash
schemaguard diff old.yaml new.yaml --format json

Returns structured JSON for programmatic consumption by agents and CI tools.

What it detects

Breaking changes (exit code 1)

RuleDescription
endpoint-removedAn endpoint was deleted
method-removedAn HTTP method was removed from a path
required-param-addedA new required parameter was added
param-removedAn existing parameter was removed
request-field-made-requiredA request field became required
field-type-changedA field's type was changed
response-field-removedA response field was removed
enum-value-removedAn enum value was narrowed
auth-requirement-changedSecurity schemes were modified
response-code-removedA response status code was removed

Non-breaking changes (info only)

RuleDescription
endpoint-addedA new endpoint was added
optional-param-addedA new optional parameter was added
response-field-addedA new response field was added
enum-value-addedAn enum value was widened
description-changedDescription or summary text changed
deprecatedAn endpoint was marked as deprecated

GitHub Actions

yaml
- name: Check API compatibility
  run: npx schemaguard ci --spec ./openapi.yaml --baseline ./baseline.yaml

Programmatic API

typescript
import { parseSpec, diffSpecs, formatDiff } from 'schemaguard';

const oldSpec = parseSpec('./v1.yaml');
const newSpec = parseSpec('./v2.yaml');
const result = diffSpecs(oldSpec, newSpec);

if (result.hasBreakingChanges) {
  console.log(`${result.breaking.length} breaking changes found`);
}

License

MIT