Engineering, production, governance, cost, communication · insight-1257
Retire fields in an event or response schema; never reuse a name or number with a new meaning
- Evidence type
- documented fact
- Difficulty
- medium
- Roles
- ML engineer
- Industries
- cross-industry
Summary: situation, action, reason, boundary
Situation
A team wants to repurpose an unused field in the prediction log, for example turning a legacy score column into a calibrated probability.
Action
Add a new field for the new meaning, mark the old one deprecated, keep its identifier reserved so it cannot be reused, and migrate readers before removing anything.
Reason
Serialization formats usually cannot tell which definition a stored value was written under, so identity reuse silently corrupts data.
Boundary
Protobuf, Avro or JSON event schemas, prediction logs, feature tables with long retention.
Symptom or risk
Old producers, stored data and downstream readers still interpret the field under its previous meaning, so dashboards and retraining sets mix two definitions with no error.
Exceptions
A private, short-lived table that is fully rebuilt on every deploy can be changed in place.
Trade-offs
Reserved and deprecated fields accumulate and add clutter to the schema.
Pitfalls
Changing a type that looks compatible, such as int64 to int32, and truncating values that no longer fit.
Example
Hypothetical: column score meant a rank in 2023 and a probability in 2024; a join across both years gives a mean of 0.5 that means nothing.
Lessons and concepts
Claims and their sources
The protobuf guide states that field numbers should never be reused and recommends reserving the numbers and names of deleted fields so the compiler rejects reuse.