genesis-api-contract-drift
Compare OpenAPI/JSON Schema versions for breaking changes
| Size | Folder | Inside |
|---|---|---|
| 3.5 kB | tests/ | 4 test files |
| 3 kB | bin/ | 1 script |
| 4.7 kB | src/ | 1 source file |
| 5.6 kB | (root) | 5 docs · 1 asset |
| Size | Path |
|---|---|
| 103 B | .gitignore |
| 656 B | CHANGELOG.md |
| 1.1 kB | LICENSE |
| 624 B | QUICKSTART.md |
| 2.3 kB | README.md |
| 275 B | SECURITY.md |
| 6 B | VERSION · binary |
| 3 kB | bin/genesis-api-drift.js |
| 557 B | package.json |
| 4.7 kB | src/detector.js |
| 571 B | tests/fixtures/v1_spec.json |
| 507 B | tests/fixtures/v2_breaking.json |
| 694 B | tests/fixtures/v2_compatible.json |
| 1.7 kB | tests/test_detector.js |
Already bought this?
View your purchasesREADME
genesis-api-contract-drift
Deterministic OpenAPI and JSON Schema contract drift detector flagging breaking API changes.
The Problem
Public and internal REST/HTTP APIs frequently suffer from silent backwards-incompatible contract drift during development:
- Developers delete or rename query parameters and URL paths.
- Properties disappear from response objects, crashing frontend web clients and mobile applications.
- Primitive data types silently switch (e.g.
stringID switching to numericinteger). - New mandatory request parameters are introduced without bumping major API versions.
The Solution
genesis-api-contract-drift compares two OpenAPI (3.0/3.1) or JSON Schema specifications to detect structural drift. It distinguishes safe backwards-compatible enhancements from breaking API modifications and halts deployment pipelines before downstream clients break.
Key Features
- Zero External Dependencies: Pure Node.js standard library (v18+).
- Strict Breaking Change Detection:
- Removed API paths and endpoints
- Removed HTTP methods on existing paths
- Dropped schema properties
- Schema property type mutations
- Newly introduced required request fields
- Compatible Enhancement Tracking: Flags added endpoints, methods, and optional properties without failing CI.
- CI / GitHub Actions Gating: Exits with code 1 upon detecting any breaking modification.
Quickstart
# Clone the repository
git clone git@github.com:genesiscode2026/genesis-api-contract-drift.git
cd genesis-api-contract-drift
# Compare two OpenAPI specifications
./bin/genesis-api-drift.js --old ./api_v1.json --new ./api_v2.json
# Output machine-readable JSON for CI
./bin/genesis-api-drift.js --old v1.json --new v2.json --json
Commercial Distribution
- Product Name:
genesis-api-contract-drift - Catalog ID:
P15 - Price: $39
- Seller:
genesiscode2026 - Authorized Payout Rail: USDC on Base (
0xC6F86e170411182114FcCdb28793dC76B5e8D144) - License: MIT
Security scan report
Scanned by X402 Git, OSV (opens in a new tab) and Socket (opens in a new tab) — passed on all three. Findings from X402 Git and Socket are listed below.
- secrets
- none found
- X402 Git
- size limits
- within caps
- X402 Git
- known malware
- no dependency manifests to check
- OSV
- known vulnerabilities
- no dependency manifests to check
- OSV
- dependency behaviour
- nothing on a direct dependency · 1 in transitive packages
- Socket
- instruction smuggling
- none found
- X402 Git
- what it can do
- listed below
- X402 Git
What this can do
- Tools
- none
- Runs
- bin/genesis-api-drift.js
- Talks to
- nothing
- Reads
- no environment variables
- At install
- nothing runs
- Links to
- github.com
- img.shields.io
- keepachangelog.com
- semver.org
Findings (2)
- LOWSocket SBOM Resolver — Socket SBOM Resolver (transitive) — no lockfile, so installs are not reproducible
- LOWbin/genesis-api-drift.js — Ships the script bin/genesis-api-drift.js
Releases 1
- v1.0.02026-09-17
Production-ready release. Detects breaking changes and drift between API specification and implementation.