Event Naming And Taxonomy

Who this is for

This subskill is for Product Analysts, Product Managers, and Engineers who define or audit analytics events. If you touch tracking plans, dashboards, funnels, or experiments, good naming and taxonomy will save you hours every week.

Prerequisites

• Basic understanding of what an event and property are in product analytics.
• Familiarity with your product's core user flows (e.g., sign up, purchase).
• Ability to read simple JSON examples.

Why this matters

• Prevents duplicate or ambiguous events that break funnels and cohorts.
• Speeds up analysis because names and properties are predictable.
• Reduces rework during instrumentation and experimentation.
• Improves team collaboration and documentation quality.

Real tasks you will do with this skill:

• Design a clean tracking spec for a new feature (names, properties, allowed values).
• Refactor legacy events and define deprecation rules.
• Create a taxonomy that groups events by domain (e.g., Acquisition, Commerce, Errors).

Concept explained simply

Event naming is choosing short, consistent names for user or system actions. Taxonomy is the organized system that groups those events and properties so anyone can find and use them reliably.

Mental model

Think of your analytics as a public API for your team. If the API names are predictable, everyone can query them without “hunting.” Inconsistent names are like typos in function names—your code (analysis) constantly breaks.

Core naming rules that work

1. Pattern: object_action in snake_case using past tense (e.g., product_viewed, trial_started, order_completed).
2. One concept → one name: Do not create synonyms (e.g., avoid both signup_completed and account_created for the same moment).
3. Actor is implied: Do not prefix with user_ unless necessary (user_report_exported is acceptable if multiple actors exist).
4. Properties are consistent: snake_case keys, stable types, and defined allowed values (enums).
5. Scope qualifiers last: Add clarifiers at the end (e.g., product_saved_to_list, checkout_started_guest).
6. Keep names short: Prefer 1–3 words. Put details in properties.
7. Version when needed: Use _v2 only for breaking changes with a deprecation plan.

Taxonomy structure

• Domains: Acquisition, Activation, Engagement, Monetization, Retention, Errors/Quality, Admin.
• Event groups: Navigation (page_viewed), Content (content_shared), Commerce (product_viewed, order_completed), Account (account_created), Experiment (variant_exposed), System (job_failed).
• Property dictionaries: For each event, list property name, type, required?, allowed values, example.

Worked examples

Example 1 — Signup (good)

Event: account_created

• method (enum, required): email, google, apple
• source (enum): landing_page, referral, ad
• campaign (string): e.g., spring_launch
• experiment_key (string): e.g., onb_v2

Example 2 — Add to cart (good)

Event: product_added_to_cart

• product_id (string, required)
• sku (string)
• price (number, required)
• currency (enum, required): USD, EUR, GBP
• source (enum): product_page, recommendation, search

Example 3 — Payment failed (good)

Event: payment_failed

• error_code (string, required): e.g., card_declined
• gateway (enum): stripe, braintree
• retryable (boolean)
• order_id (string)

Governance and change management

• Propose: Anyone submits a new event using the template below.
• Review: Analyst + Engineer approve name, properties, and types.
• Instrument: Engineer implements; Analyst validates in staging.
• Versioning: For breaking changes, create event_name_v2, keep event_name for a deprecation window, migrate dashboards, then sunset.
• Ownership: Each domain has an owner responsible for quality and documentation.

Templates you can copy

One-line naming rule: Use object_action in snake_case, past tense; details in properties.

{
  "event": "product_added_to_cart",
  "domain": "Monetization",
  "description": "User added a product to the cart",
  "properties": [
    {"name": "product_id", "type": "string", "required": true},
    {"name": "price", "type": "number", "required": true},
    {"name": "currency", "type": "enum", "allowed": ["USD", "EUR", "GBP"], "required": true},
    {"name": "source", "type": "enum", "allowed": ["product_page", "recommendation", "search"], "required": false}
  ],
  "owner": "Commerce Analytics",
  "notes": "Do not include discounts here; send final price only."
}

Create a naming proposal in 30 minutes

1. List the 3–5 key actions in the flow (e.g., view → add → checkout → purchase).
2. Apply the pattern object_action (past tense) to each.
3. For each event, list 4–6 properties: ids, amounts, currency, source.
4. Mark required properties and define allowed values for enums.
5. Share for review; agree on any versions or deprecations.

Exercises

You can do these now. The quick test at the end is available to everyone; if you log in, your progress will be saved.

1. Exercise 1: Normalize messy events (see details in the Exercises block below).
2. Exercise 2: Design a mini taxonomy for "Save for later" in an e‑commerce app.

• Checklist to self-check:
  • Names follow object_action in snake_case, past tense.
  • No synonyms for the same action.
  • Properties have stable types and allowed values.
  • Required properties are clearly marked.
  • Any breaking changes include a version plan.

Common mistakes and how to self-check

• Mixing cases: e.g., SignUp vs sign_up. Fix with a linter checklist.
• Encoding data in names: e.g., product_added_to_cart_from_rec. Put source in properties.
• Forgetting types: Strings for numbers cause failed aggregations. Declare types.
• Renaming without migration: Dashboards break. Use _v2 + sunset plan.
• Property sprawl: Too many optional fields. Keep 4–8 high-signal properties.

Practical projects

• Define a tracking spec for your onboarding flow (4–6 events). Deliverable: one-page JSON spec + data dictionary.
• Audit your product’s top 20 events. Deliverable: a list of merges, renames, and deprecations with owners and dates.
• Design an error telemetry taxonomy (_failed/_timed_out/_recovered). Deliverable: consistent names + error_code catalog.

Learning path

1. Master event naming and taxonomy (this lesson).
2. Create tracking specs and validate data in staging.
3. Set up governance: owners, review cadence, deprecation policy.
4. Automate checks (naming, type validation) in CI where possible.
5. Iterate based on analysis needs and experiment learnings.

Next steps

• Convert one live flow to this naming pattern.
• Schedule a 30-minute review with Engineering and PM to approve changes.
• Run the quick test below to confirm understanding.

Mini challenge

Pick any app you use daily. Write five events for a key user flow using the rules above and include two events for failures. Keep names under three words and define 4–6 properties each.