Event Schema Versioning: A Developer Guide

An analytics event is an API contract, even if nobody wrote it down as one.

When a developer renames item_id to product_id, changes value from a number to a formatted string, or moves campaign into a nested object, the event may still reach its destination. But every report, funnel, dashboard, export, and downstream mapping that expected the old shape now has a choice: fail silently, show a blank value, or blend incompatible periods.

Event schema versioning gives teams a controlled way to evolve payloads while preserving the meaning of data already collected. The goal is not to add a review process for every property. It is to make a breaking measurement change visible before it becomes a reporting incident.

Application code usually has a clear deployment boundary. Analytics code often does not. A frontend release, a mobile SDK update, a server worker, and a destination mapping can all emit or consume the same event on different schedules.

Consider a checkout redesign. The new code may send a valid purchase event and pass a browser-network check. Yet a revenue report can still break if one producer sends value as 129.99, another sends "129.99 USD", and an old mobile build continues to send a different item structure. The collector received events, but the business question is no longer answerable consistently.

The same problem affects non-commerce events. Changing plan from a string to an object can break an adoption segment. Replacing signup_method with method can make a funnel look as if signups disappeared. Adding an identifier to a URL or event property can also introduce a privacy risk that was not present in the previous schema.

OpenTelemetry’s telemetry schema specification describes the same producer-consumer problem: sources and consumers make assumptions about attribute names and payload shape, and they may evolve at different speeds. Product analytics has the same dependency graph. Treat event names and properties as interfaces with owners and compatibility rules.

“Compatible” needs a specific meaning for the producers and consumers in your system. Three categories are a practical place to start.

Additive changes introduce optional fields without changing existing meaning. For example, adding an optional coupon property should leave transaction_id, value, and currency untouched. This is safe only when consumers tolerate unknown properties. A strict validator or destination that rejects additional fields can still break, so test that behavior instead of assuming it.

Compatible transitions preserve an old and new representation for a defined period. A producer might send item_id while it migrates from product_id. The tracking plan should name the canonical field, mark the deprecated one, list which producers have moved, and set a retirement date. During the transition, consumers should read one canonical value or deliberately coalesce both fields. They should not select whichever happens to be present without a rule.

Breaking changes alter meaning, type, or structure. Renaming a field, turning a number into a formatted string, moving a property into a nested object, or redefining what an event name means deserves a new schema version. When the business action itself changes, a new event name may communicate the distinction more clearly.

Calling a field rename a small refactor describes the code diff, not its impact. The same change can affect a dashboard, a funnel, an export, and several destination mappings.

Write ownership beside the contract. Product or analytics engineering can own the semantic definition, the emitting team can own implementation, and report or destination owners can document what they consume. A useful contract records the event name, property types, requiredness, allowed values, example payload, version, owner, and change history.

Put the version on the event payload or in a reliable envelope that travels with it. Do not infer it from the application release number: browsers, mobile apps, and server workers can ship independently, and one application release can emit more than one event shape.

Here is an example of a versioned event contract:

{
  "event_name": "add_to_cart",
  "schema_version": 2,
  "occurred_at": "2026-10-02T09:15:00Z",
  "data": {
    "item_id": "SKU-42",
    "item_name": "Trail Jacket",
    "quantity": 1,
    "unit_price": 129.99,
    "currency": "USD"
  }
}

Here, schema_version identifies the meaning and shape of the event. It does not tell you whether delivery succeeded. Keep operational metadata—such as request IDs, retry counts, and source application versions—separate. A retry should not look like a new event schema.

Choose a versioning rule that consumers can use. A simple policy can reserve a new major version for breaking changes. If your team also uses minor versions for documented optional fields and patch versions for clarifications that do not change the payload, write down those meanings. The labels do not enforce compatibility by themselves. OpenTelemetry uses MAJOR.MINOR.PATCH for schema ordering but explicitly leaves the version numbers without further semantic meaning; each team still needs a clear contract.

JSON Schema can define reusable components and validate required fields, types, and allowed values. It is useful for complex payloads, but a schema file is only effective when the same constraints are checked in local development, continuous integration, and the server boundary where feasible.

An event test that checks “a request was sent” is necessary, but incomplete. A safe schema change proves that important consumers can still interpret the payload.

For each high-value event, validate required fields, primitive types, allowed enum values, number precision, and item-array structure. Keep a fixture for every version you still support. If a report requires numeric value, test that a formatted currency string is rejected before it reaches reporting.

Then exercise representative consumers against the old and new fixtures: a funnel, a revenue query, an export, and each important destination mapping. The outputs should stay consistent or become explicitly version-aware. This is where ambiguous migrations surface: a dashboard may expect product_id while a destination expects item_id, although both accepted the event syntactically.

For web tracking, centralize business-event emission in a small wrapper instead of scattering raw calls across components. Hardal’s Web Setup documentation distinguishes the automatically collected page_view from purchases, leads, and other business events that must be sent explicitly. A wrapper can validate the contract, attach the version, and prevent different pages from inventing slightly different names for the same action.

After deployment, inspect real payloads, not just aggregate totals. Hardal’s Events documentation describes filtering and inspecting event details, including the payload, and exporting raw data. Sample the new version, confirm its expected fields, and compare event volume and null rates with the previous version. That turns a tracking-plan assumption into observable evidence.

For high-impact changes, use a migration sequence with a clear cutover:

1. Publish the new contract and inventory the reports, funnels, exports, and destinations that consume it.
2. Update consumers to understand the old and new versions, or add an explicit transformation between them.
3. Release the new producer through a controlled rollout where possible. Keep legacy fields only when their meaning is identical.
4. Monitor arrivals by schema version, event volume, null rates, and downstream transformation results.
5. Retire the old version only after supported producers and consumers have moved, and record the cutover in reporting.

Do not assume that a metric is comparable across the cutover just because it kept the same label. Historical dashboards may need a version-aware transformation or an annotation. A migration is complete when the old and new records can be interpreted correctly—not merely when the latest client has shipped.

Add a privacy review to the change checklist. Each new custom field should have a defined purpose, retention need, and permitted destinations. Versioning makes changes visible; it is not a reason to collect extra personal data.

Pick one high-value event this week—such as purchase, generate_lead, or add_to_cart. Write down its current contract, identify the consumers, and add one old and one new fixture. Run those fixtures through the report and destination paths that depend on the event, then verify a live payload in the Events view.

A stable event schema makes every downstream measurement decision easier to trust. The version number is only one small part of that promise. The useful guarantee is that a team can explain which event shape arrived, what it means, and how reports handled it.

• Hardal: Web Setup
• Hardal: Events analytics
• OpenTelemetry: Telemetry Schemas
• JSON Schema: Structuring