Subscribe to get a new lesson each week!

Naming Conventions: One Step Towards Clean Data

Code that adheres to a style guide is easy to read. Likewise, events that follow a standard naming convention are easy to analyze.

In this article, we’ll go over why you need a strong naming convention for analytics and how to implement our preferred approach, the Object-Action Framework.

Benefits of Naming Conventions

If you really want to make the most out of your data, you have to be a stickler for exactly how you name analytics events and where they live in your codebase. If you don’t, different developers will implement tracking at different times with different preferences, resulting in a hodge podge of events that are hard to scan and to remember.

You might not realize, but there are actually a bunch of different ways to name the same user interaction.

A word cloud with a bunch of variations on Sign Up

I can’t count the number of times I asked our analysts if the right event was signup or Signed Up. These types of questions can happen to tons of data-driven organizations.

To avoid them and drive down your time to insight, you should choose how to name your events and properties (down to the casing), and enforce the standard across your company. Doing so will bring consistency, convenience and clarity.

  • Consistency — The biggest benefit of using a clear framework is data consistency. If your data is named the same way in each tool, it’s easier for you to use those tools. One framework. No questions.
  • Convenience — You’re likely going to continue to add new tracking throughout the lifetime of your product. Having a standard naming convention means that each time a developer implements a new call, they won’t have to think about how to do it.
  • Clarity — Your team will easily understand what each event means if you enforce a standard. Teammates won’t have to go ask whoever implemented the tracking what’s going on, and everyone can quickly run ad hoc analyses because your data is organized and easy to find.

If you take nothing else from this article, please remember that the most important thing to do is to pick a naming convention and stick with it.

The framework you choose is slightly less important, but at Segment, we’ve defined our favorite as the Object-Action Framework. Our success team developed this convention after working with thousands of customers on their analytics setup.

The Object-Action Framework

The idea is simple. First, choose your objects (ex: Song). Then define actions your customers can perform on those objects (ex: Played). When you put it all together, your event reads Song Played.

object action model

We like the Object-Action Framework because it makes it easy to

  • Analyze a particular feature’s performance. “I want to build a funnel to see how many people who play songs also favorite them. Sweet! The events related to songs are all next to each other in alphabetical order.”
  • Quickly scan a list of events to find what you’re looking for. “Where are the songs events? Nope, Nope. Got it.”
  • Impose a standard any marketer, analyst, or developer could understand. “I’m guessing this event called Playlist Shared is about folks sharing playlists. I’m smart.”

Now that you’ve got the basics, here’s a deep dive into how to use the Object-Action framework with some examples.

Choose your objects

The first piece of the object-action framework is the Object. These objects are the key “pieces” of your app and website that your customers are interacting with. It’s probably easiest to understand what a business object looks like with a few examples.

companies with their example objects

List how users can interact with them

The next thing to figure out is how users can interact with those objects in your product. For example, a user can play a song, or complete an order.

companies with their example objects and actions

Choose the properties to collect with each object

We recommend tracking general events like Song Played along with properties that give you more details. With just the top level event, you could analyze how often and how many people play songs. But you wouldn’t be able to see which songs and artists were the most popular.

When thinking about what properties to collect, you usually want to collect the same properties for the same object, no matter which action they are associated with.

For example, across events like Song Played, Song Favorited, and Song Shared, you’d want to collect a common set of properties related to songs, for example: name, artist, album, genre.

With these properties, you can easily figure out the most shared, favorited, and played artists and albums. If you wanted to only see how many people who play a Beyonce song also favorite it, you could do that too.

examples of companies objects and their properties

Be specific about casing

When you’re documenting each of these events and the properties associated with them, you also want to be crystal clear about the casing. This might seem nit-picky, but for those of us with OCD (or just like clean lists), it’s imperative.

Here are the five most common options:

  • all lower case — account created
  • snake_case — account_created
  • Proper Case — Account Created
  • camelCase — accountCreated
  • Title case — Account created

We like Proper Case for events and snake_case for properties.

Put it all together

Putting this all together, it’s really easy to construct your events.

Here is the naming template we adhere to:

Object Action
- object_properties

And here is a sample event, Song Played:

Song Played
- name
- artist_name
- album
- label
- genre

Document these events in your tracking plan and make sure to implement them in code with the same formatting.

In code, it would look something like this:

analytics.track('Song Played', {
  name: 'What Do You Mean',
  artist_name: 'Justin Bieber',
  album: 'Purpose',
  label: 'Def Jam - School Boy',
  genre: 'Dance Pop',
});

And in an analytics tool, it would look something like this:

Analytics Drop Down with Properties

This screenshot is from Mixpanel.

Other options

Of course the Object-Action framework isn’t the only way to do this. You can use any order of actions and objects, and any type of casing. You can also do present or past tense. JUST KEEP IT CONSISTENT!

We used to like the “action-oriented, past tense” system: Viewed Page, since it was easy to understand. There’s also present tense View Page , all lower cased view page, etc.

However, one system you definitely don’t want to use is dynamically creating new events with unique variables. You will never be able to make any sense of your funnels. Plus, your bills for your analytics tools will get out of control.

For example, sometimes we see people pass through the unique email with every signup in the event name. DON’T DO IT! Keep those as properties.

Don’t send sign up events as

analytics.track('Sign Up - jake@segment.com');

Instead, send them as

analytics.track('Sign Up', {
  email: 'jake@segment.com'
});

If you did the former, you could never answer, “How many signups did we get today?”

Hopefully this deep dive into the Object-Action Framework gave you some inspiration for keeping your data squeaky clean. We can’t stress how much you will kick yourself later if you don’t enforce these rules when you’re setting up!

Have a different way you like to name events? Let us know on Twitter!

Next article

The Anatomy of a `.track()` Call

Start your free email course today!

Get lessons right in your inbox!