Define enums and suggested values in the UI :headding-anchor:enums-and-suggested-values

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.

Image showing 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:

Transcript
With the September release there will be an enhanced enum and suggested value workflow. Enumerated fields are used when you want to restrict data values coming in on ingestion. For example, if I want to bring in only male, female, or unspecified on a gender field, I could use an enumerated field to restrict data coming in to just those three values. Suggested value fields are used either in conjunction with enumerated fields or as a standalone configuration. Suggested values allow you to build a list of possible values that the data may or may not adhere to, but will surface as a friendly dropdown list in the segmentation UI. Let’s take a look at the capabilities in action.
Here I am in my experience event billing information schema. I can now see the suggested values that are included on the standard event type field. I select event type and see all the event types that are included.
I also have the flexibility to add additional suggested values, which will show in my segmentation dropdown. I want the marketer to be able to segment on billing complete, so I will add that to my list of event types.
I want to track payment setup, whether it’s automatic or manual by the user. On my custom payment setup method field, I will add a suggested value to capture these two options. I will add suggested value and add automatic and manual.
Downstream, the marketer will be able to easily segment by manual or automatic payment setup method. Last, I want to add a suggested value list on a standard field. I want to track whether login status is not started, pending or complete. I’ll go to the login status field and I have the option to add a suggested value. I will add not started, pending and complete as options that the marketer will be able to segment on. Let’s take a look at what it looks like downstream for the marketer. Now you can see when the marketer goes to build a segment, they can add that login status field to a segment and easily segment on the values we added to the suggested value in the schema UI. They have the option to choose complete, pending or not started, but they can also just type in an additional value and use that as well. These are just suggested values, they’re not locked into just those three. Thanks for watching this demo. -

Define an enum :headding-anchor: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.

Image showing 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.

Image showing 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 :headding-anchor: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.

Image showing 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.

Image showing 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. While you can create additional suggested values for a standard field, you cannot modify or remove any suggested values that are not defined by your organization. When viewing a standard field in the UI, its suggested values are displayed but are read-only.

Image showing the enum values and display names filled out for the string field 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.

Image showing the enum values and display names filled out for the string field in the UI

Evolution rules for enums and suggested values :headding-anchor:evolution

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 for standard and custom fields with existing suggested values.
  • You CAN remove suggested values from custom fields with existing suggested values.
  • 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 remove enums or suggested values from standard fields.
  • You CANNOT add enum values to a field with no existing enum.
  • You CANNOT remove fewer than all existing enum values for a custom field.
  • You CANNOT switch from suggested values to an enum.

Merging rules for enums and suggested values :headding-anchor:merging

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 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.

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07