Practical guide
How to detect breaking changes in public OpenAPI specifications
A contract diff is useful only when the source is trustworthy, the comparison is semantic, and a consuming team can turn the result into a bounded engineering check.
1. Preserve each public source revision
Fetch the provider's documented OpenAPI URL on a declared cadence. Store the source URL, retrieval time, response status and immutable content hash. Treat retrieval and parsing failures as explicit health states, never as “no change.”
2. Compare semantics, not lines
Use established tools such as oasdiff or OpenAPI tooling rather than a text diff. Look for removed operations or properties, new required inputs, narrowed enums and incompatible schema changes.
oasdiff breaking previous.yaml current.yaml3. Keep source evidence
An alert should identify the provider, operation, before/after contract fragments, source and detection time. Provider migration guides remain important because SDK and runtime behavior may not be represented by an OpenAPI document.
4. Map the change to one check
Do not claim a customer's integration is broken without its code or runtime evidence. Recommend a bounded action instead: search for the removed field, rerun a named integration test, or verify handling of a new required parameter.
Teams that already collect provider contracts and maintain CI checks may not need a managed service. ContractSignal is testing whether independent observation plus source-linked consumer evidence is worth paying for.
For the complete consumer-side workflow, read how to monitor third-party API changes without private access.
Inspect the frozen sample report or review the ContractSignal experiment.