The schemas endpoints give administrators the ability to customize the existing attributes of the user model or define new attributes that are not part of the default user model. For example, applications often support user profile attributes that are not defined in the PingOne core attribute set for users.

Attribute types

There are three types of attributes that the user schema supports: core, standard, and custom. Core and standard attributes are available in the out-of-the-box user schema, and these attributes cannot be deleted. Custom attributes can be created, updated, and deleted. All types of attributes can be retrieved from a GET operation.

The mutability rules for these three types of attributes are:

The schemas service supports the following capabilities:

The examples below show common actions for working with schema resources and custom attributes. You need the Environment Admin role to read and update schema resources. Administrators with the Identity Data Admin or Client Application Developer roles can read schema resources.

Custom Attributes

You can add custom attributes to the user schema to identify and store key information such as account numbers, user preferences, demographic information, and other relevant profile data required by the application. A custom attribute is a name-value pair that can reference JSON or STRING user schema attributes or a static value. If the custom attribute has multiple values, then the attribute will be multi-valued in the token or assertion, as well. Custom attributes convey additional information about the user to applications.

Custom attributes have a maximum cumulative size of 16 Kb. This is calculated based on the string length for all of the custom attribute values. For example, given:

{ "id": "1234", "username": "jdoe", "customA": "1234", "customB": "1234" }

The cumulative custom attribute size in this case is 8. Size calculations for multi-valued and JSON custom attributes are the same. For the multi-valued custom attributes, add the length of all of the array elements. For JSON custom attributes, add the length of the JSON string. You can add a maximum of 100 custom string attributes and 100 custom JSON attributes.

An attribute can support multiple values if the multiValued property is set to true. If the multiValued property is set to false or is null, the User object will contain the attribute value as a single value. If multiValued is set to true, the value in the User object will be an array. When searches are performed on User schema data, a user will match if any value of a multiValued attribute is part of the search criteria.

Reserved attribute names

The following attribute names are reserved for internal use. Custom attributes cannot have the same name as these reserved attribute names.

Schemas data model

Property Type Required? Mutable? Description
allowsContainsOperator Boolean Optional Mutable Indicates whether or not the contains operator can be used. You can use the contains operator in a maximum of 5 custom attributes.
attributes.description String Optional Mutable A description of the attribute. If provided, it must not be an empty string. Valid characters consists of any Unicode letter, mark (for example, accent or umlaut), numeric character, punctuation character, or space.
attributes.displayName String Optional Mutable The display name of the attribute such as 'T-shirt size’. If provided, it must not be an empty string. Valid characters consist of any Unicode letter, mark (for example, accent or umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
attributes.enabled Boolean Required Mutable Indicates whether or not the attribute is enabled. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null. Disabled attributes are ignored for POST or PUT, and are not returned for GET operations.
attributes.environment.id String N/A Immutable The identifier of the environment resource referenced by this relationship.
attributes.id String N/A Immutable The attribute’s unique identifier.
attributes.ldapAttribute String Required Immutable The unique identifier for the LDAP attribute.
attributes.name String Required Mutable The name of the attribute. The attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must also be unique within the schema for an environment. It must start with a letter and may be followed by letters, numbers or hyphens.
attributes.required Boolean Optional Mutable Indicates whether or not the attribute is required. Required attributes must be provided a value for POST and PUT. Defaults to false.
attributes.schema.id String Required Immutable The identifier of the resource referenced by this relationship.
attributes.schemaType String Required Mutable The schema type of the attribute. This can be CORE, STANDARD or CUSTOM. CORE and STANDARD attributes are supplied by default. CORE attributes cannot be updated or deleted. STANDARD attributes cannot be deleted, but their mutable properties can be updated. CUSTOM attributes can be deleted, and their mutable properties can be updated. New attributes are created with a schema type of CUSTOM.
attributes.subAttibutes Array Optional Mutable The list of sub-attributes of this attribute. Only COMPLEX attribute types can have sub-attributes, and only one-level of nesting is allowed. The leaf attribute definition must have a type of STRING or JSON. A COMPLEX attribute definition must have at least one child attribute definition.
attributes.type String Optional Mutable The type of the attribute. This can be STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, it defaults to STRING. COMPLEX and BOOLEAN attributes cannot be created, but standard attributes of those types may be updated. JSON attributes are limited by size (total size must not exceed 16KB).
attributes.unique Boolean Required Mutable Indicates whether or not the attribute must have a unique value within the PingOne environment. This is a required property only for POST and PUT operations, and cannot be omitted or explicitly set to null.
attributes.multiValued Boolean Optional Mutable Indicates whether the attribute has multiple values or a single one. This value can only change from false to true. You cannot change this from true to false. Maximum number of values stored is 1,000.
description String Optional Mutable The description of the schema.
environment.id String N/A Immutable The environment resource’s unique identifier.
id String Required Immutable The schema’s unique identifier.
name String Required Mutable The schema name.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.