Schemas

The Schemas API provides operations to manage custom user profiles as well as endpoints to discover the structure of the log stream configuration.

Okta's Universal Directory allows admins to define custom user profiles for Okta users and apps. Okta adopts a subset of JSON Schema Draft 4 as the schema language to describe and validate extensible user profiles. For log stream schemas, Okta uses JSON Schema Draft 2020-12. JSON Schema is a lightweight declarative format for describing the structure, constraints, and validation of JSON documents.

Note: Okta implements only a subset of JSON Schema Draft 4 and JSON Schema Draft 2020-12. This document describes which parts apply to Okta, and any extensions Okta has made to JSON Schema Draft 4 and JSON Schema Draft 2020-12.

Unique Attributes

You can enforce uniqueness for custom properties in Okta user profiles or the Okta group profile, such as an employee identification number. You can declare a maximum of five unique properties for each user type and five unique properties in the Okta group profile. Different user types can have the same or different unique properties (up to the limit of five per type).

Unique properties in Okta user profiles share a single namespace across all user types in an org. If user types A and B both contain the property ice cream and you identify it as unique in both profiles, then if a user of type A has the value chocolate, no other users of type A or B (or any other user type that declares ice cream as unique) can have that value.

Properties that aren't unique also aren't tracked for uniqueness. Suppose the property candy is unique in type E and not unique in type F. If a user of type E has the value caramel for the candy property, no other users of type E can also have the value caramel, but any number of users of type F can already have or later be assigned the value caramel. Furthermore, because candy is not unique in type F, any values users of type F may have are not considered when enforcing uniqueness for users of type E. No matter how many users of type F already have the value cotton, it might be assigned to a user of type E as long as no other such user already has that value.

If you attempt to create or update a user with a duplicate value for a custom user property with a uniqueness restriction, the user creation or update operation fails. The user isn't created or updated until you enter a unique value. Similarly, creating or updating a group fails when the request contains a value for a unique custom group property that is duplicated by another group.

null values don't enter into the uniqueness calculation. If the unique property isn't also specified as being required, you can also omit the value entirely. Multiple users or groups can omit the property and not violate uniqueness.

To enforce uniqueness for custom properties, you can either add new unique custom properties or update existing custom properties to be unique.

Add new unique custom property

You can use the add property to user profile schema request or the add property to group profile schema request to add one or more unique custom user or group properties. Specify "unique": true on the properties to be marked as unique. The response shows the properties with "unique": "UNIQUE_VALIDATED" and uniqueness is then enforced on those properties.

Update existing custom property to be unique

You can use the update user profile schema property request or the update group profile schema property request to mark existing custom user or group properties as unique by specifying "unique": true on the properties to be marked as unique.

After the request to mark existing custom properties as unique is submitted, an asynchronous validation check is performed to make sure that there are no existing duplicate entries. If you have a significant number of users or groups, the validation can take some time.

A uniqueness status of "unique": "PENDING_UNIQUENESS" indicates that the validation check is still in progress. Use the Universal Directory page in the Admin Console (Directory > Directory Integrations) to track the status of the validation check. After the validation completes, if you submit a retrieve user schema request or a retreive group schema request, the property's uniqueness status changes to UNIQUE_VALIDATED if no duplicate records are found, and uniqueness is then enforced on that property. Otherwise, if duplicate records are found, the unique attribute of the schema property isn't shown in the get schema request and uniqueness isn't enforced on the schema property.

Update existing unique custom property to be non-unique

You can use the update user profile schema property request or the update group profile schema property request to change existing unique custom user or group properties to be non-unique by specifying "unique": false on the properties to be changed to non-unique. The response shows the properties without the unique attribute and the uniqueness constraint is then removed on those properties.

Note: If multiple user types declare a property as unique and you remove the uniqueness constraint on one type, there may be a delay before users of other types that declare the property as unique can be assigned values formerly held by users of the first type.