A Green Schema Check Can Still Ship a Broken API Integration

hope bilgic — Thu, 10 Sep 2026 19:59:51 +0000

A lot of API failures are not caused by invalid JSON. They happen when both sides still produce syntactically valid data, but they no longer agree about what that data means.

That is the uncomfortable gap between an expected contract and an observed contract.

Five small drifts that can pass a green lint check

Consider a client that expects this synthetic response:

{
  "account_id": "acct_123",
  "status": "active",
  "items": [{"id": "item_1", "quantity": 2}]
}

A schema or style check can remain green while the integration changes in several ways:

Field type drift: quantity changes from the integer 2 to the string "2". The JSON is valid and the field still exists, but arithmetic, validation, or serialization behavior may change.
Optionality drift: items was optional for an account with no inventory, but the producer starts omitting another field that the consumer now treats as required. Conversely, a consumer may begin requiring status even though older valid responses did not include it.
Enum drift: the producer adds "paused" to a status enum while the consumer only handles "active" and "closed". Both payloads conform to their local checks; the disagreement appears at the integration boundary.
Parameter drift: a request parameter map changes from {"region": "eu"} to {"geo": "eu"}, or a parameter remains present but changes from a string identifier to a nested object. The endpoint can still return a valid response while the selection logic queries a different scope.
Selection drift: a selector that used to mean “the newest successful item” is interpreted by the other side as “the first item returned.” The field names and types are unchanged, but the selected record is different.
Downstream-receipt drift: a write returns HTTP 200 and a valid JSON receipt, but the receipt refers to a different operation identifier, omits a required correlation field, or reports a state that does not reconcile with the observed payload.

These are semantic mismatches, not merely formatting mistakes. They can survive static syntax and style linting because the linter usually validates one artifact at a time. It may not compare the expected contract, the observed payload, the parameter map, the selection rule, and the optional downstream receipt as one relationship.

A deterministic read-only reconciliation pass

A useful diagnostic does not need to mutate the system. A small read-only reconciliation pass can make the comparison explicit:

Normalize the expected contract and the observed contract into a stable representation. Keep field paths, declared types, optionality, enum values, and parameter definitions separate instead of flattening everything into a string comparison.
Compare field presence and types by path. Report additions, removals, and type changes independently. items[0].quantity: integer -> string is more actionable than a generic “schema mismatch.”
Compare optionality and enum sets. A newly required field and a newly accepted enum value have different compatibility implications, so they should produce different findings.
Reconcile the parameter map and selection rule. Confirm that the same logical inputs select the same scope and record. When selection is nondeterministic, record that limitation instead of pretending the comparison is conclusive.
If a downstream receipt is available, compare its operation and correlation fields with the expected result and the observed response. Treat a missing receipt as “not checked,” not as proof of success.
Emit deterministic findings: stable ordering, explicit paths, before/after values where safe, and a clear distinction between mismatch, missing evidence, and unchanged fields.

This pass should be read-only. It should not call a customer system, rewrite payloads, retry operations, or “repair” a contract. A safe diagnostic input can be a public example, a synthetic fixture, or genuinely sanitized data with no secrets, credentials, private production data, or personal data.

What this approach cannot prove

Reconciliation is evidence, not omniscience. A comparison cannot prove that an undocumented field is safe, that every production variant was observed, or that a selected record is correct when the selection rule itself is ambiguous. It also cannot infer business intent from a payload. Different versions may be valid for different consumers, and a receipt can be delayed or incomplete.

Those limitations are reasons to report uncertainty explicitly. They are not reasons to turn a read-only checker into an automatic migration or production repair tool. A useful result can say “type drift found,” “enum compatibility unknown,” or “receipt not supplied” without claiming more than the fixtures support.

A small premarket prototype

This investigation produced the PREMARKET PROTOTYPE Contract Drift Guard, a read-only checker focused on comparing an expected contract with an observed payload/contract, a parameter map, and an optional downstream receipt. The public validation asset is:

https://github.com/nerimanozgun75-collab/contract-drift-guard-validation

I can do one bounded free fixture check using only a public, synthetic, or genuinely sanitized non-secret fixture. Please do not provide secrets, credentials, private production data, or personal data.

I would value technical critique: which drift category is hardest to diagnose in your stack, and what evidence would make a finding useful without making the checker noisy? If your team experiences this exact problem, would it pay for a reliable read-only guard to prevent it? This is a question about problem severity. I make no claims of customers, revenue, production readiness, guaranteed accuracy, or guaranteed savings.

This article was written with AI assistance and reviewed for the technical scope and safety boundaries described here.

DEV Community: hope bilgic

A Green Schema Check Can Still Ship a Broken API Integration

Five small drifts that can pass a green lint check

A deterministic read-only reconciliation pass

What this approach cannot prove

A small premarket prototype