Managing Your Schema

Entity types are distinct profile data stores within a Registration application. A JSON schema defines the profile attributes to be stored for user records and any global validation rules or constraints that should be applied.

The Default Schema

Every Registration application is provisioned with a default entity type called user. This schema should only be expanded upon; deleting attributes from the default user schema may result in unexpected behavior. In particular, the following attributes are part of the default schema and are pertinent to the functionality implemented by the registration process:

• The profiles plural aggregates the user data returned from the different social providers. Each provider linked to a user account will be added as a separate object to the profiles plural, but will share a common structure.
• The clients plural stores information about when and where a user has authenticated (including at initial registration). This includes the client ID in use on the site where the login occurred, the timestamp of the user’s first login on that site, and the timestamp of the user’s last login on that site. Each time a user logs into a new site, a new entry will be added with its client ID. Subsequent logins on the same site will not create an additional object, but instead update the last login value.
• The janrain object stores metadata information needed for integrations with other systems such as Salesforce Marketing Cloud or other parts of the Identity Cloud platform.

Note. The attributes in the default user entity type provisioned with new applications is occasionally updated, so not all customers will have the attributes listed above.

Adding Entity Types

In most cases the default user entity type is used for all site registrations. Occasionally you may want to utilize multiple entity types for the purpose of keeping registrations of different user types or customer verticals separate. We recommend that you consult with the Akamai Professional Services team if you are considering taking this approach.

Additional entity types may be created with the entityType.create API. Once an entity type has been created, you can add and remove schema attributes associated with it by using the entityType.addAttribute and entityType.removeAttribute endpoints.

Schema Attribute Types

The following attribute types are available for storing different types of user data.

Type	Primitive	JSON Type	Notes
boolean	Yes	Boolean
date	Yes	String	Subject to the Timestamp format.
dateTime	Yes	String	Subject to the Timestamp format.
decimal	Yes	Number
id	Yes	Number	Not an externally usable type.
integer	Yes	Number
ipAddress	Yes	String
json	Yes	(any type)	The JSON type is unstructured data; it only has to be valid parsable JSON.
object	No	Object
password	Yes	String	The default password encoding is bcrypt.
plural	No	Array	Primitive child attributes of plurals can have the constraint.
string	Yes	String
uuid	Yes	String	Not an externally usable type.

Note. All primitive types can have the constraints unique and required. For more information on constraints, please see the Constraints section.

Objects

Objects are used for nesting related attributes under a parent attribute within the schema. For example, in the default schema the primaryAddress object holds address1, city, zip, and other related attributes. When making API calls targeting an attribute within an object, you must refer to the parent and child attributes by using "dot" notation, with a period separating the parent attribute name and the child attribute name. For example: primaryAddress.city.

Plurals

Plurals are a special object type used for storing an indefinite number of nested objects or attributes of a like construct. Common use cases include opt-in lists, addresses, and subscriptions. Plurals are not supported by the Registration UI or OAuth API endpoints and require a custom integration with the user profile.

Reserved Attributes

The following attributes are read-only, automatically generated, and required in all schemas.

Attribute	Description
created	Automatically-generated timestamp marking the entity’s creation.
id	A unique identifier for for an entity. The ID is automatically created during registration and is unique to the entity.
lastUpdated	Automatically-updated timestamp marking the last change made to an entity.
parent_id	The ID used when implementing plurals.
uuid	Unique identifier for the entity.

Timestamp Formats

The registration schema accepts date and dateTime values in ISO 8601 format. For example, the following are acceptable dates:

• 1984-06-07
• 1998-01-01
• 2005-12-31

And the following are acceptable dateTime values:

• 1984-06-23 00:00:00 +0000
• 1984-06-23T00:00:00 +0000

Note that all timestamps are rendered using the UTC (Coordinated Universal Time) standard, and include the "+0000" time zone offset tag at the end of the timestamp.

Supported Password Hashing Algorithms

Akamai follows best practices to ensure that user credentials are stored in the Identity Cloud in a secure manner. For migrating custom or non-standard password hashes, please contact your Akamai representative.

Data Constraints and Features

Constraints

The following constraints may be applied to attributes of the string data type using the /entityType.setAttributeConstraints API.

Constraint	Description
alphabetic	Data may only contain characters A–Z.
alphanumeric	Data may contain characters A–Z and 0–9.
unicode-letters	Data may only contain characters encoded using the Unicode standard.
unicode-printable	Data may only contain Unicode-encoded characters that can be printed to the screen in HTML. The excluded characters are: u0000–u001F, u007F–u009F, \n, \t, and \r.
email-address	Data must contain an @ symbol and top level domain suffix, such as .com.
length	Used only with attributes of type string. Defines the number of characters allowed. By default, string length must be specified for the attribute to be indexed.
required	Data must contain a non-null value.
unique	Data must be globally unique across all entities in an entityType.
locally-unique	Data must be locally unique across plurals within a single entity.

When added to an attribute, constraints are applied only to data saved to user records after the constraint is applied. The exceptions to this rule are the unique and locally-unique constraints, which apply retroactively to data already collected. If existing data violates the constraint, adding the rule will result in an error. Error responses are explained in detail in the Error Codes topic.

Constraints set on a schema attribute will apply globally to all records. If you need to apply different constraints or validations on data collected at different sites or properties, the Configuration API will allow you to apply those in the flow configuration layer.

Features

The following features may be applied to attributes of the string data type. These features may only be applied by the Akamai team.

Feature	Description
primary-key	Makes the attribute a primary key for the plural or entity type it exists in, providing the ability to target a specific record in a plural in API calls without knowing the actual identifier for that record. Requires both required and either unique or locally-unique constraints.
query	Adds an index to an attribute to optimize the performance of entity.find API calls.

Data Validation Rules

The following data validation rules may be applied to attributes using the entityType.addRule API. The table below notes which attribute type each rule may be applied to and what type of argument each rule will accept, if any. Filters that transform input are applied before filters that validate input.

Important. Regular expressions work only when used with single-byte characters. At this point in time, regular expressions cannot be used with Unicode characters.

Rule	Description	Transforms Input?	Attribute Type	Argument Type
match	Data must contain a match from a POSIX-style regular expression.	no	string	string
match-all	Data must completely match a POSIX-style regular expression.	no	string	string
min-length	Data must be less than or equal to the argument supplied.	no	string	integer
max-length	Data must be greater than or equal to the argument supplied.	no	string	integer
less-than	Data must be less than the argument supplied.	no	integer	number
greater-than	Data must be greater than the argument supplied.	no	integer	number
required	Data must contain a non-null value.	no	any	none
min-age	The date submitted must be at least n years ago.	no	date	integer
default	Data will be pre-populated with the argument supplied.	yes	any	integer or string
ignore-update		yes	any	none
truncate	Stores only the first n characters of the value submitted.	yes	string	integer
to-lower	Converts a string value to lower case.	yes	string	none
to-upper	Converts a string value to upper case.	yes	string	none
and	Combines a list of filters and fails if one of the filters fails.	maybe	array of rules	array of strings and/or objects
or	Combines a list of filters and fails if all of the filters failed.	maybe	array of rules	array of strings and/or objects
not	Turns a failed filter result into a successful filter result.	maybe	rule	string or object

When added to an attribute, rules are applied only to data saved to user records after the rules are applied. When a rule is violated, a 360 (constraint_violation) error is returned. Error responses are explained in detail in the Error Codes topic.

Rules set on a schema attribute will apply globally to all records. If you need to apply different constraints or validations on data collected at different sites or properties, the Configuration API will allow you to apply those in the flow configuration layer.

Rule Definition Examples

Values are truncated to 100 characters if their length is over 100 and converted to lower case:

{
 "and": [
 {"truncate": 100}
 ,"to-lower"
 ]
 }
 

Values are rejected if they are less than six characters long or contain any 3s or fs:

 {
      "and": [
          {"min-length": 6},
          {"not": {
                "match":"[3f]"
            }
          }
      ]
    }
 

    {
       "and":[
          {
             "min-age":16
          },
          "required"
       ]
    }