Identity schema best practices
Follow this guide to learn about best practices when creating custom identity schemas.
The identity schema isn't the right place to store data that should be obfuscated from the user. Users can see traits and other
data - except credentials - using the
/sessions/whoami endpoint. Users are also able to edit identity traits.
Don't store sensitive internal data in the identity's traits. Use the
metadata_admin field for this purpose.
Read this document for information how to use metadata that can't be viewed or changed by the end user.
Keep your data lean
- Do not add too many fields to your identities. Keep the number of fields well below 15.
- Do not store business logic in your identities. Store this information in other systems. This includes credit card information, shipping addresses, shopping cart items, or user preferences.
- Do store profile data that is used across your system. This includes the usernames, email addresses, phone numbers, first names, and last names.
Updating identity schemas
When using the Ory CLI and Ory configuration files, use versioning to keep track of changes to your identity schema. This allows you to gradually update your identity schema without affecting existing identities.
Let's say that you just defined your first identity schema:
- id: user_v0
After a few weeks, you decide that you want to add additional fields or that you need to break compatibility with your current
schema. To do that, add another version of the schema to the configuration and change the
default_schema_id to use the new
- id: user_v0
- id: user_v1
With this configuration in place, existing identities work as expected and continue to use the
user_v0 identity schema. All
newly created identities will use
When you're ready to migrate all identities that use the
user_v0 to the
user_v1 schema, use the REST API to list all
identities using the old version and perform the required data transformations.
To make sure usernames or traits satisfy a specific regex (for example only alphanumeric characters), they can be sanitized. To sanitize usernames add regular expressions to the identity Schema. To sanitize usernames coming from third-party OIDC providers like Google or GitHub write JSonnet.