Problem solved by Diff Anything macOSWindows

Review API compatibility, not YAML movement

Compare OpenAPI and JSON Schema locally, classify compatibility changes, and keep API contracts off an online comparison service.

See it in the app

A focused workflow, on your computer.

No accounts, cloud comparison service, analytics, or telemetry.

Diff Anything 1.4 three-way merge workspace showing Ours and Theirs against Base with an unresolved conflict
Diff AnythingStructured comparison keeps compatibility findings connected to the original contract sources.

The problem

Why the usual workflow gets in the way.

A line diff can make reordered YAML or JSON look important while hiding the contract changes that can break an existing API consumer: removed operations, narrower schemas, changed parameters, or new requirements.

The solution

How Diff Anything handles it.

Diff Anything parses OpenAPI and JSON Schema as contracts and classifies compatibility-oriented changes. Pro batch manifests can emit JSON, JUnit, or SARIF and return process exit codes for release checks.

01 / Contract review

Name the baseline and candidate correctly

The baseline is the contract existing consumers already use; the candidate is the proposed replacement. That direction matters because removing an operation or narrowing an accepted value has a different compatibility effect from adding one.

Keep the source versions available during review. A compatibility classification is evidence for a release decision, not a substitute for understanding the affected consumer workflow.

02 / Contract review

Separate likely breaks from context-dependent changes

Review removed or newly required contract elements first, then examine changes whose effect depends on consumer behavior or runtime semantics. Compatible additions still deserve review when undocumented behavior or custom validation exists.

The comparison describes the contract it can parse. Runtime behavior, server implementation, and undocumented expectations remain outside that evidence.

  • Start with removed paths, operations, parameters, properties, and enum values.
  • Review new requirements and narrower types.
  • Treat semantic behavior as a human review boundary.

03 / Contract review

Use machine-readable output only after reviewing the rule set

Pro batch manifests can emit JSON, JUnit, or SARIF and use process exit codes in a release check. Establish the comparison mode and acceptable findings interactively before turning the result into a gate.

Keep the same baseline direction and contract sources in local and automated workflows so the release check answers the same question each time.

Clear answers

Common questions about compare OpenAPI specifications locally.

Is an OpenAPI diff the same as a text diff?

No. Contract comparison focuses on parsed operations, parameters, schemas, and compatibility-oriented changes rather than source line movement alone.

Can the result be used in CI?

Yes. Diff Anything Pro batch manifests can emit JSON, JUnit, or SARIF and return process exit codes for release checks.

Does the comparison prove runtime compatibility?

No. Runtime behavior, custom validation, undocumented expectations, and semantic meaning still require human review and testing.

Three short steps

Compare the contract that clients depend on.

  1. 01

    Open the baseline and candidate contracts.

  2. 02

    Choose the OpenAPI or JSON Schema comparison mode.

  3. 03

    Review compatibility findings and export or automate the result where appropriate.

Available for macOS and Windows

Solve it with Diff Anything.