Schema evolution for events
Event schemas must change as products evolve, but a careless change breaks every consumer reading the old shape. Schema evolution is the discipline of changing shape compatibly: additive changes that old readers ignore, backward compatibility so new code reads old data, forward compatibility so old code tolerates new data. This page explains compatible schema evolution for analytics events.
Kinds of compatibility
A change is backward-compatible if new processing code can still read data written under the old schema; forward-compatible if old code can tolerate data written under the new schema (typically by ignoring unknown fields). Additive changes — a new optional field — are usually both. Removing or renaming a field, or changing its type, breaks readers and is not compatible.
Aiming for additive, optional changes keeps producers and consumers decoupled so they upgrade on their own schedules.
- Backward: new code reads old data
- Forward: old code tolerates new data
- Additive optional fields are usually both
Evolving safely
Prefer adding optional fields over changing existing ones; when a rename is truly needed, add the new field, dual-write both, migrate consumers, then retire the old field. Never silently change a field's type or meaning — that corrupts historical comparisons. Encode the rules in a contract and announce the change with a version so consumers know its impact.
Schema evolution is how shape changes; versioning announces the change; contracts and enforcement make the rules stick.
How it appears in analytics and logs
Consumers breaking after a schema change mean the change was not compatible — a rename, removal, or type change rather than an addition.
Diagnostic use case
Change an event schema without breaking existing consumers by preferring additive, compatible changes over renames and type changes.
What WebmasterID can help detect
WebmasterID's explicit event shape makes compatible evolution tractable, since the current schema is known and versionable.
Common mistakes
- Renaming or removing a field instead of adding a new one.
- Changing a field's type or meaning in place.
- Evolving the schema with no version or contract.
Privacy and accuracy notes
Evolving a schema should preserve which fields carry personal data and how. This page is educational, not legal advice.
Related pages
- Semantic versioning for events
Semantic versioning gives event schemas a shared vocabulary for change: a major bump means a breaking change, minor means a backward-compatible addition, patch means a fix that does not alter shape. Tagging events and their schemas this way tells consumers whether an upgrade is safe to ignore or requires work. This page maps semver to event-schema changes and how it coordinates producers and consumers.
- Data contracts for events
A data contract is a versioned, machine-checkable agreement between the team that emits an event and the teams that consume it, fixing field names, types, semantics, and compatibility rules. Unlike a wiki page, it is enforced in CI or at the boundary, so a producer cannot ship a breaking change unnoticed. This page explains data contracts and how they protect analytics from upstream drift.
- Schema drift in event data
Schema drift is the gradual, uncoordinated change of event names, parameter keys, value types, or enumerations in an analytics stream. A renamed event, a parameter that switches from string to number, or a new value an enum did not expect can break joins, drop rows from filters, or quietly corrupt aggregates. This page explains how drift arises in event pipelines and how to guard against it.
- Events documentation
Evolve an explicit event schema compatibly.
Sources and verification notes
Last reviewed 2026-06-24. Facts are checked against primary/official sources where available; uncertain specifics are marked “Data not yet verified” rather than guessed.