Create and edit schemas in the UI
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.
Prerequisites
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.
Create a new schema create
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.
Edit an existing schema edit
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.
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.
More actions more
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.
Display name toggle display-name-toggle
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 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.
Add field groups to a schema add-field-groups
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.
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.
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 adding a field group to a schema, you can optionally remove existing fields or add new custom fields to those groups, depending on your needs.
Remove fields added from field groups remove-fields
After you have added a field group to a schema, you can remove any fields that you do not need.
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.
Add custom fields to field groups add-fields
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.
Add individual fields to a schema add-individual-fields
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.
Add standard fields add-standard-fields
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.
Add custom fields add-custom-fields
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.
Assign the field to a custom field group add-to-field-group
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.
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.
Assign the field to a custom class add-to-class
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.
Add custom fields to the structure of standard field groups custom-fields-for-standard-groups
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.
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.
Enable a schema for Real-Time Customer Profile profile
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.
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.
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.
Edit display names for schema fields display-names
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.
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.
Change a schema’s class change-class
You can change the class of a schema at any point during the initial composition process before the schema has been saved.
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.
Next steps
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.