SaaS Event Taxonomy: Build a Tracking Plan That Won't Rot

Most SaaS analytics schemas start as a best guess. An engineer adds tracking to the signup flow, a growth lead requests conversion events for a campaign, a product manager wants to know which features are being used, and within six months the event stream contains 200 events named in four different conventions with overlapping coverage and no clear ownership. By the time the team hires its first data analyst, the first task is archaeology — figuring out which events are still firing, which are duplicates, and which have drifted from what their names suggest they track. The taxonomy rot started on day one.

Why event schemas degrade faster than other technical debt

Code debt accumulates slowly and often stays contained within the codebase. Event schema debt accumulates in the analytics layer and spreads to every report, dashboard, and growth experiment that depends on it. When an event name changes, historical data under the old name becomes invisible to new queries unless someone explicitly bridges the two. When a duplicate event exists — two events tracking the same user action under different names — any metric built on one is incomparable to a metric built on the other. When a property is added to some events but not others, any analysis that filters or segments by that property produces silently incomplete results.

The compounding nature of event schema debt is why it causes more analytical pain than most teams anticipate. A rotting schema does not produce obvious errors — it produces subtly wrong numbers. Conversion rates that look fine but exclude a percentage of users tracked under a deprecated event name. Activation rates that appear stable but are actually measuring a different user action than they were six months ago. Retention cohorts that exclude users from a new acquisition channel because those users' signup events fire under a new name not yet wired into the cohort query. The GA4 event discipline guide covers the discipline required for GA4 specifically; the taxonomy principles in this post apply across every product analytics tool.

The three-layer event architecture

A maintainable SaaS event schema has three distinct layers, each with different ownership, implementation patterns, and update cadences. Understanding the layers prevents the most common taxonomy mistake: treating every event as the same type of thing and managing them all with the same process.

The first layer is pageview events. These capture user navigation — which pages and views were loaded, in what order, from what referrer. In most analytics tools, pageview tracking is largely automatic once the SDK is installed. Pageview events should carry standard properties: URL, referrer, UTM parameters, and session identifiers. They require minimal ongoing maintenance and should not be customised heavily — the goal is consistent, automatic coverage of the user's navigation path.

The second layer is feature events. These are the manually instrumented events that capture meaningful interactions with specific product capabilities. A feature event fires when a user creates a report, invites a collaborator, connects an integration, or uses a core workflow. Feature events are the bulk of your instrumentation effort and the primary data source for activation analysis, funnel construction, and feature adoption reporting. They require deliberate naming, consistent properties, and an ownership model to prevent duplication.

The third layer is outcome events. These are server-side derived events that fire when a meaningful business outcome is achieved — not when a user clicks a button, but when the business consequence of that click is confirmed. An outcome event fires when an invited user accepts and completes their first action (not when the invite is sent). It fires when an integration successfully pulls data for the first time (not when the connect button is clicked). It fires when a subscription upgrades (not when the upgrade modal opens). Outcome events require server-side instrumentation because the confirmation of the outcome — the acceptance, the successful pull, the completed payment — is only visible on the server. They are the most analytically valuable events and the most commonly absent from SaaS analytics schemas.

Verb-noun naming: the convention that stays readable

Naming conventions degrade through three failure modes: vague names ("button_click"), noun-verb ordering that does not group by object ("created_report", "deleted_report"), and platform-coupled names that embed UI details ("pricing_page_upgrade_cta_v2_clicked"). All three make the schema unreadable to anyone who did not write the instrumentation and hard to query consistently.

The verb-noun convention solves all three. Events are named as action.object: "report.created", "integration.connected", "subscription.upgraded", "collaborator.invited", "dashboard.shared". This format groups related events alphabetically (all "report.*" events cluster together), makes intent immediately clear without documentation, and is agnostic to the UI implementation — "report.created" is the right name whether the user creates a report through a sidebar button, a keyboard shortcut, or an API call. When the UI changes, the event name does not need to. The object in the event name is always a product concept, never a UI element.

Event properties: what to include on every event

Event names identify what happened. Event properties describe the context. A schema with well-designed event names but thin or inconsistent properties produces events you can count but cannot segment — you know that 500 reports were created today, but you cannot tell which feature tier created them, whether they were created by free or paid users, or whether they contained live data or were created from a template.

Every feature event and outcome event should carry a standard property set in addition to any event-specific properties. The standard set should include: user identifier (server-side, not client-side), subscription plan at time of event, whether the user is in a trial period, the number of days since signup, and the acquisition channel the user arrived from. These properties enable the most important segmentation in SaaS analytics: comparing behavior across plan tiers, comparing free vs paid users, and correlating product behavior with acquisition channel. Without them as standard properties on every event, each analysis requires joining event data to user profile data separately — a query that most teams do not bother with and that produces inconsistent results when they do. The product vs web analytics comparison explains why user-level properties on events are the core capability that separates product analytics from pageview counting.

Governance: who owns the schema and how to change it

Technical governance of the event schema is the most commonly skipped step in analytics instrumentation, and its absence is the primary cause of schema rot. Without governance, events accumulate by accretion: every sprint adds a few new events, experiments leave test events unflagged, and deprecated features leave orphaned events in the stream. Within 18 months, the schema has grown to hundreds of events with no clear map of what is current, what is deprecated, and what was added for a one-time analysis and never removed.

Effective governance requires three things: a tracking plan document that is the single source of truth for all events (event name, description, properties, owner, and status), a review process for any new event addition that includes a naming check against existing events and a confirmation that the event is not already tracked under a different name, and a deprecation process that marks events as deprecated in the tracking plan before removing instrumentation and bridges old event names to new names in analytical queries for at least 90 days. The tracking plan does not need to be elaborate — a shared spreadsheet with the right columns works better than a sophisticated tool that no one updates.

Migrating an existing schema without breaking reporting

Most SaaS teams that need to improve their event taxonomy are not starting from scratch — they have an existing event stream with some good instrumentation, some duplicates, and some events that were good ideas at the time and have since drifted. The migration challenge is cleaning up the schema without breaking dashboards and funnels built on current event names.

The safest approach is additive migration: instrument the new event names alongside the old ones for a transition period rather than replacing old names immediately. Run both in parallel for 30-60 days, validate that the new events are firing correctly and capturing the same population as the old ones, and then migrate dashboards and funnels from old to new event names one at a time. Only deprecate the old events after all reporting has been migrated. This approach is more work in the short term but avoids the alternative — a hard cutover that breaks reports and creates a gap in historical data that requires manual bridging. The analytics stack instrumentation guide by ARR stage covers when to invest in schema cleanup relative to other analytics infrastructure priorities — for most teams it becomes critical between $1M and $5M ARR when the first dedicated data or growth hire joins and needs the schema to be reliable.