Runbook: OpenAPI Contract-Test Failing

Trigger

• make contract-test fails.
• make verify fails on the contract-test stage.
• CI reports OpenAPI snapshot drift vs baseline.

Fast triage

1. Run make contract-test to see the diff summary.
2. Identify whether changes are intentional or accidental.
3. If accidental, revert/fix API contract changes in code.
4. If intentional, validate compatibility and docs, then accept baseline update.

Most common causes

• Field type changed in request/response schema.
• Error code/key mapping changed unintentionally.
• Response status set changed (for example removed 422 or 404).
• A field or parameter flipped between required and optional.
• OpenAPI examples or router response declarations diverged from implementation.

Recovery paths

Unintentional contract drift

• Fix schema/router/validation code to restore expected contract.
• Re-run make openapi-check and make contract-test.
• Run make verify before commit.

Intentional contract change

• Confirm the change is safe for the current API major version.
• Update tests, examples, and related docs/ADR notes.
• Accept new baseline: make openapi-accept-changes.
• Re-run make contract-test and make verify.

Final recovery sequence

1. make openapi-check
2. make contract-test
3. make verify

Exit criteria

• make contract-test passes.
• make verify passes end-to-end.
• If you updated the baseline, the commit message or PR explains why.

Follow-up

• If compatibility rules changed, update an ADR and developer docs.
• If this keeps happening, tighten checks in scripts/openapi_governance.py.

Page history