Design your identity schema

To align identities from your current system with Ory, you can customize the identity schema to meet your specific requirements. This ability to customize the identity schema means you can enhance and improve your old identity schema during the migration process.

The identity schema, which implements the JSON Schema standard, defines the types of data the system can store for users—such as names, email addresses, phone numbers, or birthdays—and controls business logic by specifying which fields serve as login identifiers and which are used for verification or recovery.

Identities have two main data types: traits (attributes that users can modify themselves, such as username or email address) and metadata (attributes defined by system admins that can only be updated through admin APIs. Metadata is useful for storing information like subscription status, legacy user IDs, or basic roles). Metadata comes in two forms: public (visible to users via session endpoints) and admin (only accessible through admin APIs).

Best practices for identity schema design:

Do:

• Use the identity schema for basic profile information that's used across your system, including usernames, email addresses, phone numbers, first names, and last names
• Store authentication-related data like login identifiers and verification addresses in traits
• Use metadata fields for system-managed information like legacy user IDs, subscription status, or basic roles

Don't:

• Store sensitive internal data or information that should be obfuscated from users in the identity schema, since users can see traits and other data (except credentials) using the /sessions/whoami endpoint
• Store business logic or application-specific data like credit card information, shipping addresses, shopping cart items, or detailed user preferences—keep this in your application database instead

Ory provides preset schemas to help you get started quickly. For detailed guidance on customizing schemas, see the identity schemas documentation.