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 mixins. 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 mixins 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, use the left rail to select the class or mixin that you want to define fields for. If the resource is a custom resource defined by your organization, controls to add or edit 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 mixin.

NOTE

If the class or mixin you select is a core resource provided by Adobe, it cannot be edited and therefore the controls shown above will not appear. If the schema you want to add fields to is based on a core XDM class and does not contain any custom mixins, you can create a new mixin to add to the schema instead.

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.

Define a field for a resource

After selecting the plus (+) icon, a New field appears in in the canvas, located within a root-level object that is namespaced to your unique tenant ID (shown as _tenantId in the example below). All fields that are added to a schema through custom classes and mixins are automatically placed within this namespace to prevent conflicts with other fields from Adobe-provided classes and mixins.

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

Field property Description
Field name A unique, descriptive name for the field. Note that the field’s name cannot be changed once the schema has been saved.

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
Display name A human-friendly name for the field.
Type 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.

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 canvas updates to show the field’s name and type, and 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 mixins are also saved if any changes have been made to them.

NOTE

Any changes you make to the mixins 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 property Compatible types Description
Default value String, Double, Long, Integer, Short, Byte, Boolean A default value that will be assigned to this field if no other value is provided during ingestion. This value must conform to the field’s selected type.
Pattern String A regular expression that the value for this field must conform to in order to be accepted during ingestion.
Format String Select from a list of pre-defined formats for strings that the value must conform to. Available formats include:
Minimum length String The minimum number of characters the string must contain for the value to be accepted during ingestion.
Maximum length String The maximum number of characters the string must contain for the value to be accepted during ingestion.
Minimum value Double 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.
Maximum value Double 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 Double 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 Double 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.

Special field types

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 mixins. To learn more about how to manage these resources in the UI, see the guides on creating and editing classes and mixins.

For more information on the capabilities of the Schemas workspace, see the Schemas workspace overview.

On this page