Learn how to customize Ory Identity Schemas
Ory supports custom Identity Schemas. The Identity Schema is a JSON Schema that describes the traits that make up an identity.
Create custom Identity Schema
Follow these steps to create a custom Identity Schema in The Ory Network:
- Open the Ory Console and sign in.
- Select Customize → Identity Schema from the left navigation bar.
- Using the dropdown menu, select one of the preset schemas or the empty template as the starting point for your custom schema.
- Check the Customize Identity Schema box to enable editing of the schema.
- Adjust the schema to your needs - adjust or remove traits.
- Define the name of the custom schema in the Identity Model Schema text box.
- Click the Update button to save.
Customize fields
The traits of an Identity Schema are specified under
"traits": {
"type": "object",
"properties": {
Each trait translates into a field on the user-facing frontend. For example, the "email and password" preset defines two traits - email and password:
"traits": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"title": "E-Mail",
"ory.sh/kratos": {
"credentials": {
"password": {
"identifier": true
}
},
"recovery": {
"via": "email"
},
"verification": {
"via": "email"
}
}
}
},
"required": [
"email"
],
"additionalProperties": false
}
This Identity Schema translates into the following sign-up screen:
The part highlighted below defines the identity's email
for the email+password flow in The Ory Network. It also includes a
method for recovery
as well as
verification
.
Only the email
method is available (recovery/verification via a link sent in an email).
"traits": {
"type": "object",
"properties": {
+ "email": {
+ "type": "string",
+ "format": "email",
+ "title": "E-Mail",
+ "ory.sh/kratos": {
+ "credentials": {
+ "password": {
+ "identifier": true
+ }
+ },
"recovery": {
"via": "email"
},
"verification": {
"via": "email"
}
}
}
},
"required": [
"username"
],
"additionalProperties": false
}
To add traits to the Identity Schema, add them inside the traits "properties"
"traits": {
"type": "object",
"properties": {
+ "customtrait": {
+ "type": "string",
+ "title": "Your Custom Trait Title"
+ }
}
}
for example the GitHub Handle as string
:
"traits": {
"type": "object",
"properties": {
"handle": {
"type": "string",
"title": "Your GitHub Handle"
}
}
}
or a checkbox as boolean
:
"traits": {
"type": "object",
"properties": {
"newsletter": {
"type": "boolean",
"title": "Newsletter subscription"
}
}
}
Possible values for the type
are string
, number
, integer
, boolean
.
Use string
for text fields, boolean
for checkboxes fields, integer
or number
for integral or floating-point numbers. If
you want to know more about these types, please refer to the
json-schema documentation.
The title
of each field is what the user as description or sample input. After adding the above examples the sign-up screen
would look like so:
Change existing Identity Schemas
While it's not possible to directly edit existing Identity Schemas, you can make revisions.
For example, an Identity Schema named "Customer Type 1" exists and you would like to make changes to it:
- Select the "Customer Type 1" Identity Schema and press
Customize Identity Schema
. - Make the necessary changes.
- Enter a new name, for example "Customer Type 2".
- Press the
Enter
key orUpdate
to save it.
Add identity metadata
It is possible to add metadata to an identity, either as a protected field that can only be read by the admin or as a public field that can be read by the user as well. Visit the Manage Identity Metadata documentation for details on how to add metadata to identities.
Additional properties
The additionalProperties
keyword is used to control the handling of properties whose names aren't listed in the properties keyword. This has no effect and
should be set to false.
"additionalProperties": false
Reference Identity Schema
The following Identity Schema includes first/last and nickname, as well as number fields for the users' age. There are also two true/false fields for specifying the newsletter subscription and enterprise status.
Please note that this is just a reference Identity Schema, for practical uses it contains probably too many traits.
{
"$id": "https://schemas.ory.sh/presets/kratos/identity.basic.schema.json",
"title": "Person",
"type": "object",
"properties": {
"traits": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"title": "E-Mail",
"ory.sh/kratos": {
"credentials": {
"password": {
"identifier": true
}
},
"recovery": {
"via": "email"
},
"verification": {
"via": "email"
}
}
},
"name": {
"type": "object",
"properties": {
"first": {
"type": "string",
"title": "Your First name"
},
"last": {
"type": "string",
"title": "Your Last name"
},
"nickname": {
"type": "string",
"title": "Your Nickname"
}
}
},
"age": {
"type": "integer",
"title": "How old are you?"
},
"newsletter": {
"type": "boolean",
"title": "Newsletter subscription"
},
"enterprise": {
"type": "boolean",
"title": "Are you an Enterprise customer?"
}
},
"required": ["email"],
"additionalProperties": false
}
}
}
This is what the above Identity Schema would look like on the sign-up screen: