Content & Other Properties

While the Semantic Event schema is designed to be comprehensive and structured, real-world data is often messy and unpredictable. To accommodate this, the schema includes two powerful, flexible properties for capturing unstructured text and custom structured data: content and properties. These serve as the primary mechanisms for extending an event beyond the standard fields, ensuring no valuable information is ever lost.

The content Property

The content property is a dictionary specifically designed to hold significant blocks of text associated with an event. This is where you would place the raw, unstructured text that is often the subject of the event itself, such as the body of an email, the description of a support ticket, or the content of a user-generated comment.

By structuring text this way, you make it immediately available for downstream processes like Natural Language Processing (NLP), sentiment analysis, and automated entity linking. The keys of the dictionary should be descriptive of the text they contain.

For example, an event for a Support Ticket Submitted might have a content object like this:

1{
2  "subject": "Issue with my recent order",
3  "body": "Hello, I received order #ORD-12345 today but one of the items was damaged. Can you please assist? Thank you.",
4  "quick_response_suggestion": "Acknowledge damaged item and create replacement order."
5}

The properties Property

The properties property is the ultimate "capture-all" container. It is a flexible dictionary intended for any custom data that does not fit into the standardized fields of the Semantic Event schema. This is the ideal place for application-specific attributes, experimental data, or any unique information you need to record with an event.

Its true power lies in its ability to store richly structured, nested JSON objects. Our data store, built on ClickHouse, has highly efficient native support for JSON, meaning you can store complex data within the properties field and still query it effectively without significant performance degradation. This avoids the common pitfall of flattening complex objects into strings, preserving their structure and analytical value.

For example, a Game Level Completed event might include custom properties specific to that game:

1{
2  "levelName": "Crystal Caverns",
3  "timeCompletedSeconds": 183,
4  "starsEarned": 3,
5  "character": {
6    "class": "Mage",
7    "healthRemaining": 85,
8    "itemsUsed": ["health_potion", "mana_crystal"]
9  }
10}