SaaS Event Naming Convention That Scales

An event naming convention is not just a style guide — it is the organizational contract that determines whether product analytics scales or collapses. Every cohort analysis, retention curve, and funnel visualization in a SaaS company is built on top of event names. When those names are inconsistent, ambiguous, or action-first rather than object-first, analysts spend more time cleaning and mapping events than actually analyzing them.

The naming convention problem tends to be invisible until it is severe. Early-stage companies fire events with whatever names seem intuitive at the time — button_clicked, page_viewed, user_did_thing. By the time the company has 200 events and five squads adding new ones, the taxonomy is a historical accident rather than a designed system, and cohort analysis requires manual event mapping before every query.

The Object-Action Pattern

The object-action pattern is the most widely adopted and most analytically durable event naming convention in production SaaS instrumentation. The structure is: [object]_[action], where the object is a lowercase singular noun and the action is a lowercase past-tense verb.

The object-first ordering is the critical design decision. When events are named object-first, they sort alphabetically by entity:

account_created
account_deleted
account_suspended
document_created
document_exported
document_shared
subscription_cancelled
subscription_created
subscription_upgraded

This natural grouping by object means that any analyst or engineer who looks at an alphabetical list of events can immediately see all events related to a given entity. It makes documentation more readable, makes API reference tables more navigable, and makes analytics tool filter interfaces more usable.

The action-first alternative destroys this grouping:

cancelled_subscription
created_account
created_document
created_subscription
deleted_account
exported_document

Events now sort by action — useless for product analytics purposes — and the relationship between related events (all subscription events) is lost.

The object and action components should follow consistent vocabulary rules within the taxonomy. If "cancelled" is the verb for ending a subscription, it should not be "deleted" for a similar concept in a different module. If the object is "subscription" in one event, it should not be "plan" or "contract" in another event for the same concept. Vocabulary inconsistency is the first step toward event sprawl.

PostHog's instrumentation documentation recommends maintaining an explicit vocabulary list for both objects and actions — a controlled list of approved nouns and verbs that new events must draw from. New vocabulary terms are added to the list only through the governance review process, preventing unilateral naming decisions by individual engineers.

Complete Schema Structure

The event name is only one component of a well-designed event schema. A complete event schema has five layers.

Layer 1: Event name — the object-action string following the naming convention: subscription_cancelled.

Layer 2: Standard context properties — properties that are automatically attached to every event by the instrumentation layer, requiring no engineer action: user_id, account_id, session_id, timestamp, platform, app_version, environment (production/staging).

Layer 3: Entity-specific properties — properties that describe the primary object in the event name: for subscription_cancelled, these would be subscription_id, subscription_plan, subscription_mrr, subscription_term_months, days_since_subscription_created.

Layer 4: Context properties — properties that describe the circumstances of the event: cancellation_reason, triggered_by (user/system/support), had_feature_x_enabled, cohort_month.

Layer 5: Experiment properties — properties that capture the state of any active feature flags or experiments at the time of the event: flag_new_cancellation_flow set to true or false. This layer is critical for post-hoc experiment analysis and for debugging unexpected event patterns.

The separation of these layers in the schema documentation makes the instrumentation spec legible for engineers who did not design the event, and makes the event queryable by analysts who did not instrument it.

Namespace Design for Multi-Product Companies

Single-product companies can use the flat object-action naming convention without modification. Multi-product companies face a naming collision problem: both the project management module and the billing module might legitimately want an event called user_invited, but the two events represent completely different behaviors in completely different product contexts.

The solution is namespace prefixes. Every event in a multi-product taxonomy is prefixed with the product or module identifier:

billing_subscription_created
billing_invoice_paid
billing_payment_failed
project_task_created
project_member_invited
project_deadline_updated
analytics_report_created
analytics_dashboard_shared

The namespace prefix has three benefits. First, it eliminates name collisions — billing_member_invited and project_member_invited can coexist without ambiguity. Second, it enables product-level event filtering in analytics tools without requiring property filters — an analyst who wants to analyze only billing events can filter on events starting with billing_ rather than building a complex property filter. Third, it makes the data warehouse event tables more organized — events can be partitioned or grouped by namespace for query efficiency.

Namespace design requires early decisions about what constitutes a distinct namespace. The rule of thumb: if a distinct engineering team owns the product surface, it deserves a namespace prefix. If the surface is a feature within a single product team's ownership, it may not need its own namespace.

For multi-product companies with complex instrumentation needs, the product analytics instrumentation playbook describes how the entity-action-attribute structure applies across namespaces.

Versioning Strategies

Event schemas change. The question is not whether to version events — it is which versioning strategy to use for each type of change.

Additive property changes (adding new optional properties to an existing event) do not require versioning. The new property is simply added to the schema, marked as optional in the event registry, and backfilled with null for historical events. Existing queries remain valid because they do not reference the new property.

Breaking property changes (renaming an existing property, changing a property's type, removing a property) require versioning because existing queries will break. The options are:

Parallel tracking: Fire both the old event (with the old schema) and the new event (with the new schema) for a defined transition period — typically 60–90 days. This allows existing queries against the old event to remain valid while analysts migrate to the new schema. After the transition period, the old event is deprecated and eventually stopped.

Version suffix: Rename the event with a version suffix: document_exported becomes document_exported_v2. The original event continues to fire for the old schema, and the v2 event fires for the new schema. This creates a permanent version boundary in the event name — analytically clear but slightly verbose.

Deprecation without replacement: For events that are being removed from the taxonomy entirely (because the behavior they tracked is no longer supported), simply mark the event as deprecated in the event registry, stop firing it on a defined date, and document the deprecation date so analysts know not to query the event for data after that date.

Mixpanel's data governance guide recommends documenting the versioning strategy for every event schema change in the event registry, including the deprecation date and the migration notes. Without this documentation, analysts will encounter deprecated events in queries and have no way to determine whether the event is still valid or how to migrate to the replacement.

The Governance Process That Prevents Event Sprawl

Event sprawl is the condition where the analytics taxonomy contains hundreds of redundant, inconsistently named, or poorly documented events — making cohort analysis unreliable and analyst productivity low. According to Segment's data infrastructure research, companies without event governance processes have an average of 3.2x more events in their taxonomy than companies with governance processes, for the same product surface area. The excess events represent duplicated tracking, inconsistent naming, and abandoned instrumentation from features that were deprecated but whose events were never cleaned up.

Preventing event sprawl requires three mechanisms operating simultaneously.

The event registry is the authoritative documentation of every event in the production taxonomy. Each entry includes: event name, object, action, description of the intent captured, full property schema, the team that owns it, the date it was added, the date it was last modified, whether it is active or deprecated, and the analytics use cases it supports. The event registry must be the single source of truth — if an event is not in the registry, it should not be in production instrumentation.

The naming convention linter is an automated tool that checks event names and property names against the naming convention rules and flags violations before they reach production. A linter can catch: incorrect casing (camelCase instead of snake_case), action-first naming (cancelled_subscription instead of subscription_cancelled), undefined objects or verbs not in the approved vocabulary list, and duplicate event names. Linters run in CI/CD pipelines and fail the build when naming convention violations are detected. This moves event governance from a manual review burden to an automated enforcement mechanism.

The pre-ship review gate is a human review process where a product analytics stakeholder reviews and approves every new event or schema change before it is implemented in production. The review checks: Does the event capture intent rather than clicks? Is the event name consistent with the naming convention? Are all the required properties documented? Is there an existing event that already captures the same intent? Is the event entry complete in the event registry?

Together, the registry (documentation), linter (automated enforcement), and review gate (human judgment) create a governance system that scales with team growth without requiring constant vigilance from individual engineers.

Taxonomy Mistakes That Make Cohort Analysis Impossible

Certain naming and schema patterns make cohort analysis structurally impossible — not just inconvenient, but analytically broken.

Click-based events without intent information (button_clicked with button_label='Export') cannot be grouped into reliable cohorts because button labels change with UI redesigns and are not semantically stable. A cohort of "users who clicked the Export button" built in 2024 cannot be reproduced in 2026 if the button was renamed "Download" — the cohort definition no longer matches the historical data.

Page view events without semantic meaning (page_viewed with page_path='/settings/billing') track navigation, not value delivery. A cohort of "users who viewed the billing settings page" includes users who visited accidentally, users who were confused, and users who successfully updated their billing information — three completely different behaviors with different retention implications.

Missing entity IDs as properties make it impossible to build account-level cohorts from user-level events. If document_exported does not include account_id as a property, the event cannot be used to answer "how many accounts exported a document this week" — only "how many users." For B2B SaaS products where the unit of analysis is the account, missing account IDs are a critical instrumentation gap.

Inconsistent entity naming across events (user_id in some events, userId in others, uid in others) prevents JOIN operations in SQL. An analyst trying to build a funnel from user_signed_up (which uses userId) to subscription_created (which uses user_id) must apply a case transformation at query time — adding complexity and opportunities for error.

For the connection between naming convention decisions and the downstream analytics they enable, see the funnel visualization best practice guide and the cohort analysis tools comparison. The naming convention is the foundation on which every downstream analysis depends.

Implementing the Convention at an Existing Company

Most companies that decide to improve their event naming convention are working with an existing legacy taxonomy that cannot be discarded. The migration path requires a structured approach that improves the taxonomy progressively without breaking existing analyses.

Phase 1: Audit and document. Enumerate every event currently in production, classify each by analytical value (high: used in recurring analyses or OKRs; medium: used occasionally; low: never queried), and identify the naming convention violations in each.

Phase 2: Govern new events. Before renaming any existing events, install the governance process for new events. Every new event from this point forward must follow the naming convention and pass the review gate. This prevents the taxonomy from getting worse while the migration is being planned.

Phase 3: Migrate high-value events. Starting with the highest-value events, apply the parallel tracking strategy: fire the old event (for historical query compatibility) and the new compliant event simultaneously. After 90 days, deprecate the old event. Migrate medium-value events over the following quarter. Low-value events can be deprecated without migration.

Phase 4: Install the linter. After the high-value event migration is complete, install the naming convention linter in CI/CD. This makes governance automatic for all future development.

The SaaS self-serve analytics guide describes the semantic layer implementation that builds on top of a clean event taxonomy to enable self-serve analytics for non-technical teams.

Frequently Asked Questions

Conclusion

The event naming convention is the infrastructure beneath every product analytics capability in a SaaS company. A convention designed correctly — object-action pattern, namespace prefixes for multi-product, property schema standards, governed by a registry and linter — produces a taxonomy that analysts can trust, engineers can follow without ambiguity, and leadership can query confidently. A convention designed poorly — click-based, action-first, inconsistent across teams — produces event sprawl that compounds over time and eventually makes reliable cohort analysis impossible.

The governance mechanisms (event registry, naming convention linter, pre-ship review gate) are not bureaucracy — they are the mechanism by which the naming convention actually holds as the team grows. Without automated enforcement and documented review, even the best convention will drift within two quarters of adoption as new engineers make intuitive naming decisions that are inconsistent with the standard.