Detect schema drift in a third-party integration

A provider can add fields, change a number to a string or remove a unit. If the adapter accepts drift silently, model context and downstream calculations can change without an obvious error.

Detect an authored change

The MCP contract lab compares two responses with an expected schema.

from mcp_cases import schema_drift_case

result = schema_drift_case()
assert result["drift_indices"] == [1]
assert result["rows"][1]["extra"] == ["currency"]
assert result["rows"][1]["wrong_type"] == ["value"]
assert result["silent_accept"] is False

The second response changes numeric value to string and adds currency. No third-party service runs.

Combine static and runtime checks

Pin/validate OpenAPI, JSON Schema or typed models. Reject or quarantine incompatible responses. Monitor distributions and semantic fields such as units because syntactic compatibility can still hide meaning changes.

Run sandbox/live compatibility tests separately from offline fixtures. Record provider/API version and observed response digest. Use additive-field policy deliberately; strict clients may need reviewed schema updates.

Protect downstream state

Invalid results never enter model context or durable agent state. Return a stable integration-drift code, alert the owner and preserve a sanitized sample under policy.

The Generative & Agentic AI course connects drift detection to versioning, contract tests and rollback.

Exercise

Create ten response mutations across type, unit, enum and field changes. Prove the adapter catches every breaking/semantic drift before downstream use.

Continue learning

This article is part of the MCP and integration contracts sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Agent-to-agent handoffs with explicit task ownership.
• Continue with Document an MCP server for a security reviewer.

Reference: JSON Schema.