Inspiration
A tiny API diff can break a real integration. Adding an enum value looks harmless until it appears in a response an old client cannot handle. Contract Lens makes that direction visible instead of treating every text change the same way.
What it does
Contract Lens is a browser-local OpenAPI 3.0 workbench. Paste or import old/new JSON or YAML contracts, analyze the release, select affected operations, inspect resolved schemas, run editable payload counterexamples and export JSON evidence or Markdown migration notes.
Requests should keep accepting old inputs: old is a subset of new. Responses should stay inside old guarantees: new is a subset of old. The engine swaps source and target for responses. A shared referenced schema is checked in every affected operation, so an impact is not hidden behind a component-only diff.
The synthetic Dispatch API examples include a breaking release, an additive release and a deliberately unsupported release. The breaking fixture yields four findings and three checked schema witnesses. The additive fixture has no findings in the checked scope and one new endpoint. Unsupported patterns and composed schemas produce manual-review entries, not a green certificate.
How it was built
A pure JavaScript engine handles bounded parsing, local JSON Pointer references, operation/parameter matching, directional schema rules, deterministic candidate generation and source/target validation. The interface is custom HTML/CSS/JavaScript with text-only DOM rendering, responsive editors, an impact map, filters and an interactive witness tester. The YAML package is bundled locally with esbuild. There is no runtime LLM, paid API, account requirement, analytics, backend or spec-upload endpoint. Static hosting is on GitHub Pages.
New work started November 13, 2026, during this hackathon. This is not a recycled prior entry. It uses synthetic data, not private customer contracts.
Release review update (added after the first submission)
After the original submission, the project gained a release review workflow so that a comparison ends in a recorded decision, not only a list.
- Each finding and manual-review item can get a decision (accepted risk, will migrate callers, not an issue) with a required note.
- A release gate with a policy (breaking; breaking and potential; everything including manual review) stays OPEN until every blocking item has a status and a non-empty note. A PASS reads "all blockers acknowledged, not fixed": a waiver or plan is not evidence that a migration happened or that the API is compatible.
- Save/load review session: a JSON file with decisions only, no specs. It carries a SHA-256 fingerprint of the exact baseline and candidate pair, and a session for a different pair is rejected whole, so waivers cannot transfer between releases whose findings happen to be worded alike. Nothing is persisted in browser storage.
- A command-line mode (node cli.js old new --fail-on breaking --decisions session.json) uses the same engine. Exit 0: every blocking item acknowledged. 1: gate open. 2: bad input or a mismatched session.
- The Markdown migration report now includes decisions and gate state.
Technical challenges and development lessons
Compatibility is directional: request narrowing and response widening can both harm old clients. Producing a plausible example is not enough, so a witness must pass the supported source validator and fail the target validator before being marked verified. Related changes at one schema location are grouped; one witness may demonstrate only one listed reason.
References add another boundary. Local refs are expanded with own-property lookup, JSON Pointer escape handling and cycle/depth checks. Recursive/external refs and ref siblings go to review. Input edits invalidate old results and disable stale exports.
Verification
68 Node tests (engine, review module, CLI and session binding) cover the fixtures, input/output variance, nested constraints, required fields, additional properties, array items, parameters, media/status changes, reference cases, unsupported features, parser limits, witness gates, deterministic reports and response-direction wording. Two Playwright suites cover scenarios, the decision/gate/session flow, operation filtering, editable witness outcomes, JSON export, invalid input, the scope dialog, 320/390px layouts, console errors and external requests. Actual desktop/mobile pixels were reviewed. For the original submission a fresh public clone was tested. For the release review update, the published files were compared byte for byte with the tested working copy, and the live site was checked in a browser.
Honest limits
This is a bounded OpenAPI 3.0 prototype, not a full OpenAPI linter, complete JSON Schema solver, live API test or proof of compatibility. No findings means no issue found in the checked subset. Composition, regex/format, readOnly/writeOnly projections, recursive/external refs, security, response headers and serialization semantics need manual review. Removed statuses, missing response-body cases and some header/content changes are not exhaustively checked. Runtime behavior and business rules are outside scope.
Witness search is finite, does not guarantee minimality, and can miss payloads. Inputs have size/node/depth limits and YAML aliases/prototype-sensitive keys are rejected, but the parser is not audited for hostile specs. Reports may contain schemas and payloads, so users should review them before sharing.
AI and open-source disclosure
Built with AI assistance for design, code generation, debugging, automated testing and demo production. The project was requested and directed by M J Anthony; the post-submission release review upgrade was also implemented with AI assistance. Implementation and automated testing were AI-assisted; this is not a claim that the entrant personally hand-wrote or manually tested every part. The demo includes AI-generated narration and captions over real application footage.
Tools/libraries: JavaScript, HTML, CSS, YAML (ISC), esbuild (MIT), Node.js test runner, Playwright (Apache-2.0), Python for document/media tooling, FFmpeg for video assembly, and AI assistance as described above. Code is MIT licensed; runtime/build license notices and locked dependencies are in the public repository. No template project was reused.
Next steps
Independent OpenAPI/schema validation, full reference provenance, composed-schema support, consumer-contract import, worker-based isolation, memoization, broader accessibility/browser testing and a packaged CI action (a basic CLI exists now). These are future work, not current feature claims.