Event naming conventions that survive contact with a team

Every analytics project starts clean and ends with an event called evt_452 whose meaning only one person remembers — and they left. Naming is the cheapest insurance your data pipeline will ever have. Here’s the convention that keeps our customers’ event streams readable years in.

The golden rule: noun.verb

checkout.completed, plan.upgraded, user.deleted. Object first, action second, lowercase, dotted. It reads like English, it sorts alphabetically, and it never needs a lookup table.

Avoid the two failure modes:

• Verb first: completed_checkout scatters everything that happened to checkout across the alphabet.
• Acronyms and shorthand: co, ckout, purch. Your future self is not a code golf judge.

Properties are where the detail lives

The event name is the what; properties are the context. Keep names stable and let properties carry the nuance:

checkout.started
  plan: "business"
  source: "blog"
  region: "eu"

If you’re tempted to create checkout.started.from.blog.for.business, stop — that’s a filter, not a name.

Version it like an API

Rename events by adding a version suffix, not by editing history. checkout.completed that changes meaning becomes checkout.completed.v2. Old dashboards keep working, new ones get the new shape, and nobody has to grep for the migration.

Agree once, write it down

The convention is worth less than the agreement. Write it into your contributing guide, link it from your first PR template, and name it something searchable. Then hold the line: a code review comment about “event name drift” is a normal Tuesday at Vireo, and we’re fine with that.

The payoff

Teams that follow these rules can answer “what does this event mean?” from memory, years later. Teams that don’t end up with a data dictionary document that’s always out of date. Pick the convention that doesn’t need a document.