DiffHaven.

THE FIELD GUIDE

A review you
can inspect.

What DiffHaven does, how to read its findings, and where the checks stop.

01 / GETTING STARTED

The workflow

  1. Choose your baseline. Paste the current OpenAPI JSON into Before, then the proposed version into After. You can also open a local .json file in either panel.
  2. Compare versions. The browser parses both documents, checks supported structural changes, and computes the findings. Load sample opens and compares two versions of a fictional parcel API.
  3. Read in context. Filter by severity or search for a path, title, rule or explanation. Select a finding to inspect the exact source values and suggested actions.
  4. Prepare your release. Review the suggested tests, then export a Markdown or JSON report. Checklist ticks are temporary UI notes, not test results.

Copy A to B is a quick way to explore an unchanged contract. Any input edit clears the previous review and disables exports until another successful comparison.

Open the workspace →

02 / CONTRACTS

Supported inputs

OpenAPI 3.0.x and 3.1.x, as JSON. A document must contain an OpenAPI version, an info object with title and version, and a paths object. UTF-8 JSON files with a byte order mark are accepted by the parser.

The workspace caps each input at 2 MiB (UTF-8 bytes). The engine may impose additional complexity limits. YAML, Swagger 2, malformed JSON and unsupported documents fail with a visible error; they are not silently converted.

Local fragment references are followed where supported. Remote references are not fetched. Circular or unsupported references can limit coverage and are disclosed in warnings.

03 / TRIAGE

Reading the review

Breaking
A supported check found a likely incompatible change, such as removing an operation or requiring a previously optional request parameter. Confirm impact against your real clients.
Review
A change needs human judgment. For example, a response property may no longer be guaranteed without being deleted.
Additive
New surface area, such as an added operation or a justified optional addition. Additive does not certify overall compatibility.

Counts are computed from engine findings, not from sample labels. Search and severity filters change only the visible list. The total and exports always refer to the complete comparison.

04 / PROVENANCE

Follow the pointer

Every finding includes Before and After evidence, with RFC 6901 JSON Pointers. A pointer identifies a location in the original document, using ~1 for a slash and ~0 for a tilde. For example, /paths/~1parcels/get points to the GET operation under /parcels.

References to component schemas point to the actual schema location, not an invented child under $ref. “Not present” means the evidence is absent on that side. A JSON null at a real pointer is shown as a value, not confused with absent evidence.

Values are displayed as text, never interpreted as HTML. Suggested tests are authored by deterministic rules; no test is executed by the workspace.

05 / HANDOFF

Take the review with you

Markdown is a readable release-review document. JSON is a structured report for your own tooling. Both download directly from the browser and include the complete, unfiltered review, source evidence and limitations—not the entire raw input documents.

Evidence may contain sensitive snippets from your contracts. Inspect the report before sharing it. Downloads remain on your device unless you share them yourself.

06 / THE BOUNDARIES

Coverage & limitations

DiffHaven is a focused change reviewer, not a complete OpenAPI validator. No findings is not proof of compatibility, and a valid input is not a certification of the API.

Targeted checks

  • Added and removed operations.
  • New required request parameters and optional-to-required changes.
  • Request parameter type changes and narrowing enums.
  • Required request body additions; removed request media.
  • Removed response statuses and media types.
  • Reachable nested object properties, arrays and local component schemas.
  • Request property requirements; response property removal and loss of guarantees.
  • Direction-aware request enum narrowing and response enum widening.
  • Direction-aware string length (minLength, maxLength) and array size (minItems, maxItems) bound changes on schemas where both versions allow strings or arrays. Invalid bound values and contradictory ranges are reported as warnings, not classified.

Not a full compatibility check

  • oneOf, anyOf, allOf and other sophisticated JSON Schema constraints (such as pattern, format, numeric limits and uniqueItems) are not fully analyzed.
  • Security requirements, server URLs and other unimplemented contract areas need manual review.
  • Remote or circular references can limit analysis. Read the report's warnings.
  • Runtime behavior, authentication, performance, implementation correctness and consumer-specific behavior are not tested.
  • No endpoint calls, linting service, repository integration or CI gate.

Coverage warnings are shown above the findings and included in exports. Check these before treating the findings as a release checklist.

07 / DEVELOPMENT DIRECTION

Better coverage, still local.

Findings, explanations and test suggestions come from deterministic browser-side rules. No AI integration is planned for the product. There is no AI API key setup or model request in the analysis path.

The direction is broader check coverage, regression fixtures and clearer documentation while keeping contract review browser-local and reproducible. Claude Code was used for development assistance on 2026-10-08 to implement string-length and array-size checks and regression tests. Changes were independently reviewed and tested; it is not an in-product explanation service. There is no commitment to a launch date, paid tier or future feature.