This guide provides an overview of how to create, edit, and manage Experience Data Model (XDM) schemas for your organization in the Adobe Experience Platform UI.
XDM schemas are extremely customizable, and therefore the steps involved in creating a schema can vary depending on what kind of data you want the schema to capture. As a result, this document only covers the basic interactions you can make with schemas in the UI, and excludes related steps such as customizing classes, schema field groups, data types, and fields.
For a full tour of the schema creation process, follow along with the schema creation tutorial to create a complete example schema and familiarize yourself with the many capabilities of the Schema Editor.
This guide requires a working understanding of XDM System. Refer to the XDM overview for an introduction to the role of XDM within the Experience Platform ecosystem, and the basics of schema composition for an overview of how schemas are constructed.
This section covers how to manually create a new schema in the UI. If you are ingesting CSV data into Platform, you can opt to map that data to an XDM schema created by AI-generated recommendations (currently in beta) without having to manually create the schema yourself.
In the Schemas workspace, select Create schema in the top-right corner.
The Create schema workflow appears. You can choose a base class for the schema by selecting either Individual Profile, Experience Event, or Other, followed by Next to confirm your choice. See the XDM individual profile and XDM ExperienceEvent documentation for more information on these classes.
After you have selected a class, the Name and review section appears. In this section, you provide a name and description to identify your schema. The schema’s base structure (provided by the class) is shown in the canvas for you to review and verify your selected class and schema structure.
Enter a human-friendly Schema display name in the text field. Next, enter a suitable description to help identify your schema. When you have reviewed your schema structure and are happy with your settings, select Finish to create your schema.
The Schema Browse tab appears. Your recently created schema is now listed in the Schema Library and available to edit in the the Schema Editor.
Once a schema has been saved and used in data ingestion, only additive changes can be made to it. See the rules of schema evolution for more information.
To edit an existing schema, select the Browse tab, and then select the name of the schema you want to edit. You can also use the search bar to narrow the list of available options.
You can use the workspace’s search and filtering capabilities to help find the schema easier. See the guide on exploring XDM resources for more information.
Once you select a schema, the Schema Editor appears with the schema’s structure shown in the canvas. You can now add field groups to the schema (or add individual fields from those groups), edit field display names, or edit existing custom field groups if the schema employs any.
Within the Schema Editor you can also conduct quick actions to copy the JSON structure of the schema or delete the schema if it has not been enabled for Real-Time Customer Profile or has associated datasets. Select More at the top of the view to display a drop down with quick actions.
The Copy JSON structure functionality allows you to see what a sample payload would look like while you are still building the schema and your data pipelines. It is especially helpful for situations where there are complex object map structures in the schema such as an identity map.
For your convenience, the Schema Editor provides a toggle to change between the original field names and the more human-readable display names. This flexibility allows for improved field discoverability and editing of your schemas. The toggle is found at the top right of the Schema Editor view.
The change from field names to display names is purely cosmetic and does not change any downstream resources.
The display names for standard field groups are system generated but can be customized, as described in the display names section. Display names are reflected across multiple UI views, including mapping and dataset previews. The default setting is off, and shows field names by their original values.
This section covers how to add existing field groups to a schema. If you want to create a new custom field group, see the guide on creating and editing field groups instead.
Once you have opened a schema within the Schema Editor, you can add fields to the schema through the use of field groups. To start, select Add next to Field groups in the left rail.
A dialog appears, showing a list of field groups that you can select for the schema. Since field groups are only compatible with one class, only those field groups that are associated with the schema’s selected class will be listed. By default, listed field groups are sorted based on their usage popularity within your organization.
If you know the general activity or business area of the fields you want to add, select one or more of the industry-vertical categories in the left rail to filter the displayed list of field groups.
For more information on best practices for industry-specific data modeling in XDM, see the documentation on industry data models.
You can also use the search bar to help locate your desired field group. Field groups whose name matches the query appear at the top of the list. Under Standard Fields, field groups containing fields that describe desired data attributes are displayed.
Select the checkbox next to the name of the field group that you wish to add to the schema. You can select multiple field groups from the list, with each selected field group appearing in the right rail.
For any listed field group, you can hover or focus on the information icon () to view a brief description of the kind of data the field group captures. You can also select the preview icon () to view the structure of the fields that the field group provides before you decide to add it to the schema.
Once you have chosen your field groups, select Add field groups to add them to the schema.
The Schema Editor reappears with the field-group-provided fields represented in the canvas.
After you have added a field group to a schema, you can remove any fields that you do not need.
Removing fields from a field group only affects the schema being worked on and does not affect the field group itself. If you remove fields in one schema, those fields are still available in all other schemas that employ the same field group.
In the following example, the standard field group Demographic Details has been added to a schema. To remove a single field such as
taxId, select the field in the canvas and then select Remove in the right rail.
If there are multiple fields you wish to remove, you can manage the field group as a whole. Select a field belonging to the group in the canvas, then select Manage related fields in the right rail.
A dialog appears showing the structure of the field group in question. From here you can use the provided checkboxes to select or deselect the fields that you require. When you are satisfied, select Confirm.
The canvas reappears with only the selected fields present in the schema structure.
After you have added a field group to a schema, you can define additional fields for that group. However, any fields added to a field group in one schema will also appear in all other schemas that employ that same field group.
In addition, if a custom field is added to a standard field group, that field group will be converted to a custom field group and the original standard field group will no longer be available.
If you want to add a custom field to a standard field group, refer to the section below for specific instructions. If you are adding fields to a custom field group, refer to section on editing custom field groups in the field groups UI guide.
If you do not want to alter any existing field groups, you can create a new custom field group to define additional fields instead.
The Schema Editor allows you to add individual fields directly to a schema if you want to avoid adding an entire field group for a specific use case. You can add individual fields from standard field groups or add your own custom fields instead.
Even though the Schema Editor functionally allows you to add individual fields directly to a schema, this does not change the fact that all fields in an XDM schema must be provided by its class or a field group that is compatible with that class. As the sections below explain, all individual fields are still associated with a class or field group as a key step when they are added to a schema.
You can add fields from standard field groups directly to a schema without needing to know their corresponding field group beforehand. To add a standard field to a schema, select the plus (+) icon next to the schema’s name in the canvas. An Untitled Field placeholder appears in the schema structure and the right rail updates to reveal controls to configure the field.
Under Field name, start typing the name of the field you wish to add. The system automatically searches for standard fields that match the query and lists them under Recommended Standard Fields, including the field groups that they belong to.
While some standard fields share the same name, their structure may vary depending on the field group they come from. If a standard field is nested within a parent object in the field group structure, the parent field will also be included in the schema if the child field is added.
Select the preview icon () next to a standard field to view the structure of its field group and better understand how it might be nested. To add the standard field to the schema, select the plus icon ().
The canvas updates to show the standard field added to the schema, including any parent fields that it is nested under within the field group structure. The name of the field group is also listed under Field groups in the left rail. If you want to add more fields from the same field group, select Manage related fields in the right rail.
Similar to the workflow for standard fields, you can also add your own custom fields directly to a schema.
To add fields to the root level of a schema, select the plus (+) icon next to the schema’s name in the canvas. An Untitled Field placeholder appears in the schema structure and the right rail updates to reveal controls to configure the field.
Start typing in the name of the field you wish to add, and the system automatically starts searching for matching standard fields. To create a new custom field instead, select the top option appended with (New Field).
After providing a display name and data type for the field, the next step is to assign the field to a parent XDM resource. If your schema uses a custom class, you can choose to add the field to the assigned class or a field group instead. If your schema uses a standard class, however, you can only assign the custom field to a field group.
This section only covers how to assign the field to a custom field group. If you want to extend a standard field group with the new custom field instead, see the section on adding custom fields to standard field groups.
Under Assign to, select Field Group. If your schema uses a standard class, this is the only available option and is selected by default.
Next, you must select a field group for the new field to be associated with. Start typing in the name of the field group in the provided text input. If you have any existing custom field groups that match the input, they will appear in the dropdown list. Alternatively, you can type a unique name to create a new field group instead.
If you select an existing custom field group, any other schemas that employ that field group will also inherit the newly added field after you save your changes. For this reason, only select an existing field group if you want this type of propagation. Otherwise, you should opt to create a new custom field group instead.
After selecting the field group from the list, select Apply.
The new field is added to the canvas, and is namespaced under your tenant ID to avoid conflicts with standard XDM fields. The field group that you associated the new field with also appears under Field groups in the left rail.
The rest of the fields provided by the selected custom field group are removed from the schema by default. If you want to add some of these fields to the schema, select a field belonging to the group and then select Manage related fields in the right rail.
Under Assign to, select Class. The input field below is replaced with the name of the current schema’s custom class, indicating that the new field will be assigned to this class.
Continue configuring the field as desired and select Apply when finished.
The new field is added to the canvas, and is namespaced under your tenant ID to avoid conflicts with standard XDM fields. Selecting the class name in the left rail reveals the new field as part of the class’ structure.
If the schema you are working on has an object-type field provided by a standard field group, you can add your own custom fields to that standard object.
Any fields added to a field group in one schema will also appear in all other schemas that employ that same field group. In addition, if a custom field is added to a standard field group, that field group will be converted to a custom field group and the original standard field group will no longer be available.
If you participated in the beta for this feature, you will receive a dialog informing you of the standard field groups that you have previously customized. Once you select Acknowledge, the listed resources are converted to custom field groups.
To start, select the plus (+) icon next to the root of the object provided by the standard field group.
A warning message appears, prompting you to confirm whether you want to convert the standard field group. Select Continue creating field group to proceed.
The canvas reappears with an untitled placeholder for the new field. Note that the name of the standard field group has been appended with “(Extended)” to indicate that it has been modified from the original version. From here, use the controls in the right rail to define the field’s properties.
After applying your changes, the new field appears under your tenant ID namespace within the standard object. This nested namespace prevents field-name conflicts within the field group itself in order to avoid breaking changes in other schemas that use the same field group.
Real-Time Customer Profile merges data from disparate sources to construct a complete view of each individual customer. If you want the data captured by a schema to participate in this process, you must enable the schema for use in Profile.
In order to enable a schema for Profile, it must have a primary identity field defined. See the guide on defining identity fields for more information.
To enable the schema, start by selecting the schema’s name in the left rail, then select the Profile toggle in the right rail.
A popover appears, warning you that once a schema has been enabled and saved, it cannot be disabled. Select Enable to continue.
The canvas reappears with the Profile toggle enabled.
Since the schema is not saved yet, this is the point of no return if you change your mind about letting the schema participate in Real-Time Customer Profile: once you save an enabled schema, it can no longer be disabled. Select the Profile toggle again to disable the schema.
To finish the process, select Save to save the schema.
The schema is now enabled for use in Real-Time Customer Profile. When Platform ingests data into datasets based on this schema, that data will be incorporated into your amalgamated Profile data.
Once you have assigned a class and added field groups to a schema, you can edit the display names of any of the schema’s fields, regardless of whether those fields have been provided by standard or custom XDM resources.
Keep in mind that the display names of fields that belong to standard classes or field groups can only be edited in the context of a specific schema. In other words, changing the display name of a standard field in one schema does not affect other schemas that employ the same associated class or field group.
Once you make changes the display names for a schema’s fields, those changes are immediately reflected in any existing datasets based on that schema.
To edit the display name of a schema field, select the field in the canvas. In the right rail, provide the new name under Display name.
Select Apply in the right rail, and the canvas updates to show the field’s new display name. Select Save to apply the changes to the schema.
You can change the class of a schema at any point during the initial composition process before the schema has been saved.
Reassigning the class for a schema should be done with extreme caution. Field groups are only compatible with certain classes, and therefore changing the class will reset the canvas and any fields you have added.
To reassign a class, select Assign in the left-hand side of the canvas.
A dialog appears that displays a list of all available classes, including any defined by your organization (the owner being “Customer”) as well as standard classes defined by Adobe.
Select a class from the list to display its description on the right-hand side of the dialog. You can also select Preview class structure to see the fields and metadata associated with the class. Select Assign class to continue.
A new dialog opens, asking you to confirm that you wish to assign a new class. Select Assign to confirm.
After confirming the class change, the canvas will be reset and all composition progress will be lost.
This document covered the basics of creating and editing schemas in the Platform UI. It is strongly recommended that you review the schema creation tutorial for a comprehensive workflow for building a complete schema in the UI, including creating custom field groups and data types for unique use cases.
For more information on the capabilities of the Schemas workspace, see the Schemas workspace overview.
To learn how to manage schemas in the Schema Registry API, see the schemas endpoint guide.