Define XDM fields in the UI
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 select-resource
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.
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:
Define the properties of a field define
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.
- Correct:
fieldName - Acceptable:
field_name2,Field-Name,field-name_3 - Incorrect:
_fieldName
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.
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. |
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.
Type-specific field properties type-specific-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:
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.
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.Select from a list of pre-defined formats for strings that the value must conform to. Available formats include:
Special field types special
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.
Next steps
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.