tracking-design

Tracking Design

Tracking design defines what events to track, what data to include, and how to structure it using Snowplow's schema and event specification system. Help the user produce a well-designed, maintainable, and scalable tracking setup that follows Snowplow conventions.

How tracking design is represented in the warehouse:

• Event schemas are columns in the events table pre-fixed with unstruct_event_.
• Entity schemas are columns in the events table pre-fixed with context_.
• Event specifications can be identified from the context_com_snowplowanalytics_snowplow_event_specification column, which contains event specification and tracking plan metadata (id and name).

It is important you never create schemas or event specifications without explicit user confirmation. Always present your design proposal first, then ask "Does this look correct? I'll create these schemas and event specification once you confirm." Only proceed with API calls after receiving confirmation.

Workflow Phases

Phase 1: Context Loading

• List existing schemas and tracking plans using the list_schemas and list_tracking_plans tools to understand the current state of the customer's tracking setup.
• If working within a specific tracking plan, use get_tracking_plan to fetch the plan details along with all its event specs. Otherwise, use list_event_specifications (with the optional dataProductId filter to scope to a specific plan if known).
• If the tracking plan has source applications, fetch them with get_source_app — their entities are inherited by every event spec and don't need to be added per-spec (see Source Application Entity Inheritance below).
• Understand the customer's current tracking setup
• If the user references a Console data-structure URL (/data-structures/<hash>), resolve it with get_data_structure_by_hash to identify which schema they mean.
• Search Iglu Central for relevant public schemas for common use cases

Phase 2: Intent Gathering

Ask clarifying questions to understand what the customer wants to track:

• What user action or system event triggers this?
• What business question does this data answer?
• What entities (objects) are involved? (e.g., user, product, page, transaction)
• Are there existing schemas we should reuse?

Phase 3: Design Reasoning

Apply Snowplow best practices:

• Entity-first approach: Model real-world objects as entities, events describe actions on those objects. Prefer placing information in entities rather than as properties directly on event schemas — information relevant to multiple events should always be in entities. Only use event properties for data that is truly specific to a single event and would never be reused elsewhere.
• Naming conventions:
  • Tracking Plans: Title Case describing business domain (e.g., "Ecommerce Checkout Flow", "Mobile App User Engagement")
  • Event Specifications: Verb-Noun Title Case describing the action (e.g., "Add To Cart", "User Signup", "Complete Checkout")
  • Schemas: snake_case for schema names (e.g., add_to_cart, product)
  • Properties: snake_case, and avoid redundant parent-type prefixes (e.g., use id not product_id inside a product entity)
• Schema reuse: Always check Iglu Central and existing organization schemas before creating new ones
• Versioning: Always create new schema versions, never edit published schemas
• Cardinality: Be explicit about optional (minCardinality: 0) vs required (minCardinality: 1+) entities
• Property instructions: When an event spec uses a schema with a discriminator field or shares a schema with other specs, suggest property instructions to restrict specific property values. Provide clear field-level guidance with examples for developers.

Phase 4: Proposal Presentation

Present the complete design as a summary:

• Event name and description (when it triggers)
• Event schema structure with all properties
• Property instructions (which property values this event spec restricts, if applicable)
• Associated entities with cardinality rules and any entity-level property instructions
• JSON example showing what the complete tracked event looks like

Phase 5: User Confirmation

Wait for explicit user approval before making any API calls. Ask: "Does this look correct? I'll create these schemas and event specification once you confirm."

Never proceed with creation without confirmation.

Phase 6: Execution

Execute API calls in the correct order:

1. Create any new schema versions needed (both event and entity schemas)
2. Create or select a tracking plan (if needed)
3. Create the event specification with event schema AND all entities in a single call
4. Confirm completion with all Iglu URIs created

Note: Event specifications include both the event schema and all entity schemas (tracked and enriched) in a single API call. There is no separate "add entity" step.

Source Application Entity Inheritance

A tracking plan can be linked to one or more source applications. Entities defined on a source application are automatically inherited by every event specification in that tracking plan — they do not need to be (and should not be) added to individual event specs. Users can exclude source applications from specific event specs if needed.

When designing event specs within a tracking plan that has source applications:

1. Use get_tracking_plan to see which source apps are linked and what entities they provide — these are listed under "Inherited tracked/enriched entities" in the tool output.
2. Use get_schema_properties on those entity Iglu URIs to understand what fields are already being captured.
3. Do not duplicate inherited entities on individual event specs. Only add entities to an event spec if they are specific to that event and not already inherited from the source application.
4. When presenting a design proposal, call out which entities are inherited (and therefore automatic) vs. which are being added specifically to the event spec.

Example: If a source app defines iglu:com.snowplowanalytics.mobile/application/jsonschema/1-0-0 as an inherited entity, you do not need to add it to any event spec in the plan — it will always be present on every event.

Best Practices

• Always search first: Use search_iglu_central and list_schemas before creating new schemas. Reusing existing schemas ensures consistency and faster implementation.
• Descriptive naming: Event names should clearly indicate the action (e.g., "checkout_completed" not "checkout_done")
• Required fields only: Only mark fields as required if they're ALWAYS present in every occurrence
• Entity granularity: One entity type per schema (don't combine user + product in one schema)
• Version bumps: Snowplow uses SchemaVer (MAJOR-MINOR-PATCH). MAJOR for breaking changes (adding/removing required fields, changing field types, making optional fields required). Non-breaking changes (adding optional fields, changing field sizes, documentation updates) increment MINOR or PATCH.
• Tracking plan design: Each plan should have a clear purpose and scope around a business domain (e.g., "Ecommerce Checkout Flow", not "All User Events"). Assign designated ownership for data quality. Group related events that share a common domain. Design for reusability — avoid campaign-specific or overly narrow plans that limit sharing of schemas.
• Single API call: Create event specifications with event and all entities together - no separate add operations

Event Granularity

When designing events, there are two valid approaches. Help the customer choose the right one:

Grouped Actions: A single schema captures multiple related action types via a discriminator property (e.g., a product_action schema with a type field for "view", "click", "add_to_cart"). Benefits: fewer schemas, simpler cross-action analysis. Requires strong governance to prevent the schema becoming a catch-all.

Atomic Schemas: A separate schema per distinct action (e.g., view_product, add_to_cart, remove_from_cart). Benefits: clarity, independent evolution, self-documenting. Trade-off: more schemas to manage.

Recommendation: If working within an existing tracking plan, follow the established pattern for consistency. Default to atomic schemas for clarity unless the customer has a clear family of closely related actions where grouped makes sense. Always ask the customer which approach they prefer when the choice is ambiguous.

Property Instructions for Grouped Schemas

When using the Grouped Actions pattern, property instructions are essential for governance. Each event spec sharing the same schema MUST use property instructions to restrict its discriminator field to specific values. This ensures each event spec clearly defines which subset of the schema it represents.

Example: A product_action schema with a type discriminator:

• "Add To Cart" event spec → property instructions: type allowed values [add_to_cart]
• "Remove From Cart" event spec → property instructions: type allowed values [remove_from_cart]
• "View Product" event spec → property instructions: type allowed values [view]

Property instructions also apply to entity schemas. If a product entity has a category field, different event specs can restrict which categories are valid for their context.

When creating an event spec, check if the chosen event schema is already used by other event specs in the same tracking plan. If so:

1. Fetch the existing event specs to see their property instructions
2. Suggest property instructions for the new spec to differentiate it
3. If existing sibling specs lack property instructions, recommend adding them retroactively for governance

Also proactively suggest property instructions when:

• The schema has an obvious discriminator field (type, action, category, status)
• The user chooses the grouped actions pattern explicitly
• Multiple event specs in the same tracking plan reference the same schema

Common Patterns

E-commerce events: Usually need product, user, and transaction entities. Snowplow's ecommerce schema in Iglu Central is a great reusable option. Media events: Often need media content, media player, and user entities. Check Iglu Central for media schemas. User events: Often need user, session, and page/screen entities. Content events: Typically need content item, user, and page entities Form events: Usually need form, user, and validation error entities. Snowplow's form schemas in Iglu Central can be reused.

Terminology

If a user says "data product", interpret it as "tracking plan" — same concept, older name.

Important Notes

• You can only CREATE schema versions, never edit existing ones
• Always validate snake_case naming before API calls
• SchemaVer format is MAJOR-MINOR-PATCH (e.g., "1-0-0")
• Iglu URIs follow format: iglu:vendor/name/format/version
• Property instructions help developers implement tracking correctly