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. Custom attributes can be added 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. You can add a maximum of 100 custom string attributes and 100 custom JSON attributes. The total size of the values of all custom attributes must not exceed 16KB.

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.

Schemas data model

Property Description
attributes.description A string that specifies an optional property that specifies the 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 A string that specifies an optional property that specifies 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 A boolean that specifies whether or not the attribute is enabled. This is a required property for POST and PUT operations; it cannot be omitted or explicitly set to null. Disabled attributes are ignored on create/update and not returned on read.
attributes.environment.id A string that specifies the identifier of the environment resource referenced by this relationship.
attributes.id A string that specifies the resource’s unique identifier.
attributes.ldapAttribute A string that specifies the LDAP attribute.
attributes.name A string that specifies 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 A boolean that specifies whether or not the attribute is required. Required attributes must be provided a value during create/update. Defaults to false if not provided.
attributes.schema.id A string that specifies the identifier of the resource referenced by this relationship.
attributes.schemaType A string that specifies the schema type of the attribute. It may be one of CORE, STANDARD or CUSTOM. Core and standard attributes are present out-of-the-box. Core attributes may not be updated or deleted. Standard attributes may not be deleted, but their mutable properties may be updated. Custom attributes may be deleted, and their mutable properties may be updated. New attributes are created with a schema type of CUSTOM.
attributes.subAttibutes An array that specifies the list of sub-attributes of this attribute. Only COMPLEX types may have sub-attributes, but 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 A string that specifies the the type of the attribute. It may be one of STRING, JSON, BOOLEAN, or COMPLEX. If the type is not provided during creation, then it defaults to STRING. Complex and boolean attributes may not be created, but standard attributes of those types may be updated. JSON attributes cannot be mapped to OpenID Connect or SAML attributes. In addition, JSON attributes are also limited by size (total size must not exceed 16KB).
attributes.unique A boolean that specifies whether or not the attribute must have a unique value within the environment. This is a required property for POST and PUT operations; it cannot be omitted or explicitly set to null.
description A string that specifies the description of the schema.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the resource name.

Reserved attribute names

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

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.