← Home

Schema Validation Does Not Prove a Migration Is Safe

Sep 10, 2026

Changing status: "active" into status: "enabled" can be schema-valid on both sides of a migration. It can also quietly stop every old consumer from granting access.

Schemas answer a narrow and valuable question: is this document shaped like the declared contract? They do not establish that a new field has the same business meaning, that a default preserves old behavior, or that a consumer's branch logic reaches the same outcome.

Compatibility is a behavioral claim

Suppose a producer replaces a missing boolean with an explicit default:

// old record
{ "send_receipts": false }

// new producer's intended default
{ "send_receipts": true }

Both records may validate. The migration is still breaking if consumers previously interpreted absence or false as an opt-out. The question is not “does the JSON parse?” It is “does a record produced before and after the change produce the intended decision?”

Keep a fixture corpus of historic payloads, including records with omitted fields, deprecated enum values, and surprising but accepted combinations. Run the new reader against them. For a stateful migration, use a copy of the oldest supported database and execute the actual migration chain; a schema created from scratch misses ordering and backfill defects.

Make ambiguity explicit at the boundary

If a new interpretation needs a new policy, name it. Do not overload a familiar field and expect every downstream system to discover the nuance on its own. Versioning can help, but a version number is not compatibility by itself; it only makes the difference detectable.

References

Final take

Passing a schema is evidence that data has a permitted shape. A safe migration needs evidence that the system still makes the right decisions from that shape.

Changelog