oasdiff for coding agents

When a coding agent changes an API description, check whether existing clients will still work with the new contract. An API contract documents the operations, inputs, and responses a service offers. oasdiff compares two OpenAPI descriptions and reports changes, including changes that can break existing clients.

An agent can use oasdiff to compare the previous and proposed descriptions before you review the code. The tool reads the two descriptions and prints a report. It does not change the API description. This article explains how to install the command, compare local files, and use the report to guide an API change.

Install oasdiff

The oasdiff README documents several install methods. If Go is installed, run:

go install github.com/oasdiff/oasdiff@latest

Go installs the oasdiff command using its standard install mechanism. On macOS, the README also lists brew install oasdiff, and prebuilt binaries are on the releases page. If your shell cannot find oasdiff afterward, check that Go’s binary directory is on your PATH.

Local comparisons do not require an account or API key. A spec can still point outside itself with an external $ref, a reference to another file or URL. By default oasdiff follows those references, which can mean fetching a URL. The project’s page on external refs recommends --allow-external-refs=false for specs you don’t trust. With that flag, oasdiff refuses such a reference and exits with code 123. If you use remote specification URLs instead of files, the command must fetch those URLs, and any access requirements come from the remote host.

Compare the old and new contracts

Save the earlier OpenAPI document as api-baseline.yaml and the proposed document as api-current.yaml. These names are placeholders for paths in your repository. Then run:

oasdiff diff api-baseline.yaml api-current.yaml

The diff command prints the full diff between the baseline and current descriptions, including documentation-only edits. Its default output format is YAML. To see which changes could affect compatibility, run:

oasdiff breaking api-baseline.yaml api-current.yaml

A breaking change is a contract change that can cause a client built against the earlier description to stop working. For example, removing an operation or changing a required input can affect existing clients. oasdiff breaking reports changes at two levels. ERR marks definite breaking changes, and WARN marks possible ones that oasdiff cannot confirm from the description. oasdiff changelog also lists the non-breaking changes. If the baseline is committed in Git, oasdiff can read it from a revision, as in oasdiff breaking origin/main:openapi.yaml openapi.yaml.

By default, breaking prints a readable text report to standard output. To have another tool read the report as JSON, add the documented format option:

oasdiff breaking api-baseline.yaml api-current.yaml --format json

JSON lets an agent inspect individual findings or pass them to a script. For continuous integration (CI) checks, --fail-on ERR makes the command exit with code 1 when it finds ERR-level changes, and --fail-on WARN also counts warnings. The breaking and changelog commands also have an --open flag that uploads an encrypted copy of the comparison to oasdiff.com and opens it in a browser. Leave it out when the specs should stay on your machine.

Give an agent a bounded task

Ask an agent to add an API operation and check whether the change affects existing clients. The agent can edit the current specification and compare it with the baseline. The agent can use the report to decide whether to preserve compatibility or call out a breaking change.

A prompt could say:

Update api-current.yaml to add the requested operation. Compare it with api-baseline.yaml using oasdiff breaking. Summarize any breaking changes and their affected operations. Do not change the baseline file.

The paths are placeholders; replace them with files in your repository. In this example, the agent reads both descriptions and runs a local command. The command does not write a report file. If the agent edits the specification to address a finding, review that edit separately and run the comparison again.

Treat the report as a contract check

oasdiff checks what the OpenAPI descriptions say. It does not run the service, exercise client code, or prove that a proposed change behaves correctly at runtime. A clean compatibility report therefore does not replace tests or review of the implementation. Likewise, a reported breaking change is a reason to examine the affected contract and decide whether the change is intentional.

In an automated run, have the agent run the breaking check after editing the specification and include the report in its summary. Separately decide whether your CI should block a change when the check finds a breaking change. On GitHub, the oasdiff project maintains an official GitHub Action that runs the breaking check on pull requests and can fail the job.