docs: document enum identity schema dropdowns by hperl · Pull Request #2508 · ory/docs

hperl · 2026-04-13T13:27:22Z

Summary

Describe the new behavior where declaring a string enum on an identity schema trait renders the field as a native <select> in the Ory Account Experience.
Document the options array attached to InputAttributes on the UI node so teams running a custom UI know how to render the dropdown.

Related: https://github.com/ory-corp/cloud/issues/10921

Test plan

Preview the "Customize identity schemas" page and verify the new "Restrict values with enum" section renders correctly and sits in the right place in the outline.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added guide on using enum constraints to restrict identity schema string property values
- Shows runtime behavior: enum-backed fields render as dropdowns in registration, settings, and admin flows
- Documents that allowed values are exposed to UIs via input attributes for building selects
- Notes fallback to plain-text input for UIs that ignore provided options
- Clarifies limitation to top-level string traits and that option value doubles as label

Describe the new behavior where `enum` on a string trait renders as a native `<select>` in the Account Experience and attaches an `options` array to the UI node for custom UIs. Related: ory-corp/cloud#10921 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vinckr

needs format :)

otherwise just a few small changes

vinckr · 2026-04-13T14:38:33Z

+Use the JSON Schema `enum` keyword to restrict a trait to a fixed set of
+allowed values. When you declare an `enum` on a string property, the Ory
+Account Experience renders the field as a dropdown (a native `<select>`) and
+only accepts values from the list at registration, settings, and admin updates.


do you mean if going through Registration or Settings self-service flows or the update identity admin API it will only accept values from the list?

Co-authored-by: Vincent <vinckr@posteo.net>

coderabbitai · 2026-04-14T12:42:46Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 913918f4-9c1b-459f-9c1c-abcfd2ef8355

📥 Commits

Reviewing files that changed from the base of the PR and between 1ca0d57 and 804a515.

📒 Files selected for processing (1)

docs/kratos/manage-identities/15_customize-identity-schema.mdx

✅ Files skipped from review due to trivial changes (1)

docs/kratos/manage-identities/15_customize-identity-schema.mdx

📝 Walkthrough

Walkthrough

Added a documentation section showing how to apply JSON Schema enum to top-level string traits properties in identity schemas, with examples and notes on runtime behavior and how Kratos exposes allowed values to UIs via attributes.options.

Changes

Cohort / File(s)	Summary
Documentation - Identity Schema Customization `docs/kratos/manage-identities/15_customize-identity-schema.mdx`	Added "Restrict values with enum" section: explains using `enum` on string `traits` (example: `traits.country`), marks property as required, documents runtime UI behavior (Ory Account Experience renders a `<select>`; Kratos exposes allowed values in `attributes.options`), and notes support is limited to top-level string `traits` with option values used as both value and label.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 I nibble on choices, neat and round,
Enums line up, no free-text found,
A dropdown hop, tidy and bright,
Traits now pick from a list just right,
Huzzah—my schema's snug tonight! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description includes a clear summary and references a related issue, but lacks completion of the required checklist items and does not follow the full template structure.	Complete the PR description checklist by checking appropriate boxes and confirm compliance with contributing guidelines and security policy.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting how enum declarations in identity schemas produce dropdown fields.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/enum-identity-schema-dropdowns

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

This PR updates the Kratos “Customize identity schemas” documentation to explain how string enum traits are rendered as dropdowns in the Ory Account Experience, and how custom UIs can consume the resulting UI node metadata.

Changes:

Added a new “Restrict values with enum” section explaining dropdown rendering for string enums.
Documented that Kratos exposes allowed enum values via an options array on input attributes for UI nodes.
Added a note clarifying current support limitations (top-level string traits) and label/value behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-14T12:45:54Z

+Ory Kratos surfaces the allowed values on the UI node by attaching an `options` array to the input attributes. Custom UIs that
+already know how to render a UI node can read `attributes.options` and display a `<select>`; UIs that do not look at `options`
+fall back to a plain text input, so the change is backward compatible with older custom UIs.


The text references attributes.options, but it’s not fully clear what object attributes belongs to. Consider explicitly using the full path (for example, UI node → node.attributes.options) and briefly stating what each option entry contains, so custom UI implementers can locate and render the dropdown data reliably.

Suggested change

Ory Kratos surfaces the allowed values on the UI node by attaching an `options` array to the input attributes. Custom UIs that

already know how to render a UI node can read `attributes.options` and display a `<select>`; UIs that do not look at `options`

fall back to a plain text input, so the change is backward compatible with older custom UIs.

Ory Kratos surfaces the allowed values on the UI node by attaching an `options` array to the input's attributes object

(`node.attributes.options`). Each entry in `node.attributes.options` represents one dropdown choice and contains the option

value and label used to render the native `<select>`. Custom UIs that already know how to render a UI node can read

`node.attributes.options` and display a `<select>`; UIs that do not look at `options` fall back to a plain text input, so the

change is backward compatible with older custom UIs.

Copilot · 2026-04-14T12:45:55Z

+
+Use the JSON Schema `enum` keyword to restrict a trait to a fixed set of allowed values. When you declare an `enum` on a string
+property, the Ory Account Experience renders the field as a dropdown (a native `<select>`) and only accepts values from the list
+at registration, settings, and admin updates.


“admin updates” is ambiguous in this context (Kratos typically refers to “Admin API” / “admin endpoints” rather than a generic “admin updates”). Consider rephrasing to explicitly name the surface (e.g., “via the Admin API”) so readers know where enum validation applies.

Suggested change

at registration, settings, and admin updates.

at registration, in settings, and via the Admin API.

hperl requested review from aeneasr, unatasha8 and vinckr as code owners April 13, 2026 13:27

github-actions bot added the Needs Triage label Apr 13, 2026

ory-bot assigned hperl Apr 13, 2026

vercel bot deployed to Preview April 13, 2026 13:32 View deployment

vinckr reviewed Apr 13, 2026

View reviewed changes

vinckr added the upstream Issue is caused by an upstream dependency. label Apr 13, 2026

github-actions bot removed the Needs Triage label Apr 14, 2026

Apply suggestions from code review

1ca0d57

Co-authored-by: Vincent <vinckr@posteo.net>

Copilot AI review requested due to automatic review settings April 14, 2026 12:42

Copilot started reviewing on behalf of hperl April 14, 2026 12:42 View session

chore: format

804a515

Copilot AI reviewed Apr 14, 2026

View reviewed changes

vercel bot deployed to Preview April 14, 2026 12:48 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document enum identity schema dropdowns#2508

docs: document enum identity schema dropdowns#2508
hperl wants to merge 3 commits intomasterfrom
docs/enum-identity-schema-dropdowns

hperl commented Apr 13, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vinckr left a comment

Uh oh!

Uh oh!

vinckr Apr 13, 2026

Uh oh!

hperl Apr 14, 2026

Uh oh!

Uh oh!

coderabbitai bot commented Apr 14, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Copilot AI Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	at registration, settings, and admin updates.
	at registration, in settings, and via the Admin API.

Conversation

hperl commented Apr 13, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

vinckr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vinckr Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

hperl Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hperl commented Apr 13, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Apr 14, 2026 •

edited

Loading