martech cookbookSearch recipes & patternsSign up
Recipe·Updated 23 September 2026

Event schema standardization

Define the events once, version them, and enforce the shape at write time, so analytics, activation, and reporting work against one data contract rather than negotiated reconciliations

01Problem

Most stacks accumulate event taxonomies the way an attic accumulates boxes: by addition, never by curation. The web team named the signup event account_created, the iOS team named it user_signup, the warehouse pipeline renamed it signed_up, and the email platform reads a fourth name. Each system works fine on its own, and the cost shows up at the joins, where analytics has to maintain a lookup table that maps the same event to four names and downstream reporting either misses a slice or double-counts. The lookup table grows, the people who knew which name meant which thing leave, and the events that drive activation and reporting become a system nobody fully understands.

The fix is to define the events once as a versioned schema (an event name, the properties it carries, their types, their required-ness, the consent context that applies) and enforce conformance at the write boundary, so an event that does not match the schema gets caught at the collector rather than at week six of an analytics investigation. The recipe is medium-low readiness because the technical work is mature and the patterns are well-documented; the cost is the organizational discipline of agreeing what the schema is and holding the line when product, marketing, and analytics each want a small exception.

This recipe builds the schema as a contract and the enforcement that keeps the contract honest as the stack changes.

02Outcome

A unified event schema that analytics, activation, and reporting all read from, with conformance enforcement at the write boundary and versioning that lets downstream consumers know which contract they are receiving events under. The metric is schema conformance rate: the percentage of events that arrive in the schema's shape on first capture, against a baseline measured before the schema was enforced. The value shows up in the time saved at every join (no more lookup tables mapping account_created to user_signup), in the analytics reports that stop disagreeing because they read the same definitions, and in the activation paths that no longer break when a property silently changes name.

The second outcome is the versioning discipline. When the schema needs to evolve (a new property, a renamed event, a type change), the version increment is explicit and the downstream consumers know what changed, rather than discovering it because their report broke.

03Ingredients
  • Event schema definition
  • Event schema version
  • Event validation layer
  • Customer identifier
  • Consent state flag
04Equipment

A schema registry that holds the contract (Confluent Schema Registry, AWS Glue Schema Registry, a Segment Protocols-style workflow, or a homegrown JSON Schema repo with CI enforcement) and a validation layer at every write boundary (server-side collection endpoint, client-side SDK with build-time schema checks, or both). Composable stacks suit this because the schema and the consumers can be co-located in the warehouse and tooling and the contract becomes a first-class artefact. The capability that decides whether enforcement holds is the validation discipline: a schema that defines the contract but allows non-conforming events through (warning logs only, no rejection) is a schema in name only, and the same drift problem returns within months.

05Staff
  • Data engineering
    CriticalThe schema definition, the validation layer, the versioning discipline
  • Analytics
    CriticalThe schema review for analytics readability, the downstream consumer perspective
  • Marketing ops
    CriticalThe activation-side consumer perspective, the events that activation depends on actually firing
  • Product
    SupportingThe product events the schema needs to cover and the changes that trigger schema updates

Data engineering owns the schema definition, the validation layer, and the versioning workflow that holds the contract stable as events change. Analytics owns the consumer-side review: the schema has to read in the shape analytics needs, with the properties that matter for the questions analytics is asked to answer, or the contract solves a data-engineering problem and creates an analytics one. Marketing ops owns the activation-side view, because the events activation depends on are the ones whose absence breaks campaigns, and a schema that does not cover them creates the same fragmentation in the activation layer. Product is involved at the change moments, when a new product event needs adding or an existing one is changing meaning. The recipe ships in weeks where collection is already in one place; longer where event capture lives across multiple uncoordinated systems, because the unification work is more substantial than the schema work. The hard part is rarely the schema; it is convincing the systems that emit events to conform to it.

06Technique
INPUTSPROCESSACTIVATIONEvent collectorsCustomeridentifierConsent state flagEvent schemadefinitionEvent validationlayerSchema versioningValidated eventsSignal qualitymonitorEvent schemaversionAnalyticsActivationReporting

Work in this order. Define the contract, enforce it at write, monitor conformance, version every change.

  1. Pick the definition format: JSON Schema, Protobuf or Avro.
  2. Declare consent context inside the payload, so each event states what it may be used for and consumers stop looking it up or assuming it.
  3. Validate at the write boundary, and choose reject or quarantine. Warn-only becomes the de facto standard within a quarter, because non-conforming events still work.
  4. Run a schema registry with CI enforcement.
  5. Emit one shape from client and server.
  6. Version every change with a deprecation window. A schema that can never change gets routed around, which is how the previous taxonomy fell apart.
  7. Monitor conformance and volume in production, so a deploy that breaks a slice of events alerts instead of showing up three weeks later as a drop in a report.
  8. Migrate the existing four-named taxonomy onto the contract.

Server-side event collection with client-side fallback covers steps 3 and 5, signal quality monitoring step 7, and audit trail generation at the decision point steps 4 and 6.

07Gotcha
Failure 01

The first failure is the schema that nobody enforces. A team that defines a schema, documents it well, and lets events through that do not match it is solving the problem on paper while the actual data drifts as it always did. The enforcement at the write boundary is what makes the schema a contract rather than a document, and a softer treatment (warn rather than reject) becomes the de facto standard within a quarter because non-conforming events still work.

Failure 02

The second is the schema that cannot evolve. A contract too strict to accommodate new product events or renamed properties creates pressure to bypass it (an exception here, a non-versioned change there), which is how the previous taxonomy fell apart in the first place. Schema evolution needs a workflow: the version increments, the consumers are notified, the old version is supported for a deprecation window, and the discipline holds. A schema that is never allowed to change is a schema that gets routed around.

Failure 03

The third is the schema that does not include consent. If consent state is treated as a separate concern from the event payload, downstream consumers either look it up themselves (and get it wrong) or assume the events are consented (and create exposure). Declaring consent context as part of the schema makes the contract complete: an event arrives with its own statement of what it is allowed to be used for, and the consumers act on that rather than guess.

WorkshopFor your stack·The questions this recipe raises

Eight questions this recipe raises for your stack.

The Workshop works out with your team which of these matter for your stack right now, and what to do first: a 90-minute session with the people who own the decision.

  1. 01Schema definition format: JSON Schema, Protobuf, or AvroWhich machine-readable contract fits your stack, and what each one costs to maintain.
  2. 02Validation at the write boundary: reject versus quarantineThe decision that makes the schema a contract rather than a document.
  3. 03Schema registry and CI enforcementWhere the contract lives and how it gets checked before events flow.
  4. 04Client and server emitting one shapeHolding web, iOS, and the pipeline to the same event name and properties.
  5. 05Versioning workflow and deprecation windowsLetting the schema evolve without the bypasses that broke the last taxonomy.
  6. 06Consent context declared inside the payloadMaking each event carry what it is allowed to be used for, not a separate lookup.
  7. 07Conformance and volume monitoring in productionSurfacing a breaking deploy as an alert, not a report read three weeks later.
  8. 08Migrating the existing four-named taxonomyRetiring the lookup table without dropping the events downstream still depends on.

If your stack has the same event under four names and reports keep disagreeing, the Workshop is where we build the schema.

The event taxonomy that analytics, activation, and reporting all read, the validation at the write boundary that keeps the contract honest, the versioning discipline that lets the schema evolve without breaking consumers, and the consent context declared as part of the event rather than a separate lookup: those are the decisions that turn an accumulated event taxonomy into a contract the stack actually conforms to.

take this to the martech workshop→

Did this recipe match your situation?Anonymous response. Sign up to leave a longer note tied to your account.

Related recipes