In addition to common field attributes (supported by all Identity Cloud field types) there are also type-specific attributes supported by some (but not by all) field types. These type-specific attributes include:

• dateFormat
• emptyMeansNull
• engageData
• ignoreUpdate
• placeholder
• preChecked
• submitValue
• value
• yearEnd
• yearStart
• justString
• dayLabelDateSelect
• monthLabelDateSelect
• yearLabelDateSelect
• monthNames
• options
  • selected
  • disabled
• schemaAttributes
• elementValue
• elementAttributes

These attributes are described in more detail in the following sections.

dateFormat

Required: No
Term used in the Configuration API: dateFormat
Term used in Registration Builder: Date Format

Enables you to change the format used in date select fields. By default, dates are displayed using the format mm/dd/yyyy (month/day/year). For example, December 19, 1989 looks like this:

12/19/1989

However, by using the dateFormat attribute you can change the way that December 19, 1989 is displayed. For example, you can configure the date format to look like this:

"dateFormat": "mm/dd/yyyy"

In turn, December 19, 1989 would look like this:

19/12/1989

You can use any combination of mm, dd, and yyyy (separated by /’s) in order to construct a date format. The syntax yyyy/mm/dd yields the following:

1989/12/19

When assigning the dateFormat attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "birthdate",
  "schemaAttribute": "birthday",
  "dateFormat": "dd/mm/yyyy"
}

The dateFormat attribute can be used with the following field types:

• Date select field

emptyMeansNull

Required: No
Term used in the Configuration API: emptyMeansNull
Term used in Registration Builder: Submit blank field values as null

When set to true, allows the system to interpret empty (blank) values as being null values. This can be especially useful with unique attributes, because an empty is still a value: it’s just that the value is, effectively, nothing. By contrast, a null value means “There is no value here, not even a blank value.” That might seem like a trivial distinction , but because an empty value is a value, only one user in your entity type can have an empty value assigned to a unique attribute: multiple users can’t be assign the same value, not even an empty value. Because null values aren’t really values, however, a unique attribute can have multiple users assigned a null value.

The emptyMeansNull attribute can also useful when working with date fields: they enable you to reset a date field to a null value (e.g., the user has not specified their date of birth) as opposed to resetting that date to an empty value. When assigning the emptyMeansNull attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "text",
  "name": "mobileNumber",
  "schemaAttribute": "mobileNumber",
  "validation": [
    {
      "rule": "unique",
      "value": true,
      "message": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      }
    }
  ],
  "emptyMeansNull": true
}

The emptyMeansNull attribute can be used with the following field types:

• Text input field
• Email field
• Password field
• Select menu field
• Text area field
• Date select field
• Hidden field

engageData

Required: No
Term used in the Configuration API: socialProfileData
Term used in Registration Builder: Prepopulate with data from identity provider

When a user logs in using a social provider, the Social Login service returns information obtained from the social provider in the form of a Portable Contact payload. You can use the socialProfileData attribute to specify which data from the social profile should be used to populate the value for this field in the user record. For example:

“socialProfileData": "profile.name.familyName"

The socialProfileData attribute can be used with the following field types:

• Text input field
• Email field
• Text area field

ignoreUpdate

Required: No
Term used in the Configuration API: ignoreUpdate
Term used in Registration Builder: Ignore updates submitted to this field

When set to true, enables you to create a field that can be filled in by an end user but is not written to the user profile. The ignoreUpdate attribute is typically used with hidden/calculated fields.

When assigning the ignoreUpdate attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "hidden",
  "name": "optInHidden",
  "schemaAttribute": "optIn.status",
  "value": "null",
  "ignoreUpdate": true
}

The ignoreUpdate attribute can be used with the following field types:

• Text input field
• Email field
• Password field
• Checkbox field
• Radio buttons field
• Select menu field
• Text area field
• Hidden field

placeholder

Required: No
Term used in the Configuration API: placeholder
Term used in Registration Builder: Placeholder Text

Used as the placeholder attribute on form elements when using the JavaScript SDK. A placeholder is text that appears in a field, but then disappears as soon as the user begins to type in that field. 

The placeholder must be a reference to a translation identifier; for example:

"placeholder": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

The placeholder attribute can be used with the following field types:

• Text input field
• Email field
• Password field
• Text area field
• multiIdentifierAuth field

preChecked

Required: No
Term used in the Configuration API: prechecked
Term used in Registration Builder: Pre-check by default

If set to true, the checkbox will be preselected on a form; users who do not want to accept that option will then have to manually clear the checkbox. For example:

"preChecked": true

Note that, when using the preChecked attribute you must include the value attribute (also set to true).

The preChecked attribute can be used with the following field types:

• Checkbox field

submitValue

Required: No
Term used in the Configuration API: submitValue
Term used in Registration Builder: n/a

Use this if you need to specify the submit value of a checkbox. For example:

"submitValue": "true"

The submitValue attribute can be used with the following field types:

• Checkbox field

value

Required: No
Term used in the Configuration API: value
Term used in Registration Builder: Default Value

Enables you to configure a default value for a field; default values can be configured either as a string or as a Boolean (true/false) value.

For example, the following code snippet sets the default value of the optInHidden field to false:

{
  "type": "hidden",
  "name": "optInHidden",
  "schemaAttribute": "optIn.status",
  "value": false
}

The value attribute can be used with the following field types:

• Text input field
• Radio buttons field
• Select menu field
• Text area field
• Hidden field

Note that, with the checkbox field, you must set preChecked to true*and* set value to true in order to have the checkbox preselected..

yearEnd

Required: No
Term used in the Configuration API: yearEnd
Term used in Registration Builder: End Year

Enables you to specify the final year shown in a date select control. For example, in this date select control 2021 is configured as the final year.

That means that, with this control, you cannot select any date later than December 31, 2021.

When assigning the yearEnd attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "childBirthdate",
  "schemaAttribute": "birthday",
  "yearEnd": "2021"
}

The yearEnd attribute can be used with the following field types:

• Date select field

yearStart

Required: No
Term used in the Configuration API: yearStart
Term used in Registration Builder: startYear

Enables you to specify the first year shown in a date select control. For example, in this date select control 2008 is configured as the earliest available year.

That means that, with this control, you cannot select any date earlier than January 1, 2008.

When assigning the yearStart attribute by using the Configuration API, your syntax will look similar to this:

{
  "type": "dateselect",
  "name": "childBirthdate",
  "schemaAttribute": "birthday",
  "yearStart": 2008
}

The yearStart attribute can be used with the following field types:

• Date select field

justString

Required: No
Term used in the Configuration API: n/a
Term used in Registration Builder: n/a

Displays only the plain-text data retrieved from the user profile: no formatting or other markup is allowed. This is a read-only value that appears in the flow, but isn’t accessible through either the Configuration API or Registration Builder. Although you can try changing the  value of the justString attribute by using the APIs, that code will simply be ignored when you make your API call.

The justString attribute is used with the following field types:

• Read-only field
• Translatable string field

dayLabelDateSelect

Required: No
Term used in the Configuration API: dayLabel
Term used in Registration Builder: n/a

Specifies the text used as the label for the day of the month dropdown in a date select field. For example, the following field uses the default value Day as the value for the attribute:

By comparison, this field uses an uppercase D to represent the day of the month:

To change the dayLabelDateSelect field by using the Configuration API, simply set the dayLabel attribute to a different translation key ID:

"dayLabel": {"key": "ef417f4535a9ab6531207cbbe81ed570"}

The dayLabelDateSelect attribute is associated with the following field types:

• Date select field

monthLabelDateSelect

Required: No
Term used in the Configuration API: monthLabel
Term used in Registration Builder: n/a

Specifies the text used as the label for the month dropdown in a date select field. For example, the following field uses the default value Month as the value for the attribute:

By comparison, this field uses an the phrase Mon to represent the day of the month:

To change the monthLabelDateSelect field by using the Configuration API, simply set the monthLabel attribute to a different translation key ID:

"monthLabel": {"key": "ef417f4535a9ab6531207cbbe81ed570"}

The monthLabelDateSelect attribute is associated with the following field types:

• Date select field

yearLabelDateSelect

Required: No
Term used in the Configuration API: yearLabel
Term used in Registration Builder: n/a

Specifies the text used as the label for the year dropdown in a date select field. For example, the following field uses the default value Year as the value for the attribute:

By comparison, this field uses the abbreviation Yr to represent the year:

To change the yearLabelDateSelect field by using the Configuration API, simply set the yearLabel attribute to a different translation key ID:

"yearLabel": {"key": "ef417f4535a9ab6531207cbbe81ed570"}

The yearLabelDateSelect attribute is associated with the following field types:

• Date select field

monthNames

Required: No
Term used in the Configuration API: monthNames
Term used in Registration Builder: n/a

Specifies the names of the months as they appear in a date select field. When using the Configuration AP, month names must be specified as a JSON array, with January being month 0 (the first month listed in the array) and December being month 11 (the last month listed in the array). For example:

{
    "monthNames": [{
        "key": "6951236776c9961af419252cd5ce7146"
    },
    {
"key": "6d764989c3de4b0a8069015d6f9ad3de"
    },
    {
"key": "2dd935f7ffe853e9267d8cc490bb89ce"
    },
    {
"key": "8a3fd2b4a6a53abad182733e083be160"
    },
    {
"key": "bcfc7702cb006677eb2b2a2fc40f9281"
    },
    {
"key": "d8121563311b5e6246de94ede6d90aa4"
    },
    {
"key": "6ba8a571ba7d1267f587d197ccf4bb4a"
    },
    {
"key": "d936a4e0e1dc5a0dd2c6445e25b0c36a"
    },
    {
"key": "6f0c81e8b2ea06fa6c8d4d7b483a14d3"
    },
    {
"key": "fffa5d300500aed948267c32c1cd1dd4"
    },
    {
"key": "6ee41ad264cc30f1f96a1884c0c5a376"
    },
    {
"key": "155a680eae771eda764fb18d4380b172"
    }
],

Keep in mind that the configuration API assumes that the first month shown in the preceding API is January, the second month shown is February, etc. Maintaining the this chronological order is the only way to get the month names to display properly.

In the following field the month names have been configured as three-letter abbreviations:

The monthNames attribute is associated with the following field types:

• Date select field

options

Required: Yes
Term used in the Configuration API: options
Term used in Registration Builder: Configure Options

Configures the individual values that can be selected either in a radio button collection or a select menu. For example, the following set of radio buttons includes four options (e.g., Full-time Employee):

When using the Configuration API, the options attribute must be formatted as a JSON object, with the individual options each formatted as a JSON array. For example:

"options": [
    {
        "label": {"key": "3d43b06fe00fa7cdc32e45ecc8399239"},
        "value": "Full-time Employee"
    },
    {
        "label": {"key": "3d43b06fe00fa7cdc32e45ecc8399239"},
        "value": "Part-time Employee"
    },
    {
        "label": {"key": "3d43b06fe00fa7cdc32e45ecc8399239"},
        "value": "Contractor"
    },
    {
        "label": {"key": "3d43b06fe00fa7cdc32e45ecc8399239"},
        "value": "Intern"
    }
]

Individual options must include both a label (the text, such as Full-time Employee, that’s displayed on screen), and a value (the data written to the user profile). Although the label and the value can be identical (e.g., they can both be set to Full-time Employee), they don’t have to be identical: instead, an option labeled Full-time Employee could write the value 1 to the user profile. Note, however, that the label must point to a translation key ID, while the value must be the actual value that gets written to the user profile. For example, to write the value 1 to the user profile use syntax like this:

{
    "label": {"key": "3d43b06fe00fa7cdc32e45ecc8399239"},
    "value": "1"
},

Two optional properties are also available when using this attribute:

• selected. When set to true, indicates the pre-selected value for the radio buttons or select menu.
• disabled. When set to true, the option is displayed on screen but can’t be selected.

The options attribute is associated with the following field types:

• Radio buttons field
• Select menu field

selected

Required: No
Term used in the Configuration API: selected
Term used in Registration Builder: Default Value

When used with a radio button or select menu field (and when set to true) indicates which option will be selected by default: if the user doesn't change  the selection then the value of the option marked as selected is written to the user profile. For example, in the following set of radio buttons the option Part-time Employee is selected by default:

If the user skips this field when filling out the form, their employment status will be record as Part-time employee.

To mark an option as the default option when using the Configuration API, simply set the selected value to true when defining the option:

{
    "selected": true,
    "value": "Part-time Employee",
    "label": {"key": "3d61cdcc-3fc3-4388-b6b5-590e7e325639"}
}

Two things to note here:

1. You can only define one selected option; that’s because radio buttons and select menus do not allow you to choose multiple items. If you set the selected attribute to true for more than one option, then your API call will fail. (Similarly, Registration Builder won't let you to tag more than one option as selected.)

2. By default, the selected attribute is set to false for each option: if you don’t explicitly include the selected attribute (and set the value to true) when defining an option then the option won't be pre-selected.

The selected attribute is associated with the following field types:

• Radio buttons field
• Select menu field

Note that, if you’re working with a checkbox field, you must use the preselected attribute instead of the selected attribute.

disabled

Required: No
Term used in the Configuration API: disabled
Term used in Registration Builder: Disabled

When set to true, disables the specified radio button or select menu option. When an item is disabled, that means that the  option is visible onscreen but can't be selected. In addition, the option label is displayed in gray text rather than the typical black text. In the following example, the option Social media direct message has been disabled:

To disable an option, set the disabled attribute to true when configuring option values:

{
    **"disabled": true,**
    "value": "Social media direct message",
    "label": {"key": "3d61cdcc-3fc3-4388-b6b5-590e7e325639"}
}

By default, the disabled attribute is set to false: if you don’t explicitly include the disabled attribute (and set the value to false) when defining an option then that option won't be disabled. Note that it’s possible to set multiple options as  disabled; in fact, it’s even possible (although typically not recommended) to disable all the options in a radio button collection or select menu:

The disabled attribute applies to the following field types:

• Radio buttons field
• Select menu field

schemaAttributes

Required: Yes
Term used in the Configuration API: schemaAttributes
Term used in Registration Builder: n/a

Somewhat similar to the schemaId attribute, the schemaAttributes attribute is used to identify the user profile attributes that can be used to for authentication purposes; as such, this attribute can only be used with the multiAuthIdentifier field. For example, the following syntax enables you to use either your email address or your mobile device number for authentication:

"schemaAttributes": {"email", "mobile Number"}

Note that the user profile attributes must be formatted as a comma-separated JSON array (hence the curly braces surrounding the attribute names). In addition, you must include at least two attribute names, and all the included attributes must have the string datatype and be configured as globally-unique.

Note, too that the multiIdentifierAuth field is used for post-login authentication purposes: when actually logging on the an Identity Cloud website (i.e., by using the signInscreen) you are still limited to traditional login (email address and password) and social login.

The schemaAttributes attribute is associated with the following field types:

• multiIdentifierAuth field

elementValue

Required: Yes
Term used in the Configuration API: n/a
Term used in Registration Builder: n/a

Legacy attribute that sets the default value for the field. This is a read-only value that appears in the flow but isn’t accessible through either the Configuration API or Registration Builder. Although you can try changing the  value of the elementValue attribute by using the APIs, that code is simply be ignored when you make your API call.

The elementValue attribute is associated with the following field types.

• Checkbox field

elementAttributes

Required: Yes
Term used in the Configuration API: n/a
Term used in Registration Builder: n/a

Legacy attribute used with password fields to turn autocompletion on or off; by default autocompletion is turned off, meaning that the browser will not attempt to fill in the value for you. This is a read-only value that appears in the flow but isn’t accessible through either the Configuration API or Registration Builder.

• Password field