{"slug": "show-hn-zof-api-contract-check", "title": "Show HN: Zof API Contract Check", "summary": "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.", "body_md": "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.\n\nUse 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.\n\nCaptured 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).\n\nUse **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:\n\n```\nnpm install --ignore-scripts --save-exact @zof-ai/api-contract-check@0.1.1\nnpx --no-install zof-api-contract-check baseline.json breaking.json --root node_modules/@zof-ai/api-contract-check/examples --kind openapi --markdown\n```\n\nThe command exits **1**, as intended. Its finding is:\n\n```\n- **high** type-incompatible: The accepted or returned value type is incompatible. (GET /items/responses/200/schema/properties/id)\n```\n\nThe 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.\n\nCompare the compatible example next:\n\n```\nnpx --no-install zof-api-contract-check baseline.json compatible.json --root node_modules/@zof-ai/api-contract-check/examples --kind openapi --json\n```\n\nThis command exits **0** and reports `compatible: true` for the supported checks. Neither command runs an API, sends requests, or proves runtime compatibility.\n\nThe 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).\n\nPlace the baseline and candidate inside one explicit directory:\n\n```\nnpx --no-install zof-api-contract-check baseline.json candidate.json --root contracts --kind openapi --markdown\n```\n\nFor 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.\n\n| Exit code | Meaning | CI treatment | \n|---|---|---|\n| 0 | Completed supported checks below the policy threshold | Check succeeded | \n| 1 | Findings meet the failure threshold | Review the contract change | \n| 2 | Invalid, unreadable, unsupported, or incomplete input | Fix the input or coverage gap; never count as a pass | \n\nCopy 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.\n\nRead 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.\n\nThe [walkthroughs](https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/WALKTHROUGHS.md) use the published npm package and synthetic inputs:\n\n1. A response field changes from integer to string.\n2. A new required query parameter breaks callers that omit it.\n3. An authentication declaration changes during a rollout.\n\nEach includes a runnable command, actual finding, expected exit code, and a follow-up check. These are reproducible teaching examples, not customer outcomes.\n\n``` js\nimport { compareContracts, readContract, renderMarkdown } from '@zof-ai/api-contract-check';\nconst baseline = await readContract(process.cwd(), 'baseline.json');\nconst candidate = await readContract(process.cwd(), 'candidate.json');\nconst report = compareContracts(baseline, candidate, { failOn: 'high' });\nconsole.log(renderMarkdown(report));\n```\n\nSee the [API reference](https://github.com/Zof-AI/zof-api-contract-check/blob/e9d45f612e75406b1f943c7bab76fab600fa950f/docs/API.md) for supported options and findings.\n\nFor 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.\n\nSee [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).", "url": "https://wpnews.pro/news/show-hn-zof-api-contract-check", "canonical_source": "https://github.com/Zof-AI/zof-api-contract-check/tree/e9d45f612e75406b1f943c7bab76fab600fa950f", "published_at": "2026-10-22 18:37:35+00:00", "updated_at": "2026-10-22 18:42:04.395333+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["Zof-AI", "@zof-ai/api-contract-check", "OpenAPI", "Node.js", "GitHub Actions"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-zof-api-contract-check", "markdown": "https://wpnews.pro/news/show-hn-zof-api-contract-check.md", "text": "https://wpnews.pro/news/show-hn-zof-api-contract-check.txt", "jsonld": "https://wpnews.pro/news/show-hn-zof-api-contract-check.jsonld"}}