> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating & Updating Event Schema

> How to add new events and event properties using your schema Google Sheet

## Overview

In Permutive, an **event schema** defines the structure of data collected through events and their properties. Designing your schema is an iterative process. You are not locked into an initial configuration -- schemas can be extended over time as your data collection needs evolve.

Permutive **enforces** schemas at ingestion time to ensure data consistency. Events that do not conform to the defined schema are rejected entirely.

## Schema Structure

Your event schema is managed in a **Google Sheet** that is shared with your organization and the Permutive team. Below is an example of what the schema sheet looks like:

<Frame>
  <img src="https://mintcdn.com/permutive/Vor1eZW_32cAizrz/images/guides/connectivity/event-schema-google-sheet.png?fit=max&auto=format&n=Vor1eZW_32cAizrz&q=85&s=7c6b0dc448f620a0736037006137e918" alt="Example event schema Google Sheet" width="2286" height="546" data-path="images/guides/connectivity/event-schema-google-sheet.png" />
</Frame>

Each row in the sheet represents a single property within an event. The columns are:

| Column      | Field             | Description                                                                                                                                            | Editable After Production? |
| :---------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------- |
| **A**       | **Event Name**    | The name of the event as it appears in the Dashboard and in your on-page tracking code. Do not use special characters and spaces.                      | No                         |
| **B**       | **Name**          | The display name of the property as it appears in the Dashboard. Spaces are allowed.                                                                   | Yes                        |
| **C, D, E** | **Level 1, 2, 3** | The path to the leaf-level property, which translates directly into the JSON structure of the event payload. Do not use special characters and spaces. | No                         |
| **F**       | **Type**          | The data type of the property (e.g., String, Boolean, List of Strings).                                                                                | No                         |
| **G**       | **Description**   | A brief explanation of what the property captures. Not required, but strongly recommended for team clarity.                                            | Yes                        |
| **H**       | **Examples**      | Sample values illustrating expected input. Not required, but strongly recommended.                                                                     | Yes                        |

### How the Level Columns Map to JSON

The Level 1, 2, and 3 columns define where a value lives in the nested JSON payload sent to Permutive. For example, the "Authors" row in the screenshot above has `article` in Level 1 and `authors` in Level 2, which translates to:

```json theme={"dark"}
{
  "article": {
    "authors": ["Jane Doe", "John Smith"]
  }
}
```

A property like "Page Type" with only `page_type` in Level 1 and no deeper nesting translates to:

```json theme={"dark"}
{
  "page_type": "article"
}
```

### Full Event Payload Example

Below is an example of a **Pageview** event custom payload based on the schema shown above:

```json theme={"dark"}
{
  "page_type": "article",
  "article": {
    "authors": ["Jane Doe"],
    "title": "Understanding First-Party Data"
  },
  "tags": ["news", "data-strategy"],
  "user": {
    "logged_in": true,
    "subscription": true
  }
}
```

## Which Events Can Be Edited?

Permutive provides two categories of events:

**Standard events** are collected automatically when you deploy the SDK. These include Pageview, Engagement, and Video events. Of the standard events, only the **Pageview** event schema can be extended with custom properties. You can add as many custom properties as needed to the Pageview event.

**Custom events** are events you define to track behaviors specific to your data collection needs. Using the SDK function `permutive.track()`, you can track custom events:

```javascript theme={"dark"}
permutive.track('EventName', {
  property: 'value'
});
```

<Note>
  Before adding a new custom event, confirm with your Customer Success Manager (CSM) that your contract allows additional custom events on the platform.
</Note>

## How to Edit the Schema

All schema changes are made in your **Google Sheet**. Here is how each column should be edited:

**Event Name (Column A)** -- When adding a new custom event, select a new row and enter the event name. How it appears in the sheet is how it will be displayed in the Dashboard. Avoid special characters. Once changes have been pushed to production, the event name cannot be changed.

**Name (Column B)** -- This is the Dashboard display name of the property. Because this value is only visible in the Dashboard, you can edit it at any time, even if it is already in production. A production update will still be needed for changes to take effect.

**Level 1, 2, 3 (Columns C, D, E)** -- Enter the path to your leaf-level property. These columns are **not editable** once pushed to production.

**Type (Column F)** -- The data type for the property. This is **not editable** once pushed to production.

**Description (Column G)** -- Not required, but highly recommended. A brief description clarifies the property's purpose for team members building cohorts.

**Examples (Column H)** -- Not required, but highly recommended. Providing examples illustrates what values are expected for the property.

<Warning>
  Be sure your property structure is entered correctly before requesting a production push. Event names, level paths, and data types cannot be changed after they are live.
</Warning>

## How to Push Schema Changes to Production

Once you have finished editing your schema in the Google Sheet:

<Steps>
  <Step title="Validate your edits">
    Review all new or modified rows to ensure event names, property paths, and data types are correct. Once pushed to production, these fields cannot be changed.
  </Step>

  <Step title="Notify Permutive">
    Contact [Support](mailto:technical-services@permutive.com) to request that your changes be pushed to production.
  </Step>

  <Step title="Verify the update">
    After the update has been applied, your deployment documentation will be updated to reflect the changes. Use the *Events* menu item in the Dashboard or the Permutive Chrome Extension to verify the new properties are being collected correctly.
  </Step>
</Steps>

## Correcting Published Properties

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

* Event Name
* Level 1, 2, 3 (property path)
* Type

If corrections are needed for any of these:

<Steps>
  <Step title="Add a new row in the Google Sheet">
    Re-add the custom event or property in a new row using a similar but distinct name. For example, if `browserLanguage` has the wrong data type, add a new property called `browserLanguageString` with the correct type.
  </Step>

  <Step title="Notify Permutive of the correction">
    Contact [Support](mailto:technical-services@permutive.com) with details of the changes you made and which event or property is incorrect. A member of the Technical Services team will hide the old event or property from the Dashboard so that cohorts are not accidentally built with it.
  </Step>

  <Step title="Update your tracking code">
    Update your implementation to send data under the new property name.
  </Step>

  <Step title="Check for dependent cohorts">
    Verify with your team that no existing cohorts depend on the old property or event before fully deprecating it.
  </Step>
</Steps>

## Schema Enforcement and Validation

Permutive enforces event schemas strictly. When an event is tracked, the payload is validated against your published schema. If the payload does not match, the **entire event is rejected** and no data from that event is collected.

This means:

* Every property in the payload must be defined in the schema.
* Every property value must match its declared data type.
* 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.

<Warning>
  A single invalid property in an event payload will cause the entire event to be rejected -- not just the invalid property. Always ensure any custom event or property is defined in the schema before passing data to it.
</Warning>

## Troubleshooting

There are two key ways to identify schema errors:

* **Event Rejections Dashboard** -- The central way of checking for schema errors across all of your domains and platforms. Contact your CSM to get access to your event rejections dashboard.
* **Permutive Chrome Extension** -- Pinpoint schema errors during your browsing experience on the web. The extension displays each event payload and flags validation errors as they occur.

### Common Validation Errors

<AccordionGroup>
  <Accordion title="Undefined property error">
    A property in the event payload is not defined in the schema.

    **Solution**: Add the property to your schema in the Google Sheet and request a production push, or remove the property from your tracking code.
  </Accordion>

  <Accordion title="Data type mismatch">
    A property value does not match the expected type (e.g., sending a string where a number is expected).

    **Solution**: Review the Type column in your schema Google Sheet and update your tracking code to send the correct type.
  </Accordion>

  <Accordion title="Null or undefined required property">
    A required property is missing or has a `null`/`undefined` value.

    **Solution**: Ensure your data layer or tracking logic always provides a valid value for required fields. Consider delaying event tracking until required data is available.
  </Accordion>

  <Accordion title="Property name typo or case mismatch">
    Property names are case-sensitive. For example, `articleTitle` and `articletitle` are treated as different properties.

    **Solution**: Compare property names in your tracking code against the Level columns in your schema Google Sheet character by character.
  </Accordion>

  <Accordion title="Event or property not defined in the schema">
    If you fire a custom event or property that has not been defined in your schema, the entire event is rejected and no data is collected.

    **Solution**: Ensure any custom event or property is defined in the schema Google Sheet and pushed to production before data is passed to it.
  </Accordion>
</AccordionGroup>

### Recommended Debugging Workflow

1. **Reproduce the issue** on a page where the event should fire.
2. **Open the Permutive Chrome Extension** and check whether the event appears and whether any errors are flagged.
3. **Inspect the browser console** for network errors (HTTP 400 responses) on requests to Permutive.
4. **Compare the event payload** in the network request against your schema definition in the Google Sheet.
5. **Correct the tracking code** or **update the schema** as needed.
6. **Verify the fix** by reloading the page and confirming the event is accepted without errors.

## Quick Reference

* You can always **add** new properties to your schema via the Google Sheet.
* **Event names**, **level paths**, and **data types** are immutable after being pushed to production.
* **Property display names**, **descriptions**, and **examples** can be edited at any time.
* Events with payloads that do not match the schema are **rejected entirely**.
* To correct an immutable field, create a new property in the Google Sheet and contact Support to hide the old one.
* All schema changes must be pushed to production by the Permutive Technical Services team.

## Next Steps

<CardGroup cols={2}>
  <Card title="Events" icon="bolt" href="/products/connectivity/events">
    Learn more about standard and custom events in Permutive
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:technical-services@permutive.com">
    Get help with schema changes or troubleshooting
  </Card>
</CardGroup>