Validate an Ory Kratos username with an identity schema
Constrain a username to 4–20 ASCII letters, digits or underscores. Put the rule in the identity schema and distinguish validation from identifier uniqueness.
A Kratos identity schema describes the traits an identity may contain. A username rule belongs there so that validation happens on the server, including when a caller bypasses the browser form. Client-side validation can improve feedback, but cannot replace this boundary.
For a username containing 4–20 ASCII letters, digits or underscores, use an anchored JSON Schema pattern. The anchors matter: an unanchored pattern can match a substring inside a longer, invalid value.
Put the rule under traits
This is a complete minimal username identity schema, for example identity.schema.json:
{
"$id": "https://example.com/schemas/username-v1.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Username identity",
"type": "object",
"properties": {
"traits": {
"type": "object",
"properties": {
"username": {
"type": "string",
"title": "Username",
"minLength": 4,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_]+$",
"ory.sh/kratos": {
"credentials": {
"password": { "identifier": true }
}
}
}
},
"required": ["username"],
"additionalProperties": false
}
},
"required": ["traits"]
}
Separating length from the allowed-character pattern makes the constraints easier to inspect. The equivalent single pattern is ^[A-Za-z0-9_]{4,20}$. Here ASCII is a deliberate product choice, not a requirement for all usernames.
The password identifier annotation tells Kratos to use this trait for password login. It does not enable the password method in the deployment configuration. A username-only schema also has no email recovery address; design recovery separately before using it for real accounts.
Attach and test the schema
For a self-hosted deployment, register the schema under identity.schemas, with its own ID and a file:/// URL pointing to the mounted file, then select the intended default schema ID. Ory Network manages schemas through its own project configuration. Editing an unreferenced local JSON file changes neither deployment.
Exercise registration with these cases in a scratch environment:
| Value | Expected |
|---|---|
alex_7 |
Accepted |
abc |
Rejected: too short |
abcdefghijklmnopqrstu |
Rejected: too long |
alex-smith |
Rejected: hyphen |
alex smith |
Rejected: space |
álvaro |
Rejected: outside the ASCII set |
| Missing username | Rejected: required trait |
Also test settings updates and login, not just initial registration. A schema describes allowed values; it does not automatically transform whitespace or choose an account-name normalization policy. Decide how capitalization should behave rather than relying on the regex to make that decision.
Treat schema changes as migrations
Changing the default schema does not rewrite every existing identity. Check which schema ID each identity uses, how existing values meet the new requirements and what happens when users edit settings. Roll out stricter validation with an explicit migration and recovery plan.
A regex also does not establish uniqueness or reserve names such as admin. Identifier handling and product-level naming policy need their own tests.
Ory documents identity schemas and schema customization. The passkeys dive explores a different authentication mechanism and its trust boundaries.