Manage schemas with the REST APIs

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.


📘

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

Alternatively, entity types and be managed by using the Identity Cloud Console .


Schema attribute types

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

TypePrimitiveJSON TypeNotes
booleanBoolean
dateStringSubject to the Timestamp format.
dateTimeStringSubject to the Timestamp format.
decimalNumber
idNumberNot an externally usable type.
integerNumber
ipAddressString
jsonAny typeThe JSON type is unstructured data; it only has to be valid parsable JSON.
object Object
passwordStringThe default password encoding is bcrypt.
plural ArrayPrimitive child attributes of plurals can have the constraint.
stringString
uuidStringNot an externally usable type.

📘

All primitive types can have the constraints unique and required.


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 a 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 operations and require a custom integration with the user profile.


📘

Object and plural attributes can be nested within another object or plural. Attribute nesting is limited to a depth of 5 attributes. For example:

  • object1.plural2.object3.plural4.givenName
    (This is a depth of 5 attributes and is allowed.)
  • object1.plural2.object3.plural4.object5.givenName
    (This is a depth of 6 attributes and is NOT allowed.)

Reserved attributes

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

AttributeDescription
createdAutomatically-generated timestamp marking the entity’s creation.
idA unique identifier for an entity. The ID is automatically created during registration and is unique to the entity.
lastUpdatedAutomatically-updated timestamp marking the last change made to an entity.
parent_idThe ID used when implementing plurals.
uuidUnique 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.