API Testing / Editorial solution guide

Diagnose a consumer break despite schema success

Trace shape, semantic units, enum expectations, and artifact versions before accepting an alleged compatible change.

About 3 min readContent reviewed

Read-only knowledge base · No public comments

Recognize the symptoms

A provider response validates against the selected schema, but a supported consumer miscalculates a timeout, rejects an enum, or cannot render the result. The provider may report that the change was additive. Preserve the old and proposed contract revisions, the affected consumer version, and a minimal synthetic request/response pair.

Understand the likely causes

  • Possible causes include unchanged types with changed units, a new enum value, a consumer that rejects unknown properties, missing fields, an incorrect schema dialect, or evidence from an older interaction artifact. A schema pass proves only the constraints actually executed by that validator; it does not establish every consumer assumption or business meaning.

Locate the first incompatible interpretation

Reproduce the consumer’s actual request-building and response-reading code with a local injected transport and a synthetic payload. Determine whether the failure occurs during decoding, structural validation, unit conversion, enum dispatch, or later business logic. Keep those stages separate. A manually constructed expected object that bypasses the consumer parser can hide the defect. Record supported versions and whether the provider actually verified the same interaction artifact. This guide does not contact a provider, install a contract tool, or publish a broker artifact.

Check meaning that the type cannot express alone

The example keeps an integer timeout field while changing the interpreted unit. A type-only check accepts both payloads, yet the old consumer’s multiplication produces a thousand-fold difference. The calculation is local and deliberately synthetic. Inspect the documented unit, timezone, currency, ordering, and empty-result meaning for similar shape-preserving changes. Also compare enum domains and required presence. Do not rewrite the consumer expectation to the new observation until the support promise and migration decision have been reviewed by the responsible owner.

python A shape-preserving unit mismatch 
old_payload = {"timeout": 2}
changed_payload = {"timeout": 2000}
assert type(old_payload["timeout"]) is int
assert type(changed_payload["timeout"]) is int
def old_consumer_ms(payload):
    return payload["timeout"] * 1000
assert old_consumer_ms(old_payload) == 2000
assert old_consumer_ms(changed_payload) == 2000000
print("type agreement does not preserve timeout meaning")
Expected output
type agreement does not preserve timeout meaning

This complete program demonstrates one old consumer assumption about seconds. It is not a real timeout setting or schema-engine execution. The changed payload is incompatible only under the stated old contract and supported consumer assumption.

Choose a contract repair instead of a broad exception

Restore the original meaning, introduce a clearly named new field with a migration, or version the breaking behavior according to the approved support policy. If the consumer is wrong under the existing contract, repair its adapter and retain a regression that exercises its real transformation. Use precise matchers for the fields the consumer depends on without freezing unrelated provider details. Keep schema validation and consumer interaction verification because they protect different promises. Avoid disabling the entire schema check or accepting every enum merely to make one payload pass.

Verify the fix

Verify old supported requests and responses, the repaired consumer transformation, and the proposed provider behavior against the exact versioned interaction. Confirm units and error handling with concrete expected values. Record whether verification was local, document-only, or performed by an actual approved provider verifier. Transport, deployment configuration, and persistence remain separate evidence boundaries.

Keep it from recurring

  • Review semantic changes alongside schema diffs, pin dialect and tool behavior, track supported consumer versions, and retain meaningful error interactions. Require compatibility evidence for the artifacts actually considered for release. An additive shape change is a review input, not a universal guarantee that every consumer remains compatible.

Official references