Event Schemas
Event Schemas enforce payload structure on a per-event-type basis, improve data quality, and give the AI builder better context for generating segments.
What Are Event Schemas?#
An Event Schema is a named set of property definitions that describes the expected shape of an event's payload. Once you register a schema for an event type, the ingestion pipeline validates every incoming event of that type against the schema.
Schemas are optional but recommended. They help you:
- Catch schema drift early (a deploy changed a property name, breaking segments)
- Document your event vocabulary for the whole team
- Improve AI segment generation accuracy
Creating a Schema#
- Navigate to Settings → Schemas
- Click + New Schema
- Enter the event_type this schema applies to (e.g.,
order_placed) - Add property definitions using the table editor
- Click Save Schema
Defining Properties#
Each property in a schema has three attributes:
| Attribute | Description |
|---|---|
| name | The payload key (e.g., total, currency, order_id) |
| type | One of: string, number, boolean, datetime, array |
| required | If true, events missing this property will be skipped during ingestion |
Schema Enforcement During Ingestion#
When an event arrives for an event type that has a registered schema:
- The ingestor looks up the schema for the event type
- Required properties are checked — if any are missing, the event is skipped
- Type coercion is attempted for numeric and boolean properties
- Unknown properties are passed through (they are not stripped)
Check the Ingestion → Recent Errors page to see schema violations. Each error record includes the event timestamp, event type, and the specific validation failure.
Schema-Aware AI Builder#
When you use the AI segment builder, SegOps automatically injects the registered schemas for your tenant into the AI's context. This allows the model to:
- Use exact property names from your schema (e.g.,
totalvsamount) - Infer the correct metric for monetary conditions (sum vs avg)
- Understand which event types carry which properties
- Avoid suggesting conditions that reference non-existent properties
Schema Versioning and Editing#
Schemas can be edited at any time from Settings → Schemas. There is no automatic versioning — edits take effect immediately on the next ingest call. If you need to add a new required property, be aware that all future events without that property will be dropped until your sending code is updated.