Define enums and suggested values in the UI

In Experience Data Model (XDM), a string field can be given a predefined set of accepted or suggested values to better control what values are ingested into that field or how it will behave in segmentation.

Enums constrain the values that can be ingested for a string field to a predefined set. If you attempt to ingest data to an enum field and the value does not match any of those defined in its configuration, ingestion will be denied.

In contrast to enums, the Suggested values option allows to to denote a set of recommended values for a string field that do not constrain the values that it can ingest. Instead, suggested values affect what predefined values are available in the Segmentation UI when including the string field as an attribute.

When defining a new field in the Adobe Experience Platform user interface and setting the type to String, you are given the option to define an enum or suggested values for that field.

The Enum & Suggested Values option enabled for a string field in the UI.

This document covers how to define enums and suggested values in the Schemas UI workspace. For a quick overview on enums and suggested values, including how to configure them in the UI and their downstream effects, watch the following video:

Define an enum

Select Enums and Suggested Values, then select Enums. Additional controls appear, allowing you to specify the value constraints for the enum. To add a constraint, select Add row.

The Enums option selected in the UI.

Under the Value column, you must provide the exact value you want to constrain the field to. You can optionally provide a human-friendly Display Name for the constraint as well, which affects how the value will be represented in segmentation.

Continue to use Add row to add the desired constraints and optional labels to the enum, or select the delete icon (Image of the delete icon) next to a previously added row to remove it. When finished, select Apply to apply the changes to the schema.

The enum values and display names filled out for the string field in the UI.

The canvas updates to reflect the changes. When you explore this schema in the future, you can view and edit the constraints for the enum field within the right rail.

Define suggested values

Select Enums and Suggested Values, then select Suggested Values to make additional controls appear. From here, select Add row to start adding suggested values.

The Suggested Values option selected in the UI.

Under the Display Name column, provide a human-friendly name for the value as you want it to appear in the Segmentation UI. To add more suggested values, select Add row again and repeat the process as needed. To remove a previously added row, select the delete icon next to the row in question.

When finished, select Apply to apply the changes to the schema.

The enum values and display names filled out for the string field in the UI.

NOTE

There is an approximate five-minute delay for a field’s updated suggested values to be reflected in the Segmentation UI.

Manage suggested values for standard fields

Some fields from standard XDM components contain their own suggested values, such as eventType from the XDM ExperienceEvent class and you can create additional suggested values for these standard fields in the same way you would for custom fields. You can also disable any of the standard suggested values do not suit your use cases, but they cannot be outright removed from the field definition.

IMPORTANT

You can only disable suggested values for standard fields that do not have a corresponding enum constraint. In other words, if the Enums option is enabled instead of Suggested Values, then the field is constrained as an enum and those constraints cannot be disabled.

See the section below for more information on the rules for updating enums and suggested values for existing schema fields.

To disable a standard suggested value, select the toggle next to the value in question. You can disable any combination of suggested values, including all of them.

Some of the standard suggested values for the Event Type field disabled in the UI.

To add new suggested values for a standard field, select Add row. To remove a suggested value that was previously added by your organization, select the delete icon next to the row in question.

Custom suggested values added to a standard string field in the UI.

Evolution rules for enums and suggested values

After a schema with an enum field has been used to ingest data into Platform, any further changes made to the schema definition must comply with the data already in the system. In general, changes made to an existing field can only make that field less restrictive. An field cannot be made more restrictive than it already is.

When it comes to enums and suggested values, the following rules apply post-ingestion:

  • You CAN add suggested values to any field with existing suggested values.
  • You CAN remove custom suggested values from fields with existing suggested values.
  • You CAN disable standard suggested values from fields with only suggested values and no enum constraints.
  • You CAN add new enum values for an existing custom enum field.
  • You CAN switch a custom field’s enum values to suggested values only, or convert it to a string with no enum or suggested values. This switch cannot be undone once applied.
  • You CANNOT add or remove enum constraints from standard fields.
  • You CANNOT remove suggested values from standard fields (disable only).
  • You CANNOT add enum constraints to fields with no existing enum.
  • You CANNOT remove fewer than all existing enum constraints for a custom field.
  • You CANNOT switch from suggested values to an enum.

Merging rules for enums and suggested values

If multiple schemas use the same enum field with different configurations, and those schemas are included in a union, certain rules apply when it comes to how enum differences are reconciled. The exact rules depend on whether the schemas referencing the same standard field (like eventType) or if they’re referencing the same custom field path in different field groups.

If referencing the same standard field:

  • Any additional suggested values are APPENDED in the union.
  • Updates made to the suggested values for the same enum key are UPDATED in the union.

If referencing the same custom field path in different field groups:

  • Any additional suggested values are APPENDED in the union.
  • If the same additional suggested value is defined in more than one schema, those values are MERGED in the union. In other words, the same suggested value will not appear twice after merging.

Validation limitations

Due to current system limitations, there are two cases where an enum is not validated by the system during ingestion:

  1. The enum is defined on an array field.
  2. The enum is defined more than one level deep in the schema hierarchy.

Next steps

This guide covered how to define enums and suggested values for string fields in the the UI. For information on how to manage enums and suggested values using the Schema Registry API, refer to the following tutorial.

To learn how to define other XDM field types in the Schema Editor, see the overview on defining fields in the UI..

On this page