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.
Contract, not documentation
A data contract names every field of an event, its type, allowed values, semantics, and the compatibility rules for changing it. The defining feature is enforcement: the contract is expressed as a schema that CI checks against, or that the collection boundary validates at runtime, so violations fail a build or a request rather than slipping into production. It also names the owner and consumers so changes route to the right people.
Documentation describes intent; a contract makes intent executable.
- Fields, types, values, semantics, compatibility rules
- Enforced in CI or at the boundary, not just written
- Names owner and consumers for change routing
How it protects analytics
With a contract, a producer who renames a field or changes its type triggers a check that flags the break before release, giving consumers time to adapt or the change time to be reconsidered. Backward-compatible changes pass; breaking ones require a version bump and coordination. This converts silent, weeks-later dashboard failures into loud, pre-merge ones.
Contracts, tracking-plan governance, and schema enforcement are the same idea at different layers: the plan is the agreement, the contract binds producer and consumer, enforcement makes it bite.
How it appears in analytics and logs
A dashboard that breaks the day after an unrelated deploy usually means a producer changed an event with no contract to catch it.
Diagnostic use case
Prevent upstream code changes from silently breaking dashboards by binding event producers and consumers to an enforced contract.
What WebmasterID can help detect
WebmasterID's explicit event schema is a natural place to anchor a contract that downstream consumers can rely on.
Common mistakes
- Writing a contract but not enforcing it in CI or at runtime.
- Allowing breaking changes without a version bump.
- Leaving consumers unnamed so changes surprise them.
Privacy and accuracy notes
A contract can declare which fields carry personal data and how they must be handled. This page is educational, not legal advice.
Related pages
- 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.
- Event schema enforcement
A schema only protects data quality if something enforces it. Enforcement validates each event against the declared schema and decides what happens on failure — reject, drop a field, or quarantine. It can run in CI against instrumentation, in the SDK, or at the collection boundary. This page explains where to enforce an event schema and the trade-offs of each point.
- 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.
- Events documentation
Anchor a contract on an explicit event schema.
Sources and verification notes
- Google — [GA4] Events (recommended structure)Conventions a contract can formalize and enforce.
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.