Schemas service


Schemas

The schemas service gives 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.

Note: When all 100 custom string (or 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.

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 schemas service supports the following capabilities:

  • The ability to use out-of-the-box SCIM-based 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 define the behavior and data requirements of special attributes such as passwords, usernames, email addresses, and phone numbers.

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 API operations

The schemas service supports the following endpoint operations:

For hands-on experience with the schemas API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Schemas data model

Property Description
attributes.id 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. Disabled attributes are ignored on create/update and not returned on read. This is a required property for POST and PUT operations.
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 A string 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 orJSON. ACOMPLEX` 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.
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.
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.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
404 The specified object doesn’t exist.
409 Uniqueness constraint violation (e.g., duplicate name).

Endpoint examples

Get schemas

The following sample shows the GET /environments/{environmentId}/schemas operation to return a list of all schema resources for the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/schemas" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas"
        }
    },
    "_embedded": {
        "schemas": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9"
                    },
                    "attributes": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes"
                    }
                },
                "name": "User",
                "description": "User resource stored in the directory",
                "id": "54175490-6157-4695-b72d-643bbf366db9",
                "environment": {
                    "id": "000c2764-3489-4d34-a707-b23dd488049c"
                }
            }
        ]
    },
    "count": 1,
    "size": 1
}

Get one schema

To get data for a single schema resource, the GET /environments/{environmentId}/schemas/{schemaId} operation returns data only for the schema resource with the ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

You can also retrieve the specified schema with its attributes expanded using GET /environments/{environmentId}/schemas/{schemaId}?expand=attributes. The output returned represents the schema for a single resource and all its attributes. Attributes and their values are listed in the _embedded HAL links.

"_embedded": {
    "attributes": [
        {
            "_links": {
                "self": {
                    "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/28402364-9872-4517-bb10-bd46b77bdea5"
                }
            },
            "id": "28402364-9872-4517-bb10-bd46b77bdea5",
            "environment": {
                "id": "000c2764-3489-4d34-a707-b23dd488049c"
            },
            "name": "preferredLanguage",
            "displayName": "Preferred Language",
            "description": "The attribute description.",
            "schemaType": "STANDARD",
            "type": "STRING",
            "unique": false,
            "enabled": true,
            "required": false,
            "schema": {
                "id": "54175490-6157-4695-b72d-643bbf366db9"
            },
            "javaType": "java.lang.String"
        }

Get all schema attributes

The following sample shows the GET /environments/{environmentId}/schemas/{schemaId}/attributes operation to return a list of all attributes associated with the specified schema resource.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/schemas/{schemaId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes"
        }
    },
    "_embedded": {
        "attributes": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/28402364-9872-4517-bb10-bd46b77bdea5"
                    }
                },
                "id": "28402364-9872-4517-bb10-bd46b77bdea5",
                "environment": {
                    "id": "000c2764-3489-4d34-a707-b23dd488049c"
                },
                "name": "preferredLanguage",
                "displayName": "Preferred Language",
                "description": "Preferred Language attribute description.",
                "schemaType": "STANDARD",
                "type": "STRING",
                "unique": false,
                "enabled": true,
                "required": false,
                "schema": {
                    "id": "54175490-6157-4695-b72d-643bbf366db9"
                },
                "javaType": "java.lang.String"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/25add3f1-be2c-47e8-9462-3bf11e437a81"
                    }
                },
                "id": "25add3f1-be2c-47e8-9462-3bf11e437a81",
                "environment": {
                    "id": "000c2764-3489-4d34-a707-b23dd488049c"
                },
                "name": "address",
                "displayName": "Address",
                "description": "The user's address (optional)",
                "schemaType": "STANDARD",
                "type": "COMPLEX",
                "unique": false,
                "enabled": true,
                "required": false,
                "subAttributes": [
                    {
                        "name": "streetAddress",
                        "displayName": "Street Address",
                        "description": "The full street address attribute description.",
                        "schemaType": "STANDARD",
                        "type": "STRING",
                        "unique": false,
                        "enabled": true,
                        "required": false,
                        "javaType": "java.lang.String"
                    },
                    {
                        "name": "locality",
                        "displayName": "Locality",
                        "description": "The city or locality component of the address.",
                        "schemaType": "STANDARD",
                        "type": "STRING",
                        "unique": false,
                        "enabled": true,
                        "required": false,
                        "javaType": "java.lang.String"
                    },
                    {
                        "name": "region",
                        "displayName": "Region",
                        "description": "The state or region component of the address.",
                        "schemaType": "STANDARD",
                        "type": "STRING",
                        "unique": false,
                        "enabled": true,
                        "required": false,
                        "javaType": "java.lang.String"
                    },
                    {
                        "name": "postalCode",
                        "displayName": "Postal Code",
                        "description": "The zip code or postal code component of the address.",
                        "schemaType": "STANDARD",
                        "type": "STRING",
                        "unique": false,
                        "enabled": true,
                        "required": false,
                        "javaType": "java.lang.String"
                    },
                    {
                        "name": "countryCode",
                        "displayName": "Country Code",
                        "description": "The country code attribute description.",
                        "schemaType": "STANDARD",
                        "type": "STRING",
                        "unique": false,
                        "enabled": true,
                        "required": false,
                        "javaType": "java.lang.String"
                    }
                ],
                "schema": {
                    "id": "54175490-6157-4695-b72d-643bbf366db9"
                },
                "javaType": "java.lang.String"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/dba5a79c-0fac-4a1a-b8d7-9052dc12ae94"
                    }
                },
                "id": "dba5a79c-0fac-4a1a-b8d7-9052dc12ae94",
                "environment": {
                    "id": "000c2764-3489-4d34-a707-b23dd488049c"
                },
                "name": "timezone",
                "displayName": "Timezone",
                "description": "The time zone description.",
                "schemaType": "STANDARD",
                "type": "STRING",
                "unique": false,
                "enabled": true,
                "required": false,
                "schema": {
                    "id": "54175490-6157-4695-b72d-643bbf366db9"
                },
                "javaType": "java.lang.String"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/8d0a0060-c16d-4c8d-ae27-a4e8b08514fc"
                    }
                },
                "id": "8d0a0060-c16d-4c8d-ae27-a4e8b08514fc",
                "environment": {
                    "id": "000c2764-3489-4d34-a707-b23dd488049c"
                },
                "name": "shirtSize",
                "displayName": "Shirt Size.",
                "description": "Shirt size attribute description.",
                "schemaType": "CUSTOM",
                "type": "STRING",
                "unique": false,
                "enabled": true,
                "required": false,
                "schema": {
                    "id": "54175490-6157-4695-b72d-643bbf366db9"
                },
                "javaType": "java.lang.String"
            },

            ...
          ]
        },
      "count": 22,
      "size": 22
  }

Get one schema attribute

To get data for a single attribute resource, the the GET /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} operation returns data only for the attribute resource with the ID specified in the request URL.

curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/{attributeId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

Custom string attributes in user resource requests

You can use custom string attributes in a filtering expression to fine-tune the user response data. The following sample shows a GET /environments/{environmentId}/users request that returns users with a shirtSize custom attribute value set to Large.

curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/users?filter=shirtSize%20eq%20%Large%22" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

Create schema attributes

The following sample shows the POST /environments/{environmentId}/schemas/{schemaId}/attributes operation to add a new custom attribute to a specified schema resource. In the request body, the name property is required. All other properties are optional.

curl -X "POST" "https://api.pingone.com/v1/{environmentId}/schemas/{schemaId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "description": "An optional property that specifies the description of the new attribute.",
    "displayName": "An optional property that specifies the display name of the attribute.",
    "enabled": false,
    "name": "customAttribute-101",
    "required": false,
    "type": "STRING",
    "unique": false
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/8d0a0060-c16d-4c8d-ae27-a4e8b08514fc"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c"
        },
        "schema": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9"
        }
    },
    "id": "8d0a0060-c16d-4c8d-ae27-a4e8b08514fc",
    "environment": {
        "id": "000c2764-3489-4d34-a707-b23dd488049c"
    },
    "name": "customAttribute-101",
    "displayName": "An optional property that specifies the display name of the attribute.",
    "description": "An optional property that specifies the description of the attribute.",
    "schemaType": "CUSTOM",
    "type": "STRING",
    "unique": false,
    "enabled": true,
    "required": false,
    "schema": {
        "id": "54175490-6157-4695-b72d-643bbf366db9"
    },
    "javaType": "java.lang.String"
}

Update schema attributes

The following sample shows the PATCH /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} operation to update existing attribute properties. For the PATCH operation, the update operation targets only those attribute property values specified in the request body. Attribute properties omitted from the request body are not updated or removed.

curl -X "PATCH" "https://api.pingone.com/v1/environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "name": "NewName",
    "schemaType": "CORE",
    "type": "STRING",
    "unique": true,
    "enabled": false
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/8d0a0060-c16d-4c8d-ae27-a4e8b08514fc"
        }
    },
    "id": "8d0a0060-c16d-4c8d-ae27-a4e8b08514fc",
    "environment": {
        "id": "000c2764-3489-4d34-a707-b23dd488049c"
    },
    "name": "NewName",
    "displayName": "An optional property that specifies the display name of the attribute.",
    "description": "An optional property that specifies the description of the attribute. ",
    "schemaType": "CORE",
    "type": "STRING",
    "unique": true,
    "enabled": false,
    "required": false,
    "schema": {
        "id": "54175490-6157-4695-b72d-643bbf366db9"
    },
    "javaType": "java.lang.String"
}

Note: You can also update existing attribute properties using PUT /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId}. The PUT operation removes any existing attribute properties omitted from the request body.

Delete attributes

The following sample shows the DELETE /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} operation to delete the attribute identified in the request URL by its ID.

curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \

For successful delete operations, a 204 NO CONTENT message is returned by the request.