3 mins read

Using Identity Schemas to Define Custom User Attributes

Learn what Identity Schemas are and how they are used to define user custom attributes.

Custom User Attributes

User Entity is a combination of operational attributes and custom attributes. Different user populations within an organization may have distinct needs and requirements when it comes to user entities. For example, a customer population may require specific attributes such as purchase history and preferences, while an employee population may need information related to job roles and departmental affiliations. By tailoring user entities to the specific needs of each population, organizations can better manage access, streamline authentication, and provide more personalized experiences for all their users.

In Cloudentity, user custom attributes, which can be either editable by the users themselves or exclusively modifiable by administrators, are represented through the concept of Identity Schemas. These schemas serve to delineate the available attributes associated with users. Schemas can be specifically tailored to individual Identity Pools or shared across multiple pools to ensure a consistent structure for user information while catering to the unique needs of various user populations.

Identity Schemas

Technically, Identity Schema is represented with a JSON schema which determines how the payload and metadata objects, conveying user data, must be structured in the Identity APIs. We have two types of Identity Schemas:

  • Payload schema - used to define and validate the payload structure of user-related requests (for example, the presence of user’s first name and last name)

  • Metadata schema - used to define and validate the metadata structure of user-related requests. Metadata is read-only from user’s perspective. Parameters marked as hidden: true in the schema are hidden from users calling the Self Get User Profile endpoint.

Cloudentity provides system Identity Schemas for payload and metadata - those schemas are assigned to Identity Pools by default and cannot be modified or deleted. A sample payload schema with added e-mail and custom parameters could look as follows:

Object Description
properties An array of objects where each object represents a property to be entered by the user
description Schema description for identification purposes. This description is displayed as a header on the user registration form.
type Schema data type - there should be no need to change this as the schema will always be an object.
required List of mandatory properties for user registration
    "properties": {
        "family_name": {
        "description": "user last name",
        "type": "string",
        "minLength": 1
        "given_name": {
        "description": "user first name",
        "type": "string",
        "minLength": 1
        "name": {
        "description": "user full name",
        "type": "string",
        "minLength": 1
        "e-mail": {
        "description": "user e-mail",
        "type": "string",
        "minLength": 1,
        "custom": {
        "description": "custom attribute",
        "type": "boolean",
        "minLength": 1
    "description": "sample user data schema",
    "type": "object",
    "required": [

When the above Identity Schema is assigned as a payload schema to the Identity Pool, the e-mail and custom parameters must be passed in the payload object for the request to succeed. On the UI side, the users and administrators are also prompted to fill in the required data to satisfy the schema:

Identity Schema

Updated: Sep 28, 2023