Define XDM fields in the UI

Last update: January 13, 2025

CREATED FOR:

  • Developer

The Schema Editor in the Adobe Experience Platform user interface allows you to define your own fields within custom Experience Data Model (XDM) classes and schema field groups. This guide covers the steps for defining XDM fields in the UI, including the available configuration options for each field type.

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 to learn how classes and field groups contribute fields to XDM schemas.

While not required for this guide, it is recommended that you also follow the tutorial on composing a schema in the UI to familiarize yourself with the various capabilities of the Schema Editor.

Select a resource to add fields to

To define new XDM fields in the UI, you must first open a schema within the Schema Editor. Depending on what schemas are currently available to you in the Schema Library, you can choose to create a new schema or select an existing schema to edit.

Once you have the Schema Editor open, controls to add fields appear in the canvas. These controls appear next to the name of the schema, as well as any object-type fields that have been defined under the selected class or field group.

The Schema Editor with the add icons highlighted.

WARNING
If you attempt to add a field to an object that is provided by a standard field group, that field group will be converted to a custom field group and the original field group will no longer be available. See the section on adding fields to standard field groups in the schemas UI guide for more information.

To add a new field to the resource, select the plus (+) icon next to the schema’s name in the canvas, or next to the object-type field that you want to define the field under.

The Schema Editor with an add icon highlighted.

Depending on whether you are adding a field directly to a schema or its constituent class and field groups, the required steps to add the field will vary. The remainder of this document focuses on how to configure a field’s properties regardless of where that field appears in the schema. For more information on the different ways that fields can be added to a schema, refer to the following sections in the schemas UI guide:

Define the properties of a field

After selecting the plus (+) icon, an Untitled field placeholder appears in in the canvas.

The Schema Editor with a new untitled field highlighted.

In the right rail under Field properties, you can configure the details of the new field. The following information is required for each field:

Field propertyDescription
Field name

A unique, descriptive name for the field. Note that the field’s name cannot be changed once the schema has been saved. This value is used to identify and reference the field in code and in other downstream applications

The name should ideally be written in camelCase. It may contain alphanumeric or underscore characters, but it may not start with an underscore.

  • Correct: fieldName
  • Acceptable: field_name2, fieldName_3
  • Incorrect: _fieldName
Display nameA display name for the field. This is the name that will be used to represent the field within the Schema Editor canvas. The field name can be changed to the display name using the display name toggle.
TypeThe type of data the field will contain. From this dropdown menu, you can select one of the standard scalar types supported by XDM, or one of the multi-field data types that have been previously defined in the Schema Registry.
Note: If you select the Map data type, then Map value type property appears.

You can also select Advanced type search to search and filter existing data types and locate the desired type easier.
Map value typeThis value is required if you select Map as the data type for the field. Available values for the map are String and Integer. Select a value from the drop down list of available options.
To learn more about type-specific field properties, see the define fields overview.

You can also choose to provide a description and notes for each field. Use the Description field to add context and describe the functionality of the map data type. This contributes to the maintainability and readability of the implementation. You can also add notes to complement the initial description. This should offer more granular and specific information to help developers in understanding, maintaining, and utilizing the map effectively within the context of the codebase. |

NOTE
Depending on the Type you selected for the field, additional configuration controls may appear in the right rail. See the section on type-specific field properties for more information on these controls.
The right rail also provides checkboxes for designating special field types. See the section on special field types for more information.

Once you have finished configuring the field, select Apply.

The Field properties section of the Schema Editor is highlighted.

The canvas updates to show the newly added field, located within an object that is namespaced to your unique tenant ID (shown as _tenantId in the example below). All custom fields that are added to a schema are automatically placed within this namespace to prevent conflicts with other fields from Adobe-provided classes and field groups. The right rail now lists the field’s path in addition to its other properties.

A new field in the schema diagram and its corresponding path in the Field properties section is highlighted.

You can continue to follow the steps above to add more fields to the schema. Once the schema is saved, its base class and field groups are also saved if any changes have been made to them.

NOTE
Any changes you make to the field groups or class of one schema will be reflected in all other schemas that employ them.

Type-specific field properties

When defining a new field, additional configuration options may appear in the right rail depending on the Type you choose for the field. The following table outlines these additional field properties along with their compatible types:

Field propertyCompatible typesDescription
Map value typeMapThe Map value type property only appears in the UI if you select the Map value from the Type dropdown options. You can select between String and Integer value types for the Map.
The Schemas Editor with the Type and Map value type fields highlighted.
Note: Any map data types created through the API that are not either a String or an Integer type are displayed as a ‘Complex’ data type. You cannot create ‘Complex’ data types through the UI.
PatternStringA regular expression that the value for this field must conform to in order to be accepted during ingestion.
FormatString

Select from a list of pre-defined formats for strings that the value must conform to. Available formats include:

Minimum lengthStringThe minimum number of characters the string must contain for the value to be accepted during ingestion.
Maximum lengthStringThe maximum number of characters the string must contain for the value to be accepted during ingestion.
Minimum valueDoubleThe minimum value for the Double to be accepted during ingestion. If the ingested value exactly matches the one entered here, then the value is accepted. When using this constraint, the “Exclusive minimum value” constraint must be left blank.
Maximum valueDoubleThe maximum value for the Double to be accepted during ingestion. If the ingested value exactly matches the one entered here, then the value is accepted. When using this constraint, the “Exclusive maximum value” constraint must be left blank.
Exclusive minimum valueDoubleThe maximum value for the Double to be accepted during ingestion. If the ingested value exactly matches the one entered here, then the value is rejected. When using this constraint, the “Minimum value” (non-exclusive) constraint must be left blank.
Exclusive maximum valueDoubleThe maximum value for the Double to be accepted during ingestion. If the ingested value exactly matches the one entered here, then the value is rejected. When using this constraint, the “Maximum value” (non-exclusive) constraint must be left blank.