Event Schema

Origin & evolution

The discipline grew up around the tracking plan, the document that lists every event and property an organisation collects. Segment framed the tracking plan as a contract between product, engineering, marketing, and analytics teams, so everyone agrees on what gets collected and how. The event schema is the per-event unit of that contract.

The first wave of practice was descriptive: write down what you already track. The second wave made the schema enforceable. Segment Protocols validates incoming events against the plan and blocks non-conforming data before it reaches downstream tools. Avo pushed governance earlier still, into design time, where an event and its properties are specified and reviewed before a line of code ships, then published into schema registries and validation tools like Segment Protocols, RudderStack, or Snowplow.

Governance matured alongside scale. Avo's federated model lets a parent organisation keep a core set of events in sync across subsidiaries while each team keeps its own naming conventions for the rest. The field settled on a clear principle: the schema is the artefact you govern, and the metric🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference → is downstream of it.

How it works in practice

A checkout team defines order_completed with four properties: order_id (string, required), revenue (number, required), currency (string, required), coupon_code (string, optional). The schema lives in the tracking plan, reviewed before release🚢ReleaseProduct SpecificationA shipped version of the productView reference →.

Three months later a mobile engineer ships the same event but sends revenue as a formatted string, "£42.00". The revenue chart flatlines, because the warehouse silently drops the rows it cannot cast to a number. With a validating layer in place, the malformed event is rejected at ingestion and the engineer sees the error in CI, before the data is polluted. The fix takes ten minutes. Without the schema as a gate, the same defect would have taken a week of someone wondering why revenue dropped 30%.

Kleppmann draws the same fault line at the systems level, distinguishing schema-on-write (the store rejects data that does not conform at ingestion) from schema-on-read (structure is only interpreted at query time, so malformed data enters silently and errors surface later). His analysis of schema evolution — how producers and consumers handle added, removed, or retyped fields across deployments📤DeploymentEngineeringA deployment eventView reference → — shows that forward and backward compatibility must be explicit contracts, not assumptions🤔AssumptionStrategyA belief taken as true that underpins a strategyView reference →; without them, a type change in one service quietly corrupts consumers that were never told.

Event schema vs. its neighbours

• Metric is computed from events; the schema is the raw input. A metric like weekly active users depends on a clean session_started schema underneath it. Change the schema's definition of a session and the metric shifts without anyone editing the metric.
• Funnel step🔽Funnel StepGrowthA stage within a conversion funnelView reference → references an event schema to mark a stage in a conversion path. The funnel⬇️FunnelGrowthA conversion funnel tracking user progressionView reference → borrows the event's name and filters; it does not own the event's structure. One schema can feed many funnels.
• Data source🛢️Data SourceData & AnalyticsA data source or integrationView reference → is where the events originate (a web SDK, a server, a mobile app). The schema is provider-agnostic, so the same order_completed shape can be emitted by three sources and still resolve to one definition.

A note on the common failure: "track everything" produces thousands of ad-hoc events with no shared schema, and the volume looks like rigour while delivering none. A small set of governed schemas is verifiable in a way a sprawl of unverified ones is not.

In the graph

In the Unified Product Graph, an event schema sits in the data and analytics region as the structured contract for tracked behaviour. A funnel_step_tracks_event_schemaFunnel SteptracksEvent Schemacross-domain edge ties each conversion stage to the event that proves it; product_tracks_via_event_schemaProducttracks viaEvent Schemahierarchy records which products emit it; and data_source_emits_event_schemaData SourceemitsEvent Schemahierarchy names the origin. Modelling the schema as a first-class node, with the funnel and the source hanging off it, makes the lineage queryable: when a metric drifts, you can walk back along these edges to the schema that defines it and find the break.