Beyond schema registry compatibility checks, what does 'contract testing' add when verifying that producers and consumers of asynchronous messages actually work together, and how does it differ from just relying on the registry's compatibility mode?

## What compatibility checking can see Schema compatibility checking and contract testing solve adjacent but distinct problems, and conflating them is a common source of production incidents even in teams that have a schema registry fully wired up. Compatibility checking, as enforced by BACKWARD/FORWARD/FULL modes, is **purely structural**: it verifies that a message conforming to schema version N+1 can still be parsed by code expecting version N (or vice versa), based on field presence, types, and defaults. It has no concept of the actual runtime values inside those fields, business invariants, or how a downstream consumer's logic branches on that data. A schema change can sail through a FULL compatibility check while completely breaking a consumer's behavior: - **renaming an enum value** from `PENDING` to `IN_PROGRESS` while keeping the same underlying type is often structurally compatible (a string is still a string) but semantically catastrophic if a consumer has a switch statement matching literal `PENDING`; - similarly, **changing a numeric field's unit** from cents to dollars, or its meaning from 'total including tax' to 'subtotal excluding tax,' passes any structural check because the type didn't change, yet silently corrupts every downstream computation. ## What contract testing adds Contract testing addresses this by making the actual expectations of each consumer **explicit and executable** rather than implicit and assumed. The best-known pattern is consumer-driven contract testing (CDC), popularized by tools like Pact, though for asynchronous messaging it's often adapted rather than used off-the-shelf, since Pact's HTTP-request/response model doesn't map one-to-one onto pub/sub. In the messaging adaptation: 1. Each consumer team writes a contract, essentially a set of example messages plus assertions about the fields and values it actually reads and acts on ('I require `orderStatus` to be one of PENDING, SHIPPED, CANCELLED and I read `totalCents` as an integer representing cents'). 2. These contracts are published to a shared broker or repository. 3. The producer's CI pipeline, on every change, runs all published consumer contracts against the producer's actual message-generation code (often via a 'provider verification' step that generates real messages and checks them against every registered contract). 4. If any contract fails, meaning the producer's new code would emit something that breaks a real consumer's stated expectation, the build fails before deployment, not after a downstream team pages someone in production. ## The trade-off The trade-off versus relying solely on registry compatibility modes is **cost and coordination overhead against precision**. Registry compatibility checking is essentially free once the registry is set up: it's a structural rule evaluated automatically with no per-consumer authoring effort. Contract testing requires every consumer team to author and maintain contracts, requires a broker or shared repository to publish and discover them, and requires the producer's pipeline to be wired to fetch and verify against potentially many consumer contracts on every change, which adds both engineering effort and CI time. It also introduces a governance question: who owns keeping contracts up to date as consumer logic evolves, and what happens when a consumer's contract goes stale (still asserting on a field the consumer no longer actually reads) and starts blocking unrelated producer changes for no real reason. ## Failure modes Failure modes on the contract-testing side mirror this cost. - **Stale contracts** are the most common: a consumer team writes a contract during initial integration, then refactors and no longer cares about a field, but never removes the assertion, so the producer's pipeline keeps enforcing a constraint nobody actually needs anymore, eventually training the producer team to treat contract failures as noise to route around rather than signal to respect. - **Under-specified contracts** are the opposite failure: a consumer only asserts on the fields it happened to think of at write time, missing an implicit dependency (e.g., relying on array ordering, or on a field never being null even though the schema marks it optional), so a producer change slips through contract verification and still breaks the consumer in production, which is the exact gap contract testing was meant to close. - There's also a **coordination failure mode** specific to async messaging: unlike synchronous HTTP contract testing where a provider verification step can literally call the producer's endpoint and inspect the response, message-based contract verification often has to synthesize or mock the production code path that emits messages, and if that harness drifts from what actually runs in production (different code path, different configuration), the contract test can pass while the real system still breaks. ## Where it shows up A concrete real-world shape: a logistics company has a `shipment-events` topic feeding a billing service and a customer-notifications service. The producer team wants to change how `estimatedDeliveryDate` is computed for international shipments. The schema itself doesn't change at all (still an ISO-8601 date string), so the registry's FULL compatibility check passes trivially, but the billing service's contract, which asserts that `estimatedDeliveryDate` is always resolvable to a business day in the shipment's origin timezone for a specific SLA calculation, fails during provider verification because the new computation logic occasionally returns a weekend date for certain edge-case routes. The contract test catches a purely semantic regression that the schema registry, by design, was never able to see.