Attribute constraints

Constraints serve at least two purposes. For one, they help specify the kind of data that can be stored in an attribute. For example, an attribute marked as alphabetic only accepts the letters A-Z (either uppercase or lowercase). Constraints also impose other restrictions on the values that can be stored in an attribute. For example, the unique constraint ensures that a specified attribute value in an entity type needs to be unique. Why can’t two users can’t share the same email address? That's because email is a unique attribute.

Attribute constraints are similar to data validations, and there’s even some overlap between the two. As a general rule, however, attribute constraints tend to be more generic in nature and data validations tend to be more specific. For example, the alphabetic constraint limits an attribute value to the letters A-Z. By comparison, a data validation could do something like limit an attribute value to the letters A, D, L, N, and Y. See Data validation rules for more information.

Attribute constraints are managed by using the /entityType.setAttributeConstraints operation. For example, the following Curl command makes the givenName attribute (in the user entity type) a required attribute:

curl -L -X POST 'https://se-demos-gstemp.us-dev.janraincapture.com/entityType.setAttributeConstraints' \
  -H 'Authorization: Basic ht65n2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzjuy6xxq6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Y8UUlga=' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type_name=user' \
  --data-urlencode 'attribute_name=givenName' \
  --data-urlencode 'constraints=["required"]'

Note that there isn’t an operation for modifying or for removing attribute constraints. To modify the constraints assigned to an attribute just rerun the /entityType.setAttributeConstraints operation, specifying the full set of constraints you want to assign to the attribute:

--data-urlencode 'constraints=["required", "unique"]'

In the preceding example, all the constraints currently assigned to the attribute are replaced by the required and the unique constraints.

To remove all the constraints from an attribute call the /entityType.setAttributeConstraints operation and set the constraints member to an empty array:

--data-urlencode 'constraints=[]'

On top of all that, there's also no straightforward way to return a collection of all the attributes that have constraints applied. However, if you call the /entityType operation the API response includes all the constraints applied to all your attributes. For example:

{
        "case-sensitive": true,
        "constraints": [
          "required",
          "unique"
        ],
        "length": 256,
        "name": "email",
        "type": "string"
      }

In the preceding snippet, the required and the unique constraints have been applied to the email attribute.

The following sections of this document examine the available attribute constraints in more detail.

required

Mandates that the attribute be set to a non-null value. For example, suppose you configure email as a required attribute and you attempt to create a new user account without specifying an email address for that account. That attempt fails with the following error:

{
  "attribute_name": "/email",
  "code": 362,
  "error": "missing_required_attribute",
  "error_description": "/email is required (cannot be null)",
  "request_id": "rhee3a78uy7pfm7a",
  "stat": "error"
}

That makes sense: your operation fails because you left out a required attribute. But what happens if you make an attribute required after a number of users have already created accounts without entering a value for that attribute? Well, initially, nothing happens: users can still log in to their account even though they’re missing a required value.

Similarly, users can also continue to use the /entity.update operation to make changes to their user profiles. However, Hosted Login users won’t be able to make any changes to their profile, at least not without supplying the missing (and required) value. For example, suppose a Hosted Login user doesn’t have a display name (which we'll assume is a required value). The user opens their user profile and changes their middle name. However, when they click Submit, the operation fails with the following error:

This also happens in Console: administrators can’t make any changes to a user profile unless all the required attributes have been assigned values.

unique

Requires the value of an attribute to be unique throughout an entity type. For example, only one user can have the email address karim.nafir@example.com (by default, email is a unique attribute).

{
  "code": 361,
  "error": "unique_violation",
  "error_description": "Attempted to update a duplicate value",
  "request_id": "v48npapb8h5maycr",
  "stat": "error"
}

The unique constraint is typically used for attributes that identify a specific user, such as an email address, a membership number, a UUID, etc. As a general rule, the unique constraint shouldn’t be applied to more-generic attributes. For example, if you make givenName a unique attribute then only one user can have the first name Stephen or the first name Susan. Something to be aware of.

As noted, uniqueness applies only to an individual entity type. If you have multiple entity types, each one can have a user with the email address karim.nafir@example.com.

locally-unique

The locally-unique constraint applies to plurals, a special type of attribute that can contain multiple values. For example, the following user profiles shows a user with two photos in their photos attribute:

Suppose you make the photos.type attribute locally unique. That means that you can only have one photo of the specified type. For example, each user can have only one Personal photo and one Company photo. If you try to add a second Personal photo to the user profile that attempt fails with this error:

{
  "code": 361,
  "error": "unique_violation",
  "error_description": "Attempted to update a duplicate value",
  "request_id": "v48npapb8h5maycr",
  "stat": "error"
}

The error occurs because, within the photos attribute for this user profile, the type must be unique. However, other users can have a Personal photo and a Company photo because uniqueness is limited to the user profile and not to the entire entity type.

alphabetic

Limits values to the letters A through Z (either uppercase or lowercase). If you try to enter anything other than a letter – for example, if you try to enter the value 13 – your data entry is rejected with the following error:

{
  "attribute_name": "/sampleAttribute",
  "code": 360,
  "constraint_name": "alphabetic",
  "error": "constraint_violation",
  "error_description": "the value provided for /sampleAttribute violates the alphabetic constraint",
  "request_id": "bhxva7mhgu4jj3an",
  "stat": "error"
}

alphanumeric

Limits values to the letters A through Z (either uppercase or lowercase) and the digits 0-9. If you try to enter any other character – such as ! or $ -- your data entry is rejected with the following error:

{
  "attribute_name": "/sampleAttribute",
  "code": 360,
  "constraint_name": "alphanumeric",
  "error": "constraint_violation",
  "error_description": "the value provided for /sampleAttribute violates the alphanumeric constraint",
  "request_id": "phjcc4hc73bhkqwv",
  "stat": "error"
}

unicode-letters

Allows the use of any alphabetic Unicode character, but prohibits the use of any non-alphabetic character. For example, the “smiley face” is a valid Unicode character, but it isn’t an alphabetic character:

😀

If you include the smiley face character in your data entry that operation fails with the following error:

{
  "attribute_name": "/sampleAttribute",
  "code": 360,
  "constraint_name": "unicode-letters",
  "error": "constraint_violation",
  "error_description": "the value provided for /sampleAttribute violates the unicode-letters constraint",
  "request_id": "zawdgtmhymhb4vwt",
  "stat": "error"
}

However, any alphabetic character – such as this one, taken from the Armenian alphabet – passes validation:

Թ

unicode-printable

Allows printable Unicode characters such as letters, digits, punctuation marks, and other special characters. What this constraint doesn’t allow are unprintable Unicode characters such as a line feed, tab, or carriage return. For example, in JSON the newline character (carriage return + linefeed) is \n. Suppose you include a newline in your data entry:

First line\nSecond line

Your attempt to use an unprintable characters results in the following error:

{
  "attribute_name": "/sampleAttribute",
  "code": 360,
  "constraint_name": "unicode-printable",
  "error": "constraint_violation",
  "error_description": "the value provided for /sampleAttribute violates the unicode-printable constraint",
  "request_id": "69rgh5jcgukgu4df",
  "stat": "error"
}

And what if you need to include \n in a value? For example, what if a model number or a serial number is b\nob? In that case, use a second ** to “escape” the \n**:

b\\nob

If you check the user profile, you can see that escaping the \n allows that construction to pass validation:

email-address

Requires a value to be formatted as an email address, using the following syntax:

name@email-domain.top-level-domain

For example:

karim.nafir@example.com

If you try to enter an incorrectly-formatted address such as karim.nafir@ or karim.nafir@example that attempt fails with the following error:

{
  "attribute_name": "/sampleAttribute",
  "code": 360,
  "constraint_name": "email-address",
  "error": "constraint_violation",
  "error_description": "the value provided for /sampleAttribute violates the email-address constraint",
  "request_id": "md8yst357au3vbaz",
  "stat": "error"
}

Keep in mind that this constraint only ensures that you’ve entered a properly-formatted email address. No attempt is made to ensure that it’s a valid email address (i.e., an email address you can actually send messages to).