Published API contracts remain backward compatible within a version
api-009
Intent
Mixed-version deployments and deployed clients must continue working until a deliberate versioned migration happens.
Applicability
Applies when the diff changes a published route, method, request or response schema, serialized payload, or interface behavior in the current supported version.
What to inspect
Contract diffs, route declarations, DTOs, request validation rules, response fields, status codes, accepted values, default behavior, and any compatibility shims or dual-read or dual-write logic.
Pass criteria
Current-version changes are additive or compatibility-preserving, and any incompatible change is introduced behind a new version, additive alias, or visible migration path.
Fail criteria
The diff removes or renames paths or fields, adds new required inputs to an existing operation, narrows accepted values, changes a field or parameter meaning in place, changes a success code incompatibly, or otherwise breaks existing callers without a visible compatibility path.
Do not flag
Brand-new endpoints, additive optional inputs with safe defaults, new versions that leave the old contract intact, or bug fixes that restore already documented behavior.
Confidence guidance
HIGH when the before-and-after contract is directly visible. MEDIUM when compatibility depends on generated artifacts or helpers. LOW when consumer status is only partly visible.
Remediation
Keep the current-version contract backward compatible, or add a new version and a migration path instead of changing the old contract in place.
Pass example
Order:
required: [id, status]
properties:
customer_note:
type: string
nullable: true
Fail example
Order:
required: [id, status, customer_note]