09 / Change without surprise
Catch breaking API changes before clients discover them
Validate OpenAPI contracts, compare revisions, classify meaningful changes, and connect contract findings to tests and release decisions.
+
GET /invoices/{id}safe−
customer.emailbreaking~
status: string → enumreviewrecommended release MAJOR
The job
For API producers and consumers who need a shared, reviewable definition of behavior across releases.
- 01Find structural and semantic problems in an API description.
- 02Separate compatible additions from client-breaking changes.
- 03Give reviewers concrete evidence for a release decision.
Working sequence
The shortest honest path from input to evidence.
- 01
Import the contract
Use an OpenAPI document or derive a starting point from an API artifact.
- 02
Validate and compare
Check structure, policy, and change impact against a baseline.
- 03
Attach the finding
Move the result into tests, mocks, CI, or a release review.
Operating principle
The design constraint that keeps this useful.
Contract work stays connected to execution. The useful question is not merely whether YAML parses, but what a change means for clients and rollout.
Operational notes
Use the boundary, not just the capability.
- What formats are supported?
- OpenAPI is the primary contract format, with related conversion and schema workflows available.
- What counts as a breaking change?
- Examples include removing operations or fields, narrowing accepted values, and changing required inputs in ways existing clients cannot satisfy.
- Can this run in CI?
- Yes. Contract checks can be integrated into delivery workflows through API or exported tooling.
Next move
Start with one concrete API problem.
Keep the first step small. Move into a workspace when the result deserves to be saved, repeated, or shared.