Contract Drift
Contract drift is the silent divergence between what a provider actually serves and what consumers assume — caught only by consumer-driven contract tests and schemas, not by provider self-tests.
Definition
Contract drift occurs when a service evolves its interface without a coordinated change: fields become optional, error codes change, types narrow. Provider tests still pass because the provider verifies only itself; consumers break at runtime. Consumer-driven contracts record each consumer expectations and verify the provider against them on every change.
Context and scope
Managed with Pact-style CDC pipelines, OpenAPI schema diff gates, and wiremock stubs replayed against provider deploys. Central to microservice integration safety.
Common misconceptions
- Provider tests passing means consumers are safe — provider tests verify the provider behavior; consumers depend on subsets the provider may not know about
- OpenAPI documentation prevents drift — a static spec can drift from the implementation; verification requires diffing the live behavior against the schema in CI
- Backward compatibility removes drift — consumers pin old behavior; new consumers adopt new shapes, and both live happily only with contract tests spanning them
Anti-patterns
- Renaming response fields in a minor version and letting three downstream services discover it in production
- Publishing specs that are never diffed against real responses and drifting inside the documentation itself
- Breaking consumers on purpose with coordinated freezes instead of additive evolution and canary verification
Related concepts
Related examples
Authoritative source
What it is
Between two services sits an unwritten agreement. Every deploy rewrites it slightly. Drift is the accumulation of rewrites nobody announced — the production integration test environment.
How it works
Consumer tests generate pact files encoding required interactions: paths, fields, types, status codes. The provider pipeline replays those pacts against the real service; any mismatch fails the provider build. Schema-based variants generate a live spec from the implementation and diff it against the committed contract, rejecting breaking changes.
When to invest
Multi-team service ecosystems, public APIs with external consumers, and event schemas with multiple subscribers. Broadcast the contract change, let consumers re-verify, and only then deploy.
Pitfalls
Pacts verify the recorded subset, not the full surface — new consumer needs require new pact entries. Event contracts need schema registries with compatibility modes rather than HTTP-shaped tools. Team discipline decides: a skipped verification pipeline is drift with extra steps.