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.
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.
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.
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.
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:
After selecting the plus (+) icon, an Untitled field placeholder appears in in the canvas.
In the right rail under Field properties, you can configure the details of the new field. The following information is required for each field:
|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, dash, or underscore characters, but it may not start with an underscore.
|A 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.
|The 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.
You can also select Advanced type search to search and filter existing data types and locate the desired type easier.
You can also provide an optional human-readable Description to the field to provide more context as to the field’s intended use case.
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 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.
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.
Any changes you make to the field groups or class of one schema will be reflected in all other schemas that employ them.
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:
|String, Double, Long, Integer, Short, Byte, Boolean
|A default value that is assigned to this field if no other value is provided during ingestion. This value must conform to the field’s selected type.
The default values are not saved in the dataset at the time of ingestion, as they can change over time. The default values set in the schema are inferred by downstream Platform services and applications when they read the data from the dataset. For example, when querying the data using Query Service, if the attribute has a NULL value, but the default is set to
5 at the schema level, it is expected that Query Service will return
5 instead of NULL. Please note, this behavior is not currently uniform across all AEP services.
|A regular expression that the value for this field must conform to in order to be accepted during ingestion.
|Select from a list of pre-defined formats for strings that the value must conform to. Available formats include:
|The minimum number of characters the string must contain for the value to be accepted during ingestion.
|The maximum number of characters the string must contain for the value to be accepted during ingestion.
|The 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.
|The 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 value
|The 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 value
|The 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.
The right rail provides several checkboxes for designating special roles for the selected field. The use cases for some of these options involve important considerations regarding your data modeling strategy and how you intend to use downstream Platform services.
To learn more about these special types, refer to the following documentation:
While technically not a special field type, it is also recommended that you visit the guide on defining object-type fields to learn more about defining nested sub-fields if your schema structures.
This guide provided an overview of how to define XDM fields in the UI. Remember that fields can only be added to schemas through the use of classes and field groups. To learn more about how to manage these resources in the UI, see the guides on creating and editing classes and field groups.
For more information on the capabilities of the Schemas workspace, see the Schemas workspace overview.