Data Schema Management Overview

The Data Schema Management screen in Iterable is a place for you to manage custom events, user profile fields, and purchase fields in a project’s data schema.

Overall, Data Schema Management enables you to maintain good data hygiene in your Iterable projects so that you can stay focused on value-added marketing activities.

This article provides an overview of Data Schema Management and explains how to use it to manage your project's data schema.

# In this article

# Required permissions

Users who have the Manage Settings project permission can access the Data Schema Management screen to view and manage a project's data schema and data management settings.

On this page, you can:

• View all custom events, custom event fields, user profile fields, and purchase fields in your project.
• Create new fields for custom events, user profiles, and purchase events directly from the app.
• Hide fields that you don’t need to use in segmentation, journey filters, or template editors.
• Manage whether custom events are shown in the app and whether they can be tracked.
• Control how Iterable handles unrecognized fields and events in your project and add new ones only when you want to.

# Data schema limits

Iterable has the following limits for a project's data schema:

• User profile fields: 1000 fields
• Custom event fields: 8000 fields

To avoid reaching these limits, it's important to manage your fields carefully and prevent accidental creation of incorrect fields. Iterable doesn't have a function for deleting fields.

If your project reaches a field limit, contact your customer success manager to discuss available options.

# Protecting a project's data schema

Data Schema Management settings allow you to control how Iterable handles unrecognized fields and events so that you can add new ones only when you want to.

A field or event is unrecognized by Iterable if it doesn't already exist in a project. If an API request or list upload includes a field or event name that isn’t yet listed in Data Schema Management, then that field or event would be unrecognized by Iterable.

By default, Iterable adds unrecognized fields and events to your project. You can disable this behavior by changing the unrecognized field settings in Data Schema Management.

While Iterable rejects unrecognized fields and events, you must add them manually in Data Schema Management when you want to make changes to the schema. This ensures that your project's data schema remains clean and consistent.

To access these settings, go to Settings > Data Schema Management and open the Settings tab.

Purchase fields are not affected by these settings. Iterable always allows unrecognized purchase fields and creates them automatically.

# Allowing or dropping unrecognized user profile fields

Select one of these settings for your project:

• Allow unrecognized user fields (default)

  Unrecognized fields are created when performing a list upload or API call.

• Drop unrecognized user fields

  Unrecognized fields are dropped when performing a list upload or API call.

  While user profile fields are locked, API requests and list uploads that update users include unrecognized fields do succeed, however the unrecognized fields are rejected.

  IMPORTANT

  The Drop unrecognized user fields setting doesn't impact User Profile tiles in Journeys. This tile can always add unrecognized user profile fields.

# Allowing or dropping custom events and event fields

Select one of these settings for your project:

• Allow unrecognized custom events and event fields (default)

  Unrecognized custom events and event fields are created automatically.

• Drop unrecognized custom events, allow unrecognized event fields

  Unrecognized custom events are blocked, but unrecognized event fields are created automatically. API requests with an unrecognized event name fail and no data is recorded.

• Drop unrecognized custom events and event fields

  Unrecognized custom events and event fields are dropped.

  When custom events and event fields are locked, API requests with an unrecognized event name fail and no data is recorded. API requests with a known event name but an unrecognized field name are accepted, but the unrecognized field is dropped.

# Overriding data schema settings in API calls

Data Schema Management settings impact these APIs:

• Events:

  • POST /api/events/track
  • POST /api/events/trackBulk

• Users:

  • POST /api/users/update
  • POST /api/users/bulkUpdate

• Commerce:

  • POST /api/commerce/updateCart
  • POST /api/commerce/trackPurchase

The response bodies for these endpoints indicate when an unrecognized field is allowed or dropped. Control this behavior by using the optional createNewFields parameter, and/or the project's setting to allow or drop fields.

ThecreateNewFields parameter accepts Boolean values and behaves literally when overriding Data Schema Management settings. To allow creation of new fields, assign a true value. To drop new fields and protect the data schema, assign a false value.

When the parameter isn’t included in an API request, Iterable defaults to the project’s field lock settings to determine whether unrecognized fields can be added. Therefore, you only need to include createNewFields when you need to override the project's field lock settings.

# Client-side API keys and event creation

Accounts created after August 29, 2022 require client-side API keys to have permission in order to send unrecognized events and add them to the project. If you need to create an event using a client-side API key:

• The project must have the Allow unrecognized custom events and event fields setting enabled, or the API call must have an optional createNewFields parameter set to true. To learn more, read Overriding data schema settings in API calls.

• The API key must have the Event creation permission enabled.

  To learn more about this permission for client-side API keys, read API Keys.

# Managing data schemas in Iterable

In the Data Schema Management screen, you can view and manage custom events, user profile fields, and purchase fields in your project.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Product Bite: Data Schema Management Tools

Support docs

To understand the kinds of data types you can create and how to name fields for Iterable, read these articles:

• Field Data Types
• Best Practices for Field Names and Event Names

To learn more about managing custom events, user profiles, and purchase events in the Data Schema Management screen, read these articles:

• Managing Custom Events
• Managing User Profile Fields in Iterable
• Managing Commerce Events and Shopping Cart Items