Practical framework / 5 MIN READ
Change the event contract without breaking the evidence chain
Plan compatibility, dual-running and cutover before deploying a new schema.
AI-assisted research and analysis for the SNS Creative Fieldbook
Sources checked 2026-11-06
A revised event can improve measurement while disrupting reports that expect the old structure. Safe migration preserves meaning, distinguishes old and new versions and prevents an overlap period from counting one action twice.
What you will leave with: Create a schema migration plan with compatibility tests, an authoritative counting rule and rollback conditions.
Use this when
- An event field changes type or meaning.
- A new SDK or analytics model must coexist with older clients.
This lesson concerns evolution of an established event contract, not writing the first tracking plan.
Classify the actual change
List changed fields, types, requiredness, units and business meaning. Adding an optional field differs from redefining revenue or making a previously optional identifier mandatory. A schema can remain technically valid while its meaning changes enough to break comparison.
Snowplow documents versioned schemas and different handling of breaking and non-breaking changes across warehouses. Use the versioning rules of the actual system, and review semantic compatibility separately. Do not overwrite a published meaning simply because a validator accepts the new payload.
Map producers and consumers
Identify every producer that can continue sending the old version, including installed apps that update slowly. Map reports, models, alerts and external destinations that consume the event. Assign owners and a compatibility strategy for each rather than assuming one deployment updates the entire chain.
Decide whether consumers can normalize both versions into a shared representation. Preserve the original version and source evidence. If the business definition truly changed, maintain separate measures or a documented bridge instead of pretending the new field is a drop-in replacement for historical data.
Control the overlap period
If old and new instrumentation run together, define which record is authoritative for each action. Use supported stable identities or a controlled partition of traffic to avoid duplicate counting. A dual-run intended for validation should not silently send duplicate conversion or customer-message triggers downstream.
Test mixed-version fixtures, missing optional fields, late old-version events and failed new-version validation. Reconcile counts and values under both definitions. Keep unsupported records in a visible failure route rather than coercing them into misleading defaults merely to maintain a smooth dashboard.
Cut over with evidence and a rollback
Set acceptance criteria for data quality, downstream compatibility and reporting differences. Record the cutover timestamp and which versions remain supported. A rollback should specify what happens to new-version data already collected, not merely reinstall old code.
After the authorized release, monitor old-version volume and critical report checks. Retire compatibility code only when the remaining producer population and retention requirements allow it. Annotate any meaningful series break and preserve the migration decision, so a future analyst can distinguish business change from instrumentation change.
Make the reasoning concrete.
A hypothetical purchase schema changes amount from dollars to integer cents. One producer sends 50 under the old version and another sends 5000 under the new version for the same $50 purchase. A consumer that ignores version interprets the latter as $5,000.
Reuse the field silently
Opening: Keep one amount field without version-aware conversion.
Hypothesis: The schema appears simple.
Risk: Values differ by a factor of 100 and overlap may double count.
Normalize by explicit version
Opening: Convert each supported version to the agreed unit and count the action once.
Hypothesis: Reports preserve the intended $50 meaning.
Risk: Late old clients and rollback behavior still need tests.
Require mixed-version acceptance tests and an authoritative counting rule before cutover. Label any real definition change rather than normalizing away a substantive difference.
Take the questions into your next brief.
Use these prompts in your own notes. Nothing is submitted from this page.
Change
Which technical and semantic elements differ?
Dependencies
Which producers and consumers must coexist?
Overlap
How is one action counted once during validation?
Tests
Which mixed, late and invalid versions must pass?
Cutover
What evidence permits release and what triggers rollback?
Watch for the wrong conclusion.
- Changing units without changing the contract.
- Assuming all clients update together.
- Dual-sending live conversions without a counting rule.
- Rolling back code without a plan for collected new-version data.
Your next action
Draft a schema migration matrix covering producers, consumers, overlap counting and one mixed-version value fixture.
Sources & scope
Frameworks, worksheets and hypothetical examples are original editorial synthesis. Linked primary sources support only the stated concepts. Source checking is not an independent audit of effectiveness. No named human author or reviewer is claimed.
- Snowplow: Versioning, patching, and marking schemas as superseded →Primary technical documentation · Supports: Explains schema versions, backward compatibility and warehouse-specific handling of breaking changes. The business migration and double-count prevention plan is original editorial analysis.