Event type schemas

Learn about event type schemas in the Loyalty Engine and how they define the structure of event payloads. Includes example schemas for common event types.

Event type schemas are essential for defining the structure of the data (payload) that accompanies each reported event in the Loyalty Engine. The schema ensures that the payload contains all the required fields, in the correct format, before the event is processed. This validation helps ensure that the event triggers the appropriate reactions or other actions within your loyalty program.

For example, in a purchase event, the schema could define fields such as transaction ID, total amount, and item SKUs. Each of these fields would need to be present and properly formatted in the payload to ensure the event is valid and can be processed correctly by the Loyalty Engine.

---

Define an event type's schema

The schema for an event type is configured in the event type settings within the Loyalty Console. It is also used to define which properties appear in the block builder when creating or editing reactors, helping you to easily apply conditions based on the event’s payload data.

Defining a schema in an event type's settings in the Loyalty Console

Schema represented in the GUI block editor in a reactor config in the Loyalty Console

---

Event type schema format

When creating an event type, the event payload schema must follow JSON Schema Draft 6. The schema defines the structure and data types for the event payload, ensuring that the reported event contains all the required information in the correct format.

Below are the key components supported in JSON Schema Draft 6 that you can use when defining your event schemas:

Supported JSON Schema Components

• type: This should always be set to "object" for event payloads, as the payload will consist of multiple key-value pairs (properties).

• required: This defines which of the properties must be present in the event payload for it to be considered valid. Any properties listed here must be included in the payload when the event is reported.

• properties: This section defines all the key-value pairs expected in the event payload. For each property, you can specify:

  • title: A descriptive name for the property (useful for documentation purposes).

  • description: A short explanation of what the property represents, providing additional context.

  • type: The type of data the property holds. Supported types include "string", "number", "boolean", "array", and "object".

  • items: If the property is an array, this specifies the types or schema of the items within that array.

  • pattern: A regular expression (regex) that the property’s value must match. This is commonly used for fields like email addresses or phone numbers that require specific formatting.

  • const: Specifies a constant value that the property must always have (useful if the field needs a fixed value across all events of this type).

  • enum: Defines a set of allowed values for the property. For example, "status": { "enum": ["active", "inactive"] } would ensure that the value for the status field is either "active" or "inactive".

---

Example event type schemas

Here are a few example JSON Draft 6 schemas for common event types:

New Transaction Event (e.g. TRANSACTION_COMPLETED)

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "string"
    },
    "total_amount": {
      "type": "number",
      "minimum": 0
    },
    "items_purchased": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "purchase_channel": {
      "type": "string",
      "enum": ["online", "in-store"]
    }
  },
  "required": ["transaction_id", "total_amount", "items_purchased", "purchase_channel"]
}

Completed Survey Event (e.g. COMPLETED_SURVEY)

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "type": "object",
  "properties": {
    "survey_id": {
      "type": "string"
    },
    "questions_answered": {
      "type": "integer",
      "minimum": 0
    },
    "completion_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    }
  },
  "required": ["survey_id", "questions_answered", "completion_score"]
}

New Subscription Event (e.g. SUBSCRIPTION_STARTED)

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "type": "object",
  "properties": {
    "subscription_plan": {
      "type": "string"
    },
    "subscription_start_date": {
      "type": "string",
      "format": "date"
    },
    "auto_renew": {
      "type": "boolean"
    }
  },
  "required": ["subscription_plan", "subscription_start_date"]
}

---

Event type schema best practices

• Do not include personally identifiable information: when a user account is deleted, their corresponding events are not deleted. As such, we advise against including PII in event payloads. PII should only be sent when calling the Register or Update user API endpoints.

• Ensure completeness: Include all the necessary fields that will be needed to trigger reactors and other processes.

• Validate data types: Use the appropriate data types (e.g., string, number, boolean) for each property.

• Optional vs. required fields: Clearly define which fields are required and which are optional. This ensures that the event can still be processed even if some optional data is missing.

• Structure for usability: Design the schema so it’s easy to understand and use when creating reactors and other platform actions.

When creating custom event types, think carefully about the data you need to capture. Remember, the schema not only helps validate the event payload but also determines what data will be available for use in reactor conditions and any bespoke analytics you may commission from WLL.

---

FAQs

Is specifying a schema for an event type required?

No, adding a schema is entirely optional. However, without a schema, any data will be accepted when the event is reported, which can lead to inconsistencies. Additionally, when creating reactors for that event type, the block-builder GUI will not be available, meaning you’ll need to write manual JSON conditions for any payload-based criteria.

What happens if I report an event to the Loyalty Engine that does not match the specified schema?

If an event payload does not match the defined schema for that event type, the event will fail validation and will not be accepted by the Loyalty Engine. You will receive an error response explaining which part of the payload is invalid. This ensures that only correctly formatted data is processed by the system.

Can I update the schema for an event type after it’s created?

Yes, you can modify the schema for an existing event type. If you change the schema, events reported with the new schema must still comply with the updated structure.

Is it mandatory to define every property in an event payload?

No, you can choose which properties to define as required. Non-required properties can be omitted from the payload if they are not relevant to a specific event, but required properties must always be included.

Can I define complex structures in the schema, like nested objects or arrays?

Yes, the schema can support complex structures, including nested objects and arrays. You can define sub-properties within objects or specify the types of items in an array using the properties and items components.

What should I do if I need to report events of the same type from multiple systems (e.g., CRM and e-commerce)?

Ensure that all systems use the same event type schema for consistency. The schema should be flexible enough to accommodate the data from each system, but every system must follow the same structure to avoid validation errors.

If aligning all systems to a single schema isn’t feasible, consider using a middleware service to normalize and map the data into the correct format before passing it to the Loyalty Engine.

What happens if I omit optional fields in the payload?

Optional fields do not need to be included in the payload. The Loyalty Engine will still accept the event as long as all required fields are present and the payload matches the schema.

Is there a limit to how many properties can be defined in the schema?

While there is no strict limit, it is recommended to keep the schema manageable and only include properties that are necessary for processing the event. Adding too many properties can complicate validation and event processing.