In this article 

We explain what an "event schema" is and how to make updates to it.  We'll also cover troubleshooting any errors you may experience during this process.

What is a schema?

For Permutive, a schema is the organization of data collected through custom events and their properties. A further definition of what a schema is can be found here. The schema is unique per client and enables you to collect publisher-specific data points that you have available (i.e. through a data layer, API call, or user input). For more detailed information about custom events and properties, read our documentation here. Additionally, designing and updating your schema is an iterative process — you are not committed to it if you find that it needs to be modified in the future.

What is stored in the schema?

Below is an example schema followed by a breakdown of what is stored in each column. 

Column A - Event Name - The name of the event as it appears in the dashboard and in the code on-page.

Column B - Name - The name of the property in the event as it appears in the dashboard.

Column C, D, E - Level 1, 2, 3 - The pads to the leaf level property which gets translated into JSON format.

Column F - Type - The data type of the property.

Column G - Description - A brief description of the property and what it collects which appears in the dashboard.

Column H - Examples - Examples of values are expected which appear in the dashboard.

What events can be edited in the schema? 

Within the dashboard, you have access to both standard events and custom events. Standard events are available "out of the box" when you deploy our SDK. Custom events are events you choose to add to your deployment that are specific to your data collection needs. While custom events are editable, the only standard event that can be edited is the PageView event. You can add as many custom properties you feel are needed to the PageView event.

Note: Before adding a new custom event, please check with your CSM if you are unsure of the number of custom events you are contractually allowed to have within the Permutive platform. 

How to edit the schema?

Here is how each individual column in your schema should be edited:

Column A - Event Name - When adding a new custom event, you need to select a new row within the schema and select the Event Name cell. Enter the name of the event that you are adding properties to. How this appears in the schema is how it will be displayed in the dashboard. Once any changes have been pushed to production, the properties within the event cannot be edited or changed. So, be sure your properties' structure is entered correctly. If any mistakes or changes need to be made to these cells please follow the instructions here. 

Column B - Name - This is the dashboard name of the property you are adding. Because this value is only visible in the dashboard, you can edit it at any time, even if it's already in production. In the event of an edit, a production update (made by Technical Services) will still be needed.

Column C, D, E - Level 1, 2, 3 - The next 3 cells in the row is where the pads to your leaf level property should be added. These columns are also not editable once they have been pushed into production. If any mistakes or changes need to be made to these cells please follow the instructions here.

Column F - Type - This is the data type for the new custom property. This section is not editable and, as with previous sections, if any mistakes or changes need to be made to these cells please follow the instructions here. 

Column G - Description - This cell is not required, however, it is highly recommended. A brief description clarifies the property's purpose for the members of your team that are building cohorts.

Column H - Examples - Like the description, this cell is not required but highly recommended. Providing examples can illustrate what values are expected in that property. 

Once you validate your edits, please continue to the next section.

How to update the schema? 

Once edits have been made to the schema, you will then need to notify technical-services@permutive.com who will be able to push your changes to production. You should also see your specific deployment documentation update to reflect these changes.

How to make corrections to uneditable columns of the schema?

The following columns cannot be edited once they are pushed to production:

• Event Name
• Level 1, 2, 3
• Type 

If edits are needed for any of the above sections, we advise that you re-add the new custom event or custom property in a new row using a similar but different name (e.g. if "browserLanguage" is ascribed the wrong data type, add a new property like "browserLanguageString"). Once the new event or property has been added, please notify technical-services@permutive.com of the changes you have made and of the event or property that is incorrect. A member of the Technical Services team will be able to hide the old event or property from the dashboard so that cohorts are not accidentally built with it. Be sure to check within you team that you do not have any cohorts that are still dependent on that old property or event.

What happens if an event or property is not defined in the schema?

If you fire a custom event or property that has not been defined in your schema, it will be rejected and that entire event's data will not be collected. It is very important that any custom event or custom property is defined in the schema before any data is passed to it.

Troubleshooting schema errors

There are two key ways to troubleshoot schema errors:

1. Event Rejections Dashboard: This is the central way of checking for schema errors across all of your domains and platforms. To get access to your event rejections dash please contact your CSM/CP.
2. Chrome Browser Extension: This allows to you to pinpoint schema errors (among other errors) during your browsing experience on the web. Refer to this documentation for information on how to install and use the browser extension.