Identity schema

The identity schema implements the JSON Schema Standard and allows you to adjust Ory specifically to your requirements. The identity schema specifies the types of data the system can store for users, such as their names, email addresses, phone numbers, or birthdays. Through schemas, you can also define additional fields that can be added to user profiles, such as a job titles, company names, or locales.

The identity schema not only defines the data model of your identities, but also controls business logic and allows you to:

• Define which field is used as the identifier when logging in: username, email, phone number, or a combination of those.
• Define fields which are used to verify or recover the user's identity: email, phone number, or a combination of those.

Depending on your setup, you can benefit from defining different identity schemas for different groups of users, such as customer support and end users. This allows to tailor the user experience and security measures to the specific needs and requirements of each group.

The Ory Network provides default presets to help users get started with creating and managing identity schemas for their systems.

info

Identity schemas are a powerful tool with a learning curve. When getting started, use one of the presets Ory provides to make your life easier. Use the preset as a starting point and customize the identity schema to your needs later.

Presets

The Ory Network provides five identity schema presets. Use a preset URL (for example preset://email) when configuring your project. Each preset defines which traits are available and which credentials and recovery/verification channels are enabled.

Profile with email - preset://email

With this preset, identities have a single trait, the email. The email is the login identifier and is used for email verification and for account recovery:

// Identity example
{
  id: "6e9d3d30-f93e-4630-901f-c2096953723d",
  traits: {
    email: "foo@bar.com",
  },
}

Profile with username - preset://username

This preset is useful for applications that don't need the user's email address and don't prioritize a high degree of user anonymity. Without an email, users can not send recovery links to their email. They will not be able to regain access to their account.

With this preset, every identity has a single trait - the username. The username is the login identifier:

// Identity example
{
  id: "6e9d3d30-f93e-4630-901f-c2096953723d",
  traits: {
    username: "some-username",
  },
}

Profile with SMS - preset://sms

This preset uses a phone number as the login identifier. Verification is done through SMS. Account recovery is not configured in this preset.

Identities have a single trait, phone_number.

// Identity example
{
  id: "6e9d3d30-f93e-4630-901f-c2096953723d",
  traits: {
    phone_number: "+1234567890",
  },
}

Profile with email, name, newsletter opt-in - preset://basic

This preset extends the email preset with additional profile fields: first name, last name, and a newsletter subscription checkbox. The email is the login identifier and is used for recovery and verification.

// Identity example
{
  id: "6e9d3d30-f93e-4630-901f-c2096953723d",
  traits: {
    email: "foo@bar.com",
    name: {
      first: "Foo",
      last: "Bar",
    },
    newsletter: true,
  },
}

Blank profile template - preset://blank

An empty schema with no traits defined. Use this as a starting point when building a fully custom identity schema from scratch. This preset has no login identifiers, recovery, or verification configured — you must add them yourself.

// Identity example
{
  id: "6e9d3d30-f93e-4630-901f-c2096953723d",
  traits: {},
}