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.

Note:A user profile is the aggregate of all user identity and resource data for the user, including the user’s relationships, roles, devices, and attributes. Each user profle has a maximum cumulative size of 16 Kb. This can, for example, constrain the number and size of the custom attributes you create for a user schema.

For more information about schemas, see User Attributes in the PingOne Admin Guide.

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:

Core attributes (for example, id or username) cannot be modified in any way.
Standard attributes (for example, email, preferred language, address) cannot be modified except to configure these flags: enabled and unique.
Custom attributes (for example, ssn or shirtSize) can be modified except for the name, type and schema properties. The multiValued property of custom attributes can only be changed from false or null to true. The required property is ignored if included in a create request body (defaults to false) and returns an error if included in an update request body.

The schemas service supports the following capabilities:

The ability to use out-of-the-box user schema custom attributes.
The ability to select a subset of the PingOne standard schema that is relevant for users stored in an environment.
The ability to add custom attributes to the schema that are used for the same purposes as PingOne default attributes.
The ability to add custom attributes that support multiple values.
The ability to define the behavior and data requirements of special attributes such as passwords, usernames, email addresses, and phone numbers.

The request examples 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 {#custom-attributes}

Custom attributes convey additional information about the user to applications. 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.

Note: Although you can use SCIM filtering in request query parameters for STRING custom attributes, you cannot use SCIM filtering for JSON custom attributes.

If the custom attribute has multiple values, then the attribute will be multi-valued in the token or assertion as well. 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 200 custom string attributes and 200 custom JSON attributes. Bear in mind that the maximum size of the entire user profile is 16 Kb.

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.

Note: When all 200 custom string attributes or all 200 custom JSON attributes are used, and one attribute is deleted, a new attribute cannot be defined until all of the existing data for the deleted attribute has been removed from all user resources in the directory.

Reserved attribute names

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

password
devices
roleAssignments
pairingCodes
linkedAccounts
environment
population
account

Enumerated values and regular expressions

An attribute is enumerated if the attributes.enumeratedValues[] property is present and has at least one unarchived attributes.enumeratedValues[].value. An attributes.enumeratedValues[].value cannot be deleted, but it can be archived. If all attributes.enumeratedValues[].value objects are archived, the attributes.enumeratedValues[] property is removed from the attribute. An existing attribute cannot be made enumerated. It is possible to add attributes.enumeratedValues[] objects to an existing enumerated attribute and to unarchive existing archived values.

A regular expression can be added to an attribute to validate the client-provided value. An attribute cannot be both regex and enumerated. However, a value matching a regular expression can be multi-valued or unique. A list of test case values that the pattern should match and should not match can also be provided to help validate that the pattern is correct.

Schema attributes POST, PUT, PATCH data model

Property	Type	Required?	Mutable?	Description
`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.
`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.
`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.
`enumeratedValues[]`	Array	Optional	Mutable	An array of enumerated values. Maximum number of enumerations is 100.
`enumeratedValues[].value`	String	Required	Mutable	A string that specifies the immutable value. Values are case sensitive; two values that differ only by case are not allowed. Required if `enumeratedValues[]` is set.
`enumeratedValues[].archived`	Boolean	Optional	Mutable	A boolean that specifies whether the enumerated value is archived. Archived values cannot be added to a user, but existing archived values are preserved. This allows clients that read the schema to know all possible values of an attribute.
`enumeratedValues[].description`	String	Optional	Mutable	A string that specifies the description of the enumerated value.
`environment.id`	String	N/A	Immutable	The identifier of the environment resource referenced by this relationship.
`id`	String	N/A	Immutable	The attribute’s unique identifier.
`ldapAttribute`	String	Required	Immutable	The unique identifier for the LDAP attribute.
`multiValued`	Boolean	Optional	Mutable	A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
`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.
`regexValidation`	Object	Optional	Mutable	Object representation of the optional regular expression representation of this attribute.
`regexValidation.pattern`	String	Required	Mutable	A string that specifies the regular expression to which the attribute must conform. Required if `regexValidation` is set.
`regexValidation.requirements`	String	Required	Mutable	A string that specifies a developer friendly description of the regular expression requirements. Required if `regexValidation` is set.
`regexValidation.valuesPatternShouldMatch`	Array	Optional	Mutable	An array that specifies the list of strings matching the regular expression.
`regexValidation.valuesPatternShouldNotMatch`	Array	Optional	Mutable	An array that specifies the list of strings not matching the regular expression.
`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`.
`schema.id`	String	Required	Immutable	The identifier of the resource referenced by this relationship.
`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`.
`subAttributes`	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.
`subAttributes.description`	String	Optional	Mutable	A description of the sub-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.
`subAttributes.displayName`	String	Optional	Mutable	The display name of the sub-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.
`subAttributes.enabled`	Boolean	Required	Mutable	Indicates whether or not the sub-attribute is enabled. This is a required property only for `POST` and `PUT` operations, and cannot be omitted or explicitly set to null. Disabled sub-attributes are ignored for `POST` or `PUT`, and are not returned for `GET` operations.
`subAttributes.name`	String	Required	Mutable	The name of the sub-attribute. The sub-attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must start with a letter and may be followed by letters, numbers or hyphens.
`subAttributes.required`	Boolean	Optional	Mutable	Indicates whether or not the sub-attribute is required. Required attributes must be provided a value for `POST` and `PUT`. Defaults to `false`.
`subAttributes.schemaType`	String	Required	Mutable	The schema type of the sub-attribute. This can be `CORE`, `STANDARD` or `CUSTOM`. `CORE` and `STANDARD` sub-attributes are supplied by default. `CORE` sub-attributes cannot be updated or deleted. `STANDARD` sub-attributes cannot be deleted, but their mutable properties can be updated. `CUSTOM` sub-attributes can be deleted, and their mutable properties can be updated. New sub-attributes are created with a schema type of `CUSTOM`.
`subAttributes.type`	String	Optional	Mutable	The type of the sub-attribute. This can be `STRING`, `JSON`, `BOOLEAN`, or `COMPLEX`. If the type is not provided during creation, it defaults to `STRING`. `COMPLEX` and `BOOLEAN` sub-attributes cannot be created, but standard sub-attributes of those types may be updated. `JSON` sub-attributes are limited by size (total size must not exceed 16KB).
`subAttributes.unique`	Boolean	Required	Mutable	Indicates whether or not the sub-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.
`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).
`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.

Schema attributes GET response model

Property	Type	Required?	Mutable?	Description
`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.multiValued`	Boolean	Optional	Mutable	A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
`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.regexValidation`	Object	Optional	Mutable	Object representation of the optional regular expression representation of this attribute.
`attributes.regexValidation.pattern`	String	Required	Mutable	A string that specifies the regular expression to which the attribute must conform. Required if `attributes.regexValidation` is set.
`attributes.regexValidation.requirements`	String	Required	Mutable	A string that specifies a developer friendly description of the regular expression requirements. Required if `attributes.regexValidation` is set.
`attributes.regexValidation.valuesPatternShouldMatch`	Array	Optional	Mutable	An array that specifies the list of strings matching the regular expression.
`attributes.regexValidation.valuesPatternShouldNotMatch`	Array	Optional	Mutable	An array that specifies the list of strings not matching the regular expression.
`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.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.subAttributes`	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.subAttributes.description`	String	Optional	Mutable	A description of the sub-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.subAttributes.displayName`	String	Optional	Mutable	The display name of the sub-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.subAttributes.enabled`	Boolean	Required	Mutable	Indicates whether or not the sub-attribute is enabled. This is a required property only for `POST` and `PUT` operations, and cannot be omitted or explicitly set to null. Disabled sub-attributes are ignored for `POST` or `PUT`, and are not returned for `GET` operations.
`attributes.subAttributes.name`	String	Required	Mutable	The name of the sub-attribute. The sub-attribute name must be provided during creation, must not be empty and must not exceed 256 characters. It must start with a letter and may be followed by letters, numbers or hyphens.
`attributes.subAttributes.required`	Boolean	Optional	Mutable	Indicates whether or not the sub-attribute is required. Required attributes must be provided a value for `POST` and `PUT`. Defaults to `false`.
`attributes.subAttributes.schemaType`	String	Required	Mutable	The schema type of the sub-attribute. This can be `CORE`, `STANDARD` or `CUSTOM`. `CORE` and `STANDARD` sub-attributes are supplied by default. `CORE` sub-attributes cannot be updated or deleted. `STANDARD` sub-attributes cannot be deleted, but their mutable properties can be updated. `CUSTOM` sub-attributes can be deleted, and their mutable properties can be updated. New sub-attributes are created with a schema type of `CUSTOM`.
`attributes.subAttributes.type`	String	Optional	Mutable	The type of the sub-attribute. This can be `STRING`, `JSON`, `BOOLEAN`, or `COMPLEX`. If the type is not provided during creation, it defaults to `STRING`. `COMPLEX` and `BOOLEAN` sub-attributes cannot be created, but standard sub-attributes of those types may be updated. `JSON` sub-attributes are limited by size (total size must not exceed 16KB).
`attributes.subAttributes.unique`	Boolean	Required	Mutable	Indicates whether or not the sub-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.
`description`	String	Optional	Mutable	The description of the attribute.
`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.
`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.
`environment.id`	String	N/A	Immutable	The environment resource’s unique identifier.
`id`	String	Required	Immutable	The attribute’s unique identifier.
`multiValued`	Boolean	Optional	Mutable	A boolean that specifies whether the attribute has multiple values or a single one. This value can only change from false to true, as changing from true to false is not allowed. Maximum number of values stored is 1,000.
`name`	String	Required	Mutable	The attribute name.
`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`.
`schema.id`	String	Optional	Mutable	The schema’s unique identifier.
`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`.
`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).
`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.

Schemas GET response model

Property	Type	Required?	Mutable?	Description
`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.
`schemas.description`	String	Optional	Mutable	The description of the schema.
`schemas.environment.id`	String	Optional	Mutable	The unique identifier of the environment containing the schema.
`schemas.id`	String	Optional	Mutable	The schema’s unique identifier.
`schemas.name`	String	Required	Mutable	The schema name.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service	Event
schemas	ATTRIBUTE.CREATED
schemas	ATTRIBUTE.UPDATED
schemas	ATTRIBUTE.DELETED

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.