PingOne Platform APIs

Schemas

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.

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, refer to 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 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.

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.

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

N/A

Read only

Indicates whether or not the attribute is required. The value of this property for custom attributes is always 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.

Schemas events generated

Refer to Audit Reporting Events for the events generated.

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.