Engineering notes

Schema versioning for ingest

Batches carry the schema version they were written against. Staging validates; it does not coerce.

Accepted · shipped 2026.8.2 · owner: rk

Decision

Every inbound batch declares the schema version it was produced against. Ingest validates against that version and rejects on mismatch. It does not attempt to migrate a batch forward.

Why not coerce

Coercion is a transform that returns a plausible result rather than an error. A field that moved, or changed units, or narrowed its range comes through looking fine and is wrong downstream, where it is attributed to whatever read it rather than to the coercion. Rejecting is louder and the loudness is the point.

The cost is real: a producer pinned to an old version stops working at the moment we ship a new one, and that has already happened once. The answer is a deprecation window, not silent acceptance.

Consequences