Work with custom schemas


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.

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 that 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. For more information, see Work with user roles.

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/000c2764-3489-4d34-a707-b23dd488049c/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
}

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 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/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/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
  }

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'

Add an attribute to a schema

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/environments/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/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 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/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/8d0a0060-c16d-4c8d-ae27-a4e8b08514fc" \
-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 an attribute

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/000c2764-3489-4d34-a707-b23dd488049c/schemas/54175490-6157-4695-b72d-643bbf366db9/attributes/8d0a0060-c16d-4c8d-ae27-a4e8b08514fc" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \

For successful delete operations, a 204 NO CONTENT message is returned by the request. Deleted attributes are removed from all user resources in the directory.