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:
| Field | What it records | Example |
|---|---|---|
| Event name | The exact string sent in the payload | order_completed |
| Display name | Human-readable label in reports | Order completed |
| Description / trigger | When the event fires, once per what | Fires once per paid order, after payment confirmation |
| Category | Grouping for browsing the plan | Commerce |
| Platforms | Which SDKs send it | web, ios, android |
| Property: name | Exact property key | value |
| Property: type | Data type, from the JSON type set | number |
| Property: required | Must every arrival carry it? | yes |
| Property: description + example | Meaning and a sample value | Order total in USD; 40.00 |
| Owner | Who answers questions about this event | Payments team |
| Status | Lifecycle stage | proposed → in development → in review → live → deprecated |
| Version | Schema revision for change tracking | 2 |
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:
| Artifact | Scope | Granularity | Typical maintainer |
|---|---|---|---|
| Event schema | One event | Name, properties, types, required flags, trigger | The team that owns the event |
| Tracking plan | All events in the product | Collection of schemas + categories, owners, platforms, status | Analytics or data governance lead |
| Data dictionary | Shared vocabulary | Canonical definitions of properties and metrics reused across events | Analytics 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:
- 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. MixingOrderCompleted,order-completedandpurchasefor the same action creates three events that no funnel will ever join. Broader naming and grouping decisions belong to your data taxonomy. - One canonical spelling per property. Decide
valueorrevenueoramount— once, in the dictionary — and use it in every schema. If iOS sendsorder_valuewhile web sendsvalue, aggregations split silently. - Never encode variable values in event names.
order_completedwith aplanproperty, notorder_completed_proandorder_completed_enterprise. If the name contains a plan, country, or experiment ID, it belongs in a property. - Types are part of the name's meaning.
valueis 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:
| Platform | Arrivals | What actually arrived | Conforming arrivals |
|---|---|---|---|
| Web | 12,000 | Matches the schema, except 1,125 arrivals missing currency | 12,000 − 1,125 = 10,875 |
| iOS | 3,000 | Old SDK build: sends orderId instead of order_id, value as a string ("40.00"), no currency at all | 0 |
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:
| Change | Breaking? | Version bump | What to do |
|---|---|---|---|
Add an optional property (coupon) | No | Minor: 2 → 2.1 | Ship; note it in the changelog |
| Add a required property | Yes — old SDK builds fail validation | Major: 2 → 3 | Ship the property as optional first, make it required after old builds drain |
Change a property's type (value string → number) | Yes | Major | New version + fix all senders before switching |
Rename a property (orderId → order_id) | Yes | Major | Send both keys during a transition window, then drop the old one |
| Remove or deprecate the event | Yes | Major / status change | Mark 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
valuestarts 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.
- Write the contract before shipping. In All-platform analytics › Data › Tracking plan, add
order_completedwith its display name, category, platforms (web,ios), trigger, owner and status. Each property gets a name, type, required flag, description and example, soorder_id(string, required),value(number, required) andcurrency(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. - 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.
- 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
orderIdkey next toorder_idpoints straight at the old iOS build. Add a validation rule onvalue(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. - 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
- Amplitude Docs, Create a tracking plan — event and property metadata, required flags, types and rules.
- Amplitude Docs, Protect your schema from unexpected data — marking or rejecting unplanned events, properties and values.
- JSON Schema, object — the
requiredkeyword and property definitions. - JSON Schema, Type-specific keywords — the basic JSON type set.
Was this explanation clear?
We use your answers to fix and expand this page.
Couldn’t send. Please try again in a minute.
Thanks for the feedback. We’ll use it to improve this page.You’ve already sent feedback on this page. Thanks.

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