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.
Mapping semver to events
Semantic versioning uses MAJOR.MINOR.PATCH. For an event schema, a MAJOR bump marks a breaking change — removing or renaming a field, changing a type, or altering meaning — that consumers must handle. A MINOR bump marks a backward-compatible addition, such as a new optional parameter. A PATCH marks a fix that does not change the contract, like a corrected description.
The number alone tells a consumer whether ignoring the change is safe.
- MAJOR: breaking — removed/renamed field, type change
- MINOR: additive — new optional parameter
- PATCH: non-shape fix
Coordinating change
When a breaking change is unavoidable, a major version lets old and new schemas coexist during migration: consumers move on their own schedule, and you retire the old version once usage drains. Additive minor changes can roll out freely because they do not break anyone. Pair versioning with a contract so the version is enforced, not just declared.
Semver complements schema evolution: evolution is how the shape changes safely; the version is how you announce which kind of change it was.
How it appears in analytics and logs
Consumers blindsided by an event change usually lack a version signal that would have marked the change breaking versus additive.
Diagnostic use case
Communicate the impact of an event-schema change at a glance by versioning it with semver so consumers know whether action is required.
What WebmasterID can help detect
WebmasterID's explicit event definitions can carry a version so downstream consumers reason about compatibility deliberately.
Common mistakes
- Treating a breaking change as if it were additive.
- Bumping versions but never retiring old ones.
- Versioning in name only, with no enforcement.
Privacy and accuracy notes
Versioning is metadata about schema shape and touches no visitor identity. This page is educational, not legal advice.
Related pages
- 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.
- 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.
- Tracking plan governance
A tracking plan documents every event, its parameters, types, and meaning, so collection stays consistent as teams ship. Governance is the process around it: who can add events, how changes are reviewed, and how naming is enforced. Without it, the same action gets logged three ways and reports quietly diverge. This page describes how tracking-plan governance keeps an analytics schema trustworthy.
- Events documentation
Carry a version on each event definition.
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.