Contract Drift

1. Core problem: the contract file, implementation, and consumer are different things

In Contract Drift, a producer, consumer, and OpenAPI file can each be internally consistent while disagreeing on an operation, required field, status code, or semantic rule. This lesson separates three evidence layers: the declared contract, observed implementation behavior, and consumer assumptions/dependencies. Without all three, declaring a breaking change can be premature.

2. OpenAPI describes an interface; it is not runtime proof

OpenAPI 3.2 defines a language-agnostic interface description for HTTP APIs so humans and tools can understand service capabilities. The current published patch is 3.2.1. [OAS-321] The presence of an OpenAPI Description alone does not establish that a deployment conforms to it; that distinction is central to drift diagnosis.

3. Schema validation does not catch every specification violation

The official OpenAPI schema page explicitly notes that schemas can catch many errors but are not guaranteed to catch every specification violation; if schema and specification text disagree, the specification text is authoritative. [OAS-SCHEMA] Therefore, “the validator is green” is not equivalent to “the contract and runtime are fully conformant.”

4. Name the exact drift element

Instead of saying “the API broke,” identify the changed element: path/operation, request parameter, required property, response field, enum domain, status code, or semantic meaning. The element boundary determines which consumers can actually be impacted.

5. An additive change is not automatically breaking

Adding an optional response property can be additive and non-breaking for a consumer that ignores unknown fields. A strict consumer may behave differently. Compatibility therefore cannot be derived from the file diff alone.

6. Optional-to-required needs consumer evidence

If a property that an older consumer omitted becomes required, old requests may fail. To call it breaking, record the declared difference and show that the observed consumer actually sends the old shape or depends on optionality. Without consumer evidence, you have a candidate break, not proven impact.

7. Status codes are part of behavioral contract

A status-code change can leave the body schema unchanged while breaking retry, fallback, or error mapping. In one fixture, the consumer retries only on 429, while the new producer emits 400 for the same bounded condition. That is semantic/behavioral drift, not merely a schema mismatch.

8. Enum narrowing can be breaking

Adding and removing enum values are not equivalent. If the consumer actually sends or expects a removed value, narrowing can be breaking. If the removed value is never used in the observed consumer path, impact must be derived from evidence rather than worst-case imagination.

9. Stale docs are not the same as a contract-version change

The declared vA and vB files can be identical while the synthetic implementation response differs. That is implementation-versus-declared-contract divergence, not necessarily a change between two contract versions. Repair may involve rollback, implementation correction, or documentation update; first identify which authority is intended.

10. Build compatibility from three inputs

For each element, combine declared difference, observed behavior, and consumer assumption/dependency. The result may be ADDITIVE_COMPATIBLE, BREAKING_FOR_OBSERVED_CONSUMER, IMPLEMENTATION_DIVERGENT, or UNKNOWN. This lesson does not define a universal compatibility policy; classification is bounded to the fixture and consumer profile.

11. Containment is not repair

Containment may temporarily preserve the old route, freeze a feature, enable a compatibility shim, or stop rollout. Repair means contract, implementation, and consumer return to an agreed state: backward-compatible producer, coordinated migration, versioned endpoint, or corrected docs/runtime. Do not present containment as proof of closure.

12. Counterexample: additive field ignored by the consumer

One fixture adds a new optional response property, while the consumer profile explicitly ignores unknown fields. A learner who labels every diff as breaking fails this case. The difference is real, but observed consumer impact is not; classification stays additive/non-breaking.

13. Transfer: REST to webhook callback

The transfer no longer centers on the primary REST success response. Callback payload and acknowledgement behavior become the contract boundary. A newly required callback field that the older receiver cannot provide can be breaking. Rebuild compatibility from webhook evidence rather than copying REST rules.

14. Lab: eight fixtures and 64 assertions

The lab is fully local, deterministic, and synthetic. Eight cases cover a healthy baseline, required-input break, ignored additive field, status-semantic break, stale-doc/runtime divergence, enum narrowing, incomplete evidence, and webhook transfer. The hidden evaluator checks eight dimensions per case for 64 assertions total.

15. Exit checklist and claim boundary

To exit, independently record declared contract, observed behavior, and consumer assumption; name the exact drift element; derive additive/breaking state from consumer evidence; avoid treating a green schema validator as runtime proof; separate stale docs from version drift; distinguish containment from repair; preserve OPEN when evidence is insufficient; and solve the webhook transfer from changed evidence. The synthetic fixture makes no conformity claim about a real API.