Detect Breaking OpenAPI Changes with oasdiff
Build an oasdiff CI check against the released API contract. Review request and response direction, generated SDK changes, and authentication changes separately.
Compare a proposed OpenAPI description with the contract your consumers actually received. Use oasdiff to identify contract changes in CI, then review generated clients and deployed behavior separately. A clean comparison is not proof that every SDK remains compatible or that the implementation matches either description.
Compatibility is directional. A server generally preserves request compatibility by continuing to accept previously valid requests. It preserves response compatibility by continuing to produce responses that old consumers can handle. Therefore, adding a response value can be more disruptive than adding an accepted request value. Avoid a blanket rule that every addition is safe.
Which changes need separate decisions?
| Proposed change | Contract or HTTP concern | Client review |
|---|---|---|
| Add a required request property | Old requests can become invalid | Check callers that omit it |
| Remove a permitted request enum value | Previously accepted input can fail | Find callers using that value |
| Add a possible response enum value | Old response validators may reject it | Check exhaustive switches and unknown-value handling |
| Stop returning a required response property | The old response guarantee is lost | Check deserialization and dependent code |
| Rename an operationId or component | Need not change HTTP messages | Generated method or type names may change |
| Rename only a path placeholder | /items/{id} can describe the same URL as /items/{itemId} | Parameter names and generated signatures may change |
| Change a serialized discriminator value | Response content and branch selection can change | Check old values and union handling |
Adding an optional response field also needs context. A consumer that rejects unknown properties can fail. A new response status or media type may reach a branch that an existing client does not handle. Neither outcome is universally safe. Changing a query parameter's actual name differs from renaming an internal path placeholder: the query name is part of the request.
The oasdiff endpoint-matching documentation explains that path parameter names are ignored during default matching. Inspect the matched operations rather than treating every placeholder rename as endpoint removal.
How do you put oasdiff in CI?
The official breaking-change reference documents the commands and failure thresholds. Use a reviewed, pinned oasdiff release. Prepare two local descriptions with their complete reference sets: contract-released.yaml from an immutable release artifact and contract-candidate.yaml from the proposed change.
This shell step assumes those files and the binary are already available:
set -eu
oasdiff changelog contract-released.yaml contract-candidate.yaml \
--format json > contract-changelog.json
oasdiff breaking contract-released.yaml contract-candidate.yaml \
--fail-on ERR
This is a configuration example, not a reported test run. changelog reports consumer-relevant changes. breaking selects breaking-change findings. --fail-on ERR makes error-level findings fail the check. --fail-on WARN also fails on warnings, so it is stricter, not a softer gate. Keep the report as a CI artifact even when the gate fails.
Validate both descriptions first. A missing baseline, unresolved reference, or tool failure must not become a successful empty comparison. Pin remote reference content or retain reviewed local copies. Comparing only with the previous commit can miss a break introduced several commits before the release. Record both input hashes, the tool version, and the rule configuration.
Why do authentication changes need another review?
Requiring a new credential or OAuth scope can break existing authorized clients. Removing authentication can instead create a security regression while making requests easier to accept. A compatibility check and a security check answer different questions.
Review the effective requirement for each operation. The OpenAPI security model distinguishes alternative requirements from combined schemes and permits operation-level overrides. Compare those declarations with the server's actual checks. In an authorized fixture, verify missing-token denial and a valid caller without the required grant. Do not preserve an unsafe authorization behavior merely to keep a compatibility report green.
What closes the change review?
Generate affected SDKs with the same generator version and configuration before and after the contract change. Compile representative existing calls and inspect serialization and authentication wiring. OpenAPI names can influence generated interfaces, but no universal rule determines every generator's output.
Keep a decision record for each material change: affected consumers, contract finding, SDK impact, runtime evidence, migration path, and owner. For an intentional break, agree on versioning and a support window that fits the actual service commitments. Do not invent a universal retention period. Use remediation acceptance tests to retain the security property after the compatibility decision is complete.
Find the gaps in your access controls
See how an illustrative cross-workspace finding connects evidence, impact and a fix. Discuss the tenant boundaries your team needs reviewed.
Sources
- oasdiff Breaking Changes and ChangelogAccessed
- oasdiff Endpoint MatchingAccessed
- OpenAPI Specification v3.1.2Accessed