TapCub is live — analytics, insights and live chat, free on one platform
Glossary

Event Schema: Definition, Example and Validation

An event schema is the written contract for one analytics event: name, properties, types and required flags, agreed before data is sent and checked as it arrives. Field table, JSON example, and a recomputable completeness calculation.

Lucas Hayes Reviewed by Chen Yu Also called event specification Last updated Nov 16, 2026 Glossary

Quick answer

An event schema is the written contract for one analytics event: its name, the properties it carries, each property's type, and which ones are required — agreed before any data is sent and checked as data arrives.

Formula: Required-property completeness = conforming arrivals ÷ total arrivals (per event, per time window)

What is an event schema?

An event schema is the written contract for one analytics event: the event's name, the properties it carries, each property's data type, and which properties are required. The contract is agreed before any data is sent, and every arriving event is checked against it. If a checkout event is supposed to carry order_id (string, required) and value (number, required), an arrival without order_id — or with value sent as "40.00" — is a broken contract, not just a messy row.

The word "schema" comes from database design, where a schema fixes the columns and types of a table before rows are inserted. Analytics events arrive as flexible JSON payloads, so nothing stops a developer from adding, renaming or retyping a property at any time. The event schema is what restores the database-style guarantee: a fixed, reviewable structure that both the people sending data and the people querying it can rely on. Amplitude's tracking-plan documentation describes the same idea — events and properties are defined, with descriptions, types, rules and required flags, before instrumentation begins.

What goes in an event schema?

At minimum, a schema needs the event name, when the event fires, and a property list with types and required flags. A schema that can drive validation and ownership needs a few more fields:

FieldWhat it recordsExample
Event nameThe exact string sent in the payloadorder_completed
Display nameHuman-readable label in reportsOrder completed
Description / triggerWhen the event fires, once per whatFires once per paid order, after payment confirmation
CategoryGrouping for browsing the planCommerce
PlatformsWhich SDKs send itweb, ios, android
Property: nameExact property keyvalue
Property: typeData type, from the JSON type setnumber
Property: requiredMust every arrival carry it?yes
Property: description + exampleMeaning and a sample valueOrder total in USD; 40.00
OwnerWho answers questions about this eventPayments team
StatusLifecycle stageproposed → in development → in review → live → deprecated
VersionSchema revision for change tracking2

The type field is not decoration. JSON Schema — the specification most validation tooling builds on — defines a small closed set of basic types (string, number, boolean, object, array, null), and its required keyword lists the property keys that must be present. A schema written against that vocabulary can be checked mechanically; a schema that says "value: the price" cannot.

Here is the contract from the opening paragraph as a machine-checkable example (Sample data):

{
  "event": "order_completed",
  "version": 2,
  "trigger": "once per paid order, after payment confirmation",
  "platforms": ["web", "ios", "android"],
  "owner": "payments-team",
  "status": "live",
  "properties": {
    "order_id": { "type": "string", "required": true, "example": "ord_8841" },
    "value":    { "type": "number", "required": true, "example": 40.00 },
    "currency": { "type": "string", "required": true, "enum": ["USD", "EUR"] },
    "coupon":   { "type": "string", "required": false, "example": "FALL10" }
  }
}

Three required properties, one optional. Every field in this file exists so that a validator — or a new engineer — can answer "is this arrival correct?" without asking the original author.

Event schema vs tracking plan vs data dictionary

These three terms get used interchangeably, and teams then argue about the wrong document. They sit at different levels:

ArtifactScopeGranularityTypical maintainer
Event schemaOne eventName, properties, types, required flags, triggerThe team that owns the event
Tracking planAll events in the productCollection of schemas + categories, owners, platforms, statusAnalytics or data governance lead
Data dictionaryShared vocabularyCanonical definitions of properties and metrics reused across eventsAnalytics team, with domain owners

The practical rule: if two events both carry currency, the dictionary decides that currency means an ISO 4217 code; each schema decides whether that event requires it; the plan records that both events exist and who owns them. This article covers the schema layer — the plan itself, including how to build one, is covered in create a tracking plan.

Naming conventions that keep schemas stable

A schema is only enforceable if the names in it are predictable. Four rules cover most of the damage:

  1. Pick one pattern — object_action — and one casing. order_completed, signup_started, search_submitted. If a name doesn't read as noun + past-tense verb, reject it in review. Mixing OrderCompleted, order-completed and purchase for the same action creates three events that no funnel will ever join. Broader naming and grouping decisions belong to your data taxonomy.
  2. One canonical spelling per property. Decide value or revenue or amount — once, in the dictionary — and use it in every schema. If iOS sends order_value while web sends value, aggregations split silently.
  3. Never encode variable values in event names. order_completed with a plan property, not order_completed_pro and order_completed_enterprise. If the name contains a plan, country, or experiment ID, it belongs in a property.
  4. Types are part of the name's meaning. value is always a number, never a formatted string. If a platform's SDK serializes prices as strings, convert at instrumentation time — do not "fix it in the dashboard".

Worked example: required-property completeness

Here is what skipping the "verify on arrival" half of the contract costs. Sample data: an online store sends order_completed from web and iOS. The schema above requires order_id, value and currency. Over one day, 15,000 events arrive:

PlatformArrivalsWhat actually arrivedConforming arrivals
Web12,000Matches the schema, except 1,125 arrivals missing currency12,000 − 1,125 = 10,875
iOS3,000Old SDK build: sends orderId instead of order_id, value as a string ("40.00"), no currency at all0

Required-property completeness = conforming arrivals ÷ total arrivals:

  • Web: 10,875 ÷ 12,000 = 90.6% (90.625%, rounded to one decimal)
  • iOS: 0 ÷ 3,000 = 0%
  • Overall: (10,875 + 0) ÷ 15,000 = 72.5%

Nothing crashed. The dashboard still shows 15,000 "orders" — but every report built on the required properties silently drops the non-conforming arrivals. If average order value is $40, revenue computed from schema-conforming events shows 10,875 × $40 = $435,000 instead of 15,000 × $40 = $600,000. The gap is 15,000 − 10,875 = 4,125 events (all 3,000 iOS arrivals fail the contract, plus 1,125 web arrivals missing currency): 4,125 × $40 = $165,000 per day of invisible revenue. And a web-vs-iOS conversion comparison is meaningless, because one platform's events don't qualify at all.

Now run the contract properly: the schema is written first, arrival validation flags the iOS build, the SDK is fixed, and the missing currency on web is patched. The next day, same 15,000 arrivals:

  • Web: 11,960 conforming (40 still missing currency, caught by validation) → 99.7%
  • iOS: 2,950 conforming (50 from devices still on the old build) → 98.3%
  • Overall: (11,960 + 2,950) ÷ 15,000 = 14,910 ÷ 15,000 = 99.4%

Completeness went from 72.5% to 99.4% — a 26.9-percentage-point recovery — without collecting a single new event. The data was always there; the contract made it usable. That is the whole argument for writing the schema before sending data and validating on arrival: the same instrumentation produces trustworthy numbers or misleading ones depending only on whether the contract is enforced.

Versioning without breaking reports

Schemas change when products change. The goal is to make every change classifiable before it ships:

ChangeBreaking?Version bumpWhat to do
Add an optional property (coupon)NoMinor: 2 → 2.1Ship; note it in the changelog
Add a required propertyYes — old SDK builds fail validationMajor: 2 → 3Ship the property as optional first, make it required after old builds drain
Change a property's type (value string → number)YesMajorNew version + fix all senders before switching
Rename a property (orderId → order_id)YesMajorSend both keys during a transition window, then drop the old one
Remove or deprecate the eventYesMajor / status changeMark deprecated, keep it queryable until reports migrate

Two rules make the table work in practice. If a change would make yesterday's arrivals fail today's schema, it is breaking — no exceptions for "small" renames. And a breaking change needs a transition window sized to your slowest-updating platform: on the web you control the deploy, but mobile users can sit on an old SDK build for months, which is exactly how the iOS drift in the example above happens.

Common event schema mistakes

  • Treating the schema as documentation written after launch. Test: can a validator read your schema and reject a bad payload? If it lives in a slide deck, it is a wish, not a contract.
  • Letting each platform invent its own spelling. Test: diff the property keys arriving from web vs iOS for one event. Any difference is a future undercount — the example above lost 3,000 iOS orders a day to exactly this.
  • No required flags. If everything is optional, completeness is undefinable and validation has nothing to check. Decide the two or three properties every report depends on and mark them required.
  • Changing meaning without changing version. If value starts including tax, every historical comparison breaks silently. Bump the major version and annotate the change date so analysts can split the series.
  • Validating once at launch, never again. Drift arrives with the next SDK release, not at launch. Completeness needs a recurring check — a daily or rolling window — not a one-time audit. Ongoing checks like this belong to data quality work; granularity choices that interact with schema design are covered in data granularity.

Validating event schemas in TapCub

Take the store from the worked example into TapCub. The contract is written in one place, checked as events arrive, and the iOS drift shows up the same day.

  1. Write the contract before shipping. In All-platform analytics › Data › Tracking plan, add order_completed with its display name, category, platforms (web, ios), trigger, owner and status. Each property gets a name, type, required flag, description and example, so order_id (string, required), value (number, required) and currency (string, required) match the field table above. The plan can hold the event before any SDK sends it; set it to Developing while engineers build it.
  2. Watch completeness on arrival. Turn on Live verification (24 h) and the row shows 15,000 hits with required-property completeness well below 100%, the 72.5% day from the example. Move the row to Accepting while you chase the gap; low completeness is a warning and does not block events by itself.
  3. Find which sender broke it. In All-platform analytics › Data › Property dictionary, the daily scan lists keys with their type, samples and last seen, so a new orderId key next to order_id points straight at the old iOS build. Add a validation rule on value (expected type: number) with the Warn only action, and every string "40.00" becomes a warning in All-platform analytics › Data › Data quality instead of a silent gap in revenue.
  4. Review stray names instead of letting them split the data. If someone ships OrderCompleted, it appears as Unplanned in All-platform analytics › Data › Event inbox. It is still stored, so the inbox is a review queue: fix the call, or set the stray definition to Blocked so it stops being stored.

The boundary: TapCub can warn, drop a property, block an event or quarantine it, but it cannot turn orderId into order_id or "40.00" into 40. Fixing the payload is your team's job; TapCub tells you, within a day, that the contract is broken and where. That is the thesis applied: write the schema before data is sent, and validate every arrival against it.

See also: What is data validation? Checks, where to run them and a worked example.

See also: What is a data model? Levels, types and an event-model example.

Sources

Was this explanation clear?

We use your answers to fix and expand this page.

Lucas Hayes

Data Engineer

Writes about event design, data quality, and collection workflows, with verifiable implementation methods for reliable analytics.

FAQ

Questions people ask

Short answers to the follow-up questions that come up most.

Still have a question?

Chat with the team behind TapCub — we usually reply within a few hours on business days.

What is the difference between an event schema and a tracking plan?

An event schema defines one event: its name, properties, types and required flags. A tracking plan is the collection of all event schemas plus organizational metadata such as categories, owners, platforms and lifecycle status. The schema is the row; the tracking plan is the table.

What happens when an event does not match its schema?

It depends on enforcement. With no validation, the event lands anyway and quietly corrupts reports: missing required properties, wrong types, duplicate names. With validation, non-conforming events are flagged, quarantined or rejected, so the mismatch is visible while it can still be fixed.

How often should you update an event schema?

Whenever the product changes what an event means or carries — not on a fixed schedule. Adding an optional property is a minor, non-breaking change; removing a required property or changing a type is breaking and needs a new version, a migration note and a deprecation window.

Can event schemas be enforced automatically?

Yes. A structured schema can drive runtime validation that checks each arriving event's name, property presence and types, and reports completeness per event. Amplitude's schema settings, for example, can mark or reject unplanned events, properties and property values that violate the plan.

See this number on your own site

Add one script tag for web and apps, and the first reports fill in within minutes.

See your data clearly. Find your growth.

Every click, backed by data. Install one line of code and see your first numbers in a minute.

No credit card · Free plans for analytics and chat · Cookieless analytics