A single Semantic Event is a rich, self-contained JSON object designed to capture the complete context of a business occurrence. While its structure is comprehensive, it is logically organized into distinct components. This overview introduces each major component of the event schema to provide a high-level map for developers and data engineers.

Core Event Properties

These are the fundamental, top-level attributes that define the event itself. They answer the basic questions of what happened and when. This includes the event type (like track or identify), the specific event name, the timestamp, and unique identifiers like messageId and event_gid.

For detailed information, see Core Properties.

Identity & Session

This group of fields establishes who performed the action. It includes all identifiers necessary for user tracking and identity resolution, such as user_id for known users, anonymous_id for unknown visitors, and session_id to group events from a single browsing session. It also includes previous_id for linking identities after an alias call.

Standard Context Objects

To ensure broad compatibility and ease of use, our schema incorporates the standard context objects popularized by Segment.com. These are typically captured automatically by client-side libraries or enriched on the server. This includes detailed information about the user's environment, such as:

• context: General context like IP address and locale.
• device: Details about the user's device (e.g., model, manufacturer).
• os: The operating system.
• app: Information about the mobile application.
• network: Network carrier and connectivity details.
• page: For web events, the URL, path, and title of the page.
• screen: For mobile events, the name of the screen being viewed.
• campaign: Marketing attribution data (e.g., source, medium, term).

For complete details on these objects, see Basic Context Objects covering app, device, OS, page, screen, and campaign objects.

User & Group Traits

The traits object is a container for properties about the user (in an identify call) or a group (in a group call). This is where you store attributes like a user's name, email, subscription plan, or a company's industry and employee count.

Learn more about user traits in Traits.

Commerce

The commerce object is a powerful, deeply nested structure designed to capture every detail of an e-commerce transaction. It goes far beyond basic order information to include order and checkout IDs, revenue, tax, discounts, and payment details. Its most critical sub-component is the products array.

• Products: Each entry in the products array is a rich object describing a single product line item. It contains dozens of fields for detailed product identification (SKU, GTIN), classification (category, brand), pricing, and supply chain information (supplier, manufacturer).

For complete details, see Commerce covering transaction identifiers, transaction details, and financial summary, plus Products.

Context Suite Extended Properties

These proprietary objects are what elevate a standard event into a truly semantic one, enabling advanced operational intelligence.

• involves: An array that explicitly links any entity—a person, a product, a document—to the event, describing its specific role in the interaction.
• classification: An array used to categorize the event with tags, keywords, or business-specific intents (e.g., Intent: 'Purchase', Priority: 'High').
• sentiment: An array containing the results of sentiment analysis, linking positive, negative, or neutral sentiment to specific targets within the event.
• content: A dictionary for attaching any unstructured text associated with the event, such as the body of an email or the subject of a support ticket.
• location: An array for attaching one or more detailed geographical locations relevant to the event.

Custom Extensibility

For any data that doesn't fit into the predefined schema, we provide flexible map objects for custom data.

• properties: A generic key-value store for any custom properties related to a track event.
• dimensions: For custom, low-cardinality key-value pairs intended for dashboarding and filtering.
• metrics: For custom numerical key-value pairs.
• flags: For custom boolean flags.

Learn more about these flexible structures in Content and Properties and Dimensions and Metrics.

Data Governance & Processing

This final set of objects and fields provides metadata for data lifecycle management, access control, and directing internal processing logic. This includes access rules, a ttl_days (time-to-live) setting, and integrations flags to control which downstream systems should receive the event.

For details on governance features, see Governance and Processing.

Complete Component Reference

Explore the detailed documentation for each component:

Core Components:

• Core Properties - Event details and user identifiers
• Basic Context Objects - App, device, OS, page, and campaign context
• User & Group Traits - User profile and group information

Commerce & Products:

• Commerce - Transaction IDs, payment details, and financial summary
• Products - Rich product information and line items

Advanced Context:

• Entity Relationships - Explicit involvement and implicit linking
• Classification - Properties and common types
• Sentiment Analysis - Capture opinions and emotions
• Location - Geographic context and addresses

Custom Data:

• Content & Properties - Flexible text and structured data
• Dimensions & Metrics - Custom analytics dimensions

Data Management:

• Governance - Access control and data lifecycle
• Processing - Integration and analysis controls