Naming Conventions That Survive the Third Consultant

Open any CDP that has been live for two years and shipped through three consultants. The event catalog tells the story.

user_login, userLoggedIn, login_success, session_start_logged_in. Four events. Same intent. Different consultants. All still firing. No single segment query works across them. Every report has to union four tables. The analyst who inherits this thinks the platform is broken. The platform is fine. The convention is missing.

A naming convention is the difference between a platform anyone on the team can open and one only one person understands. The platforms that survive turnover have a convention. The ones that decay don’t.

What a convention is

A naming convention is three things.

A set of rules for how events, attributes, segments, and scenarios are named. A single document that describes those rules, versioned and referenced. A named owner who approves new elements against the rules and retires old ones that don’t fit.

Without all three, the document becomes stale, the owner becomes a gatekeeper, or the rules become suggestions. The three parts hold each other up.

Most conventions fail not because the rules are wrong, but because the second and third parts are missing. A perfect rule set with no enforcement is a marketing deck.

The rules we use

After ten years and forty-plus implementations, the convention below is what holds up. Other conventions work too. This one survives consultant turnover with the least friction.

Three rules apply to every name. English only. Lowercase with underscores for anything that appears in code: events, properties, attributes, definitions. And a short dictionary of the abbreviations the team may use (ltv, aov, d30), kept in the convention document so nobody invents a second one.

Events

One event per business moment, named after the moment: purchase, cart_update, view_item, consent, email_signup. Anything that varies goes into a property, not into the name.

• cart_update with action: add, remove, empty.

• purchase with status: completed, cancelled, refunded, plus coupon_code when one was used.

• email_signup with source: footer, checkout, popup.

Each property has a fixed type and, where possible, a closed list of values written in the tracking plan. A new variant is a new value, not a new event. A segment then reads one event and filters on a property, so nothing has to be unioned, and the event list stays short enough to read in a minute. It also matches how the platforms name their own events: Bloomreach records every email delivery, open, and click as one campaign event with a status.

Attributes

An attribute name starts with its data type, then says what it holds.

• num_ number: num_order_count

• txt_ text: txt_loyalty_tier

• date_ date: date_first_seen

• flag_ flag, true or false: flag_consent_email

• id_ identifier: id_crm_customer

• list_ list: list_viewed_categories

The prefix answers the first question an analyst asks, what can I compare this with, before they open the attribute. It also sorts the attribute list by type, so every date sits together and the short prefixes read without a legend. A flag names the positive state: flag_consent_email, not flag_not_opted_out. Negative names invite double negatives in every filter built on them. What the name can’t hold goes into the attribute’s description, with one example value.

Calculated definitions

Aggregates, expressions, and running aggregates take the same type prefix, then four more slots: metric, event, property, window.

• num_count_purchase_d30: purchases in the last 30 days.

• num_sum_purchase_total_price_y1: revenue in the last year.

• txt_last_consent_source: where the latest consent came from.

• date_first_purchase_all: date of the first purchase ever.

The window always comes last, from a short list: d7, d30, d90, y1, all. A definition with no window in its name is how two people end up reading the same number differently. The kind of definition stays out of the name, because the platform already shows it with an icon.

Segments

Segments follow the pattern audience_criteria_window, with the same window list.

• vip_customers_d90

• cart_abandoners_d7

• high_value_at_risk_d30

The audience is who. The criteria is why. The window is when. A segment that doesn’t declare its window in the name hides its own decay. Two months later, nobody remembers whether vip_customers meant last year or lifetime, and the number on the dashboard stops meaning anything.

Things people build

Scenarios, campaigns, weblayers, experiments, reports, and creative assets start with the year and month they were created, then the goal: 202605_welcome_onboarding, 202605_summer_sale_early_access. The list sorts by age, and anyone can see which creative and copy have run for a year and are due for a refresh.

Channel, audience, owner, and status go into tags, not into the name. A scenario that adds SMS next quarter shouldn’t need a rename, and a tag can be filtered where a long name can’t. Bloomreach takes tags on scenarios, reports, and other assets.

Weblayers need one more prefix. Only one layer per group shows, and Bloomreach picks it in alphabetical order, so the name sets the priority. Put a three-digit priority first, in steps of five: 100_202605_exit_intent_newsletter, 105_202603_free_shipping_bar. Reordering is a rename, and the gaps leave room for a new layer without renaming the rest.

Versioning happens in metadata, not in the name. 202605_welcome_onboarding_v2 means v1 is still live and both are firing. The right answer is one live scenario with a version in a field you can filter on.

The numbers rule

No numbers in names unless they describe the thing, its creation month, its window, or a weblayer’s priority. Never a version. email_7_day_reminder is fine because seven is a property of the reminder. email_reminder_v3 isn’t.

Where the rules break down

No convention survives every edge case. The ones that survive turnover are explicit about the cases they don’t cover.

Legacy data. Most platforms have been live before the convention was written. Rewriting every historical event is rarely worth the cost. The pragmatic answer is to apply the convention going forward and maintain a mapping table for legacy names. The mapping lives in the convention document and gets referenced in every report that crosses the boundary.

Vendor-defined events. Bloomreach fires built-in events like session_start and session_end. The convention should explicitly exempt vendor-defined names and mark them clearly. Don’t try to rename what the platform gives you.

Multi-brand tenancy. A single CDP running three brands carries the brand as a property on every event and as a tag on every campaign. Never as a second copy of each event per brand: brandx_purchase and brandy_purchase are the duplicate problem again.

Agency-specific experiments. Campaign-level A/B tests that will run for two weeks don’t need to meet the full convention. A relaxed rule for temporary elements keeps the main catalog clean. The rule is that temporary elements carry an end date in a tag or the description and get retired when it passes.

The governance ritual

The convention lives or dies on enforcement.

Once a month, thirty minutes. Anyone who wants a new event, attribute, segment, or scenario presents it to the owner. Does it meet the convention? If not, can it be adjusted. If it does meet the convention, it ships. If it doesn’t, it either gets adjusted or it waits. The meeting is short because most proposals are either clearly in or clearly out. The few that are ambiguous take the time.

Quarterly, the same owner audits the catalog. Events that haven’t fired in ninety days get deprecated. Segments that nobody uses get archived. Attributes that duplicate others get merged. The audit takes a full day. It pays back across every subsequent query.

The meeting cadence is the thing that doesn’t get done. Most conventions get adopted for the first few weeks. The ones that survive past month three are the ones where the monthly meeting is in the calendar and the quarterly audit is blocked off.

Why the third consultant matters

The title of this piece is deliberate. The first consultant defines the convention. The second consultant keeps it. The third consultant is the test.

By the time a third consultant arrives, the first two have left. The convention document is a year old. The platform has hundreds of events and attributes. Either the new consultant can open the catalog and read it, or they can’t.

If they can, the convention has done its job. If they can’t, the platform decays. A convention that doesn’t survive the third consultant is a style guide nobody follows.

What to do with this

If you’re starting a CDP implementation, write the convention in week one. Not week twelve. Not after the first set of events is live.

If you have a CDP that has been live for more than a year, assume the convention has drifted. Block off a day. Audit the event catalog. Group the variants that describe the same thing. Pick the winner. Deprecate the rest. Write the convention as it is, not as you wish it was, then decide what to change.

If you’re inheriting a platform from another team or another consultancy, the convention is the first artifact to ask for. Not the dashboard, not the segment library, not the scenario inventory. The convention. If it doesn’t exist, that’s the project. Everything else depends on it.

For the data types the convention applies to, see Seven Types of Customer Data Inside a CDP. For the ownership dimension, see Where Customer Data Comes From.

A convention isn’t a document. It’s a document, an owner, and a ritual. The ones that hold are the ones where all three are named. Write the names down before the second consultant arrives.

Read next

• Data Sanity: Keeping Your Marketing Data in Check. The data-side twin of naming discipline.

• Campaign Evaluation: Don’t Be Scared, Be Smart. Clean names are what make evaluation queries possible.