references/naming-and-schema.md

Event naming and tracking-plan schema

Compiled 2026-08 from vendor documentation; the rules below are the common ground between vendors so a plan ports between them.

Segment, "What is a tracking plan?" and the object-action naming framework (Segment Spec). https://segment.com/docs/protocols/tracking-plan/create/
Amplitude, Data Taxonomy Playbook (event and property naming, taxonomy governance). https://amplitude.com/blog/data-taxonomy-playbook
Google Analytics 4, event naming rules (snake_case, reserved prefixes, 40-character limit, recommended events). https://support.google.com/analytics/answer/13316687
PostHog, product analytics documentation (event capture, properties, person properties). https://posthog.com/docs/product-analytics
GDPR, Regulation (EU) 2016/679, Article 5(1)(c) data minimisation.

object_action, lowercase snake_case, ASCII: signup_completed, filter_applied, invoice_downloaded.
Past tense for completed outcomes (order_placed), present tense for intents that may not complete (checkout_start), and never both for the same moment.
No screen, product, platform or variant names in the event name; carry them as properties.
Max 40 characters; no reserved prefixes (ga_, google_, firebase_, vendor internals).
One event per user-meaningful moment. Do not encode outcomes in the name (payment_failed and payment_succeeded become payment_completed with status) unless the two are analysed as different funnels.
Properties: snake_case, one type each, enumerations listed in the plan, booleans prefixed is_ / has_, durations in milliseconds with _ms, money in minor units with _cents or an explicit currency.
Context properties on every event: screen, entry_point, platform, app_version, variant (when experiments run), session_id if the vendor does not supply one.
Person properties (stable attributes such as plan, role, signup date) are set once, not repeated on every event.
Versioning: when semantics change, add a new event and deprecate the old one in the plan; never silently repurpose a name.

Column	Content
event	The name per the rules above
trigger	Exact moment and component ("Save button in report editor, on successful server response")
properties	`name: type [enum values]`, one per line
source	client / server / both (server for money and persisted outcomes)
owner	Team or person accountable for the event firing correctly
metric served	The metric or funnel this event exists for
status	planned / implemented / verified / deprecated

Anonymous identifier: how it is generated and stored.
User identifier: when it is known and how anonymous history merges.
Consent: which categories exist, what fires before consent, how withdrawal is honoured.
Personal data inventory: which properties are personal data, the purpose, the retention period.

Step	Action	Expected event	Expected properties	Where to verify
1	...	...	...	vendor live view / debug console

Add: duplicate-fire check, client/server reconciliation for outcomes, consent-off session check, experiment assignment fires once per user.