How detailed should event properties be?

Detailed enough that the analytics team can answer the business questions without going back to engineering. A good rule: if you need to join the event data with another table to answer a listed question, you are missing a property. Over-instrumenting is cheaper than under-instrumenting. Adding a property later requires a code change and a new release. Adding it now costs an extra line in the schema.

Should events fire client-side or server-side?

Server-side is the source of truth for anything that involves data integrity: purchases, account creation, subscription changes. Client-side is appropriate for UI interactions that have no server component: button clicks, page views, tooltip hovers. When both are possible, prefer server-side. Client-side events can be blocked by ad blockers and lost during network failures.

How do we handle event versioning?

Include a `schema_version` property on every event (e.g., `"1.0"`). When the event schema changes (new required property, renamed property), bump the version. This lets the analytics pipeline handle old and new formats gracefully. Never remove a property without bumping the version.

What is the difference between this template and an event tracking plan?

A data requirements document defines the schema for a specific feature or initiative. An [event tracking plan](/templates) defines org-wide naming conventions, property standards, and governance rules. The data requirements doc references the tracking plan's conventions and adds feature-specific detail. Use both together.

Who should approve this document?

At minimum: the PM (owns the business questions), the engineering lead (owns implementation feasibility), and the analytics or data team lead (owns data quality). If the events feed into financial reporting or compliance systems, include the data governance owner as well. ---

Data Requirements Template

What This Template Is For

A data requirements document is the contract between product and engineering for analytics instrumentation. It specifies exactly what data to capture, how to structure it, and what constitutes valid data. Without this document, engineering guesses at property names, events fire inconsistently, and the analytics team spends weeks cleaning data instead of analyzing it.

Most analytics debt starts here. A PM says "we need to track signups" without defining whether that means form submissions, email confirmations, or first logins. Engineering picks one. Months later, the numbers don't match the billing system and nobody can figure out why. A precise data requirements doc prevents this entirely.

This template structures event definitions, property schemas, data source mappings, and validation rules into a single document that both product and engineering can sign off on. It pairs well with the Product Analytics Handbook for the full measurement framework, and the event tracking plan template for naming conventions and QA processes. For definitions of key metrics you plan to derive from these events, see the activation rate and retention metrics reference pages.

How to Use This Template

Start with the business questions you need to answer. Every event you define should trace back to a specific question or metric.
For each question, identify the user actions that generate the underlying data. These become your events.
Define each event with a name, trigger condition, and the exact properties to capture. Be specific about data types, allowed values, and whether properties are required or optional.
Map each event to its data source (client-side, server-side, or third-party) and specify the destination (analytics tool, data warehouse, or both).
Add validation rules so engineering can write automated tests. If an event fires without a required property, that is a bug.
Review the document with engineering, QA, and the data/analytics team before any sprint work begins.
After implementation, run the QA checklist against a staging environment before shipping to production.

The Template

Document Overview

Field	Details
Document Title	[e.g., "Q2 2026 - Onboarding Flow Data Requirements"]
Author	[PM name]
Eng Lead	[Engineering lead name]
Analytics Lead	[Data/analytics lead name]
Status	[Draft / In Review / Approved / Implemented]
Target Sprint	[Sprint or date]
Related Feature Spec	[Link to PRD or feature spec]

Business Questions

Before defining events, list the questions this instrumentation needs to answer.

#	Question	Metric It Feeds	Priority
1	[e.g., "What % of signups complete onboarding?"]	[Onboarding completion rate]	[P0 / P1 / P2]
2	[e.g., "Where do users drop off in the setup flow?"]	[Funnel drop-off rate by step]	[P0 / P1 / P2]
3	[e.g., "How long does it take to reach first value?"]	[Time to first value]	[P0 / P1 / P2]

Event Definitions

Event 1: [event_name]

Field	Value
Event Name	[e.g., `onboarding_step_completed`]
Trigger	[Exact condition: "Fires when user clicks 'Next' on any onboarding step and the step is validated server-side"]
Source	[Client-side / Server-side / Both]
Destination	[Amplitude / Segment / Data warehouse / All]
Frequency	[Once per step per user / Every occurrence]

Properties:

Property	Type	Required	Description	Example Value	Allowed Values
`step_number`	integer	Yes	The onboarding step (1-indexed)	`2`	1-5
`step_name`	string	Yes	Human-readable step label	`"invite_teammates"`	Enum: see list below
`time_on_step_ms`	integer	Yes	Milliseconds spent on this step	`14320`	> 0
`input_method`	string	No	How the user completed the step	`"manual"`	`"manual"`, `"skip"`, `"import"`

Validation Rules:

☐ step_number must be between 1 and the total number of onboarding steps
☐ step_name must match one of the defined enum values
☐ time_on_step_ms must be a positive integer
☐ Event must not fire if the step validation fails server-side

(Repeat this block for each event)

Property Enums and Lookup Tables

Enum Name	Values
`step_name`	`"create_account"`, `"set_profile"`, `"create_project"`, `"invite_teammates"`, `"complete_tour"`
`input_method`	`"manual"`, `"skip"`, `"import"`, `"ai_generated"`
[Add more as needed]

Data Source Matrix

Event	Client SDK	Server API	Third-Party	Destination	Notes
[event_name_1]	[Yes/No]	[Yes/No]	[Source name]	[Amplitude, Segment, Warehouse]	[e.g., "Server-side is source of truth for this event"]
[event_name_2]	[Yes/No]	[Yes/No]	[Source name]	[Destination]	[Notes]

Identity Resolution

Field	Value
Primary Identifier	[e.g., `user_id` (UUID, set at account creation)]
Anonymous Identifier	[e.g., `anonymous_id` (UUID, set by analytics SDK on first visit)]
Merge Trigger	[e.g., "On successful signup, call `identify(user_id)` to merge anonymous and authenticated sessions"]
Cross-Platform	[e.g., "Web and mobile share the same `user_id`. Anonymous IDs are device-specific."]

QA Checklist

☐ All events fire in staging environment with correct property values
☐ Required properties are never null or empty
☐ Enum values match the defined lookup tables exactly (case-sensitive)
☐ Events do not fire on page load unless explicitly specified
☐ Duplicate events are not sent for the same user action
☐ Identity resolution works: anonymous events merge with authenticated user on signup/login
☐ Event volume in staging matches expected patterns (no infinite loops, no missing events)
☐ Data appears in the destination tool within the expected latency window

Filled Example: SaaS Onboarding Instrumentation

Document Overview

Field	Details
Document Title	Q2 2026 - TaskFlow Onboarding Instrumentation
Author	Maria Chen, Product Manager
Eng Lead	Jake Torres
Analytics Lead	Priya Sharma
Status	Approved
Target Sprint	Sprint 14 (March 18-29, 2026)
Related Feature Spec	[TaskFlow Onboarding Redesign PRD v2.1]

Business Questions

#	Question	Metric It Feeds	Priority
1	What % of signups complete all 4 onboarding steps?	Onboarding completion rate	P0
2	Which step has the highest drop-off?	Step-level funnel conversion	P0
3	How long does onboarding take end-to-end?	Time to first value (TTFV)	P1
4	Do users who skip steps retain worse than those who complete them?	Skip vs. complete retention at D7	P1

Event: `onboarding_step_completed`

Field	Value
Event Name	`onboarding_step_completed`
Trigger	Fires when the server confirms a user has completed or skipped an onboarding step. Does not fire on client-side validation alone.
Source	Server-side (POST /api/onboarding/complete-step response 200)
Destination	Segment (routed to Amplitude + BigQuery)
Frequency	Once per step per user. If a user revisits a completed step, do not re-fire.

Properties:

Property	Type	Required	Description	Example Value	Allowed Values
`step_number`	integer	Yes	1-indexed step position	`2`	1-4
`step_name`	string	Yes	Step identifier	`"create_project"`	`"set_profile"`, `"create_project"`, `"invite_team"`, `"start_tour"`
`time_on_step_ms`	integer	Yes	Time from step load to completion	`34200`	> 0
`input_method`	string	Yes	How the step was completed	`"manual"`	`"manual"`, `"skip"`, `"import"`
`onboarding_variant`	string	Yes	A/B test variant	`"guided_v2"`	`"guided_v1"`, `"guided_v2"`, `"self_serve"`

Event: `onboarding_completed`

Field	Value
Event Name	`onboarding_completed`
Trigger	Fires when the user completes or skips all 4 onboarding steps.
Source	Server-side
Destination	Segment (routed to Amplitude + BigQuery)
Frequency	Once per user, ever.

Properties:

Property	Type	Required	Description	Example Value
`total_time_ms`	integer	Yes	Total time from first step load to final step completion	`187400`
`steps_skipped`	integer	Yes	Number of steps the user skipped	`1`
`onboarding_variant`	string	Yes	A/B test variant	`"guided_v2"`

Key Takeaways

Every event should trace back to a specific business question or metric
Define exact trigger conditions, property types, and allowed values for each event
Specify whether events fire client-side or server-side, and name the destination
Include a QA checklist that engineering can run against staging before shipping
Review the document with product, engineering, and analytics before sprint work begins

About This Template

Created by: Tim Adair

Last Updated: 3/4/2026

Version: 1.0.0

License: Free for personal and commercial use

Data Requirements Template