Show HN: Zof API Contract Check

Zof-AI published version 0.1.1 of @zof-ai/api-contract-check, an offline CLI that compares two OpenAPI 3.0/3.1 JSON contracts and flags breaking changes before merge, exiting 1 when findings meet the failure threshold and 0 when the supported checks pass. In the package's synthetic example, the tool reports a high-severity type-incompatible finding because the response field `id` changed from integer in the baseline to string in the candidate. The tool requires Node.js 22 or 24 plus Python 3.10+ on Linux or macOS, does not support YAML, `allOf`/`oneOf`/`anyOf`, or external references, and does not run an API or prove runtime compatibility.

Flag breaking changes in supported OpenAPI JSON contracts before merge. Compare two local files and get a finding such as: the response field id changed from integer to string . Runs offline without a Zof account or source upload. Use this for OpenAPI 3.0/3.1 JSON contracts or the documented JSON Schema subset. YAML, allOf / oneOf / anyOf , and external references are unsupported and return an incomplete-analysis error. See supported scope https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/LIMITATIONS.md before trying your own contract. Captured from the public 0.1.1 package using synthetic examples; playback is paced for readability. The commands and findings are written out below. Terminal recording https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/media/contract-check.cast . Use Node.js 22 or 24 , npm, and Linux or macOS with Python 3.10+ . Windows file operations fail closed. In a new project directory, install the published version and run its deliberately breaking example: npm install --ignore-scripts --save-exact @zof-ai/api-contract-check@0.1.1 npx --no-install zof-api-contract-check baseline.json breaking.json --root node modules/@zof-ai/api-contract-check/examples --kind openapi --markdown The command exits 1 , as intended. Its finding is: - high type-incompatible: The accepted or returned value type is incompatible. GET /items/responses/200/schema/properties/id The full report also lists the analysis limitations. The baseline declares id as an integer; the candidate declares a string. A client expecting an integer needs review before that change is released. Compare the compatible example next: npx --no-install zof-api-contract-check baseline.json compatible.json --root node modules/@zof-ai/api-contract-check/examples --kind openapi --json This command exits 0 and reports compatible: true for the supported checks. Neither command runs an API, sends requests, or proves runtime compatibility. The package includes compiled JavaScript, TypeScript declarations, runtime dependencies, and synthetic examples. --ignore-scripts disables installation lifecycle scripts; --no-install keeps later commands from downloading another package. Package: @zof-ai/api-contract-check https://www.npmjs.com/package/@zof-ai/api-contract-check . Place the baseline and candidate inside one explicit directory: npx --no-install zof-api-contract-check baseline.json candidate.json --root contracts --kind openapi --markdown For standalone JSON Schema files, use --kind json-schema ; the comparison describes accepted inputs, so a narrower candidate constraint is incompatible. Default reports are Markdown; --json produces structured findings. An optional --policy policy.json is resolved under the same root and can change severity and the failure threshold without removing findings. | Exit code | Meaning | CI treatment | |---|---|---| | 0 | Completed supported checks below the policy threshold | Check succeeded | | 1 | Findings meet the failure threshold | Review the contract change | | 2 | Invalid, unreadable, unsupported, or incomplete input | Fix the input or coverage gap; never count as a pass | Copy the complete GitHub Actions workflow https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/examples/github-actions/api-contract.yml to .github/workflows/api-contract.yml , then change its two openapi.json paths to your contract's repository-relative path. The workflow compares the PR's exact base and head commits using this package's CLI. It installs the tool separately and does not install or execute the checked-out application's code. Read the CI quickstart https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/CI.md for prerequisites, path configuration, branch protection, and the workflow's limits. The separate Zof GitHub Action performs generic source checks; this workflow calls API Contract Check directly. The walkthroughs https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/WALKTHROUGHS.md use the published npm package and synthetic inputs: 1. A response field changes from integer to string. 2. A new required query parameter breaks callers that omit it. 3. An authentication declaration changes during a rollout. Each includes a runnable command, actual finding, expected exit code, and a follow-up check. These are reproducible teaching examples, not customer outcomes. js import { compareContracts, readContract, renderMarkdown } from '@zof-ai/api-contract-check'; const baseline = await readContract process.cwd , 'baseline.json' ; const candidate = await readContract process.cwd , 'candidate.json' ; const report = compareContracts baseline, candidate, { failOn: 'high' } ; console.log renderMarkdown report ; See the API reference https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/API.md for supported options and findings. For source builds, use the pinned source installation and development guide https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/DEVELOPMENT.md . npm consumers can use the quickstart above without building this repository. See limitations https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/LIMITATIONS.md , security https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/SECURITY.md , contributing https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/CONTRIBUTING.md , and release gates https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/RELEASE.md . No telemetry or hosted integration is implemented. Independently authored and licensed under Apache-2.0 https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/LICENSE .