From 322b087b5bde029c5e17213cd022fc7d4c7885c2 Mon Sep 17 00:00:00 2001
From: Henning Perl <henning.perl@ory.sh>
Date: Mon, 13 Apr 2026 15:19:15 +0200
Subject: [PATCH 1/3] docs: document enum identity schema dropdowns

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: https://github.com/ory-corp/cloud/issues/10921

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../15_customize-identity-schema.mdx          | 41 +++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/kratos/manage-identities/15_customize-identity-schema.mdx b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
index c7764a9bb..8178a7544 100644
--- a/docs/kratos/manage-identities/15_customize-identity-schema.mdx
+++ b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
@@ -205,6 +205,47 @@ their GitHub handle, which is clear thanks to the field description defined in t
 </Tabs>
 ````
 
+## Restrict values with `enum`
+
+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.
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "traits": {
+      "type": "object",
+      "properties": {
+        "country": {
+          "type": "string",
+          "title": "Country",
+          "enum": ["US", "UK", "DE", "AT"]
+        }
+      },
+      "required": ["country"]
+    }
+  }
+}
+```
+
+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.
+
+:::note
+
+Only top-level string properties under `traits` are supported today. The
+rendered option value is used as both the submitted value and the visible
+label.
+
+:::
+
 ## Identity schema extensions
 
 Because the system doesn't know which fields have system-relevant meaning, you have to specify that in the schema. For example:

From 1ca0d57748b515be29283323f76435653f2fcbe7 Mon Sep 17 00:00:00 2001
From: Henning Perl <henning.perl@ory.sh>
Date: Tue, 14 Apr 2026 14:42:23 +0200
Subject: [PATCH 2/3] Apply suggestions from code review

Co-authored-by: Vincent <vinckr@posteo.net>
---
 .../kratos/manage-identities/15_customize-identity-schema.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/kratos/manage-identities/15_customize-identity-schema.mdx b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
index 8178a7544..010881394 100644
--- a/docs/kratos/manage-identities/15_customize-identity-schema.mdx
+++ b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
@@ -232,7 +232,7 @@ only accepts values from the list at registration, settings, and admin updates.
 }
 ```
 
-Kratos surfaces the allowed values on the UI node by attaching an `options`
+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
@@ -240,7 +240,7 @@ backward compatible with older custom UIs.
 
 :::note
 
-Only top-level string properties under `traits` are supported today. The
+Only top-level string properties under `traits` are supported. The
 rendered option value is used as both the submitted value and the visible
 label.
 

From 804a515774ae1fad25e7b3704a3e940370577fbb Mon Sep 17 00:00:00 2001
From: Henning Perl <henning.perl@ory.sh>
Date: Tue, 14 Apr 2026 14:44:06 +0200
Subject: [PATCH 3/3] chore: format

---
 .../15_customize-identity-schema.mdx          | 20 ++++++++-----------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/docs/kratos/manage-identities/15_customize-identity-schema.mdx b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
index 010881394..bcddea3d7 100644
--- a/docs/kratos/manage-identities/15_customize-identity-schema.mdx
+++ b/docs/kratos/manage-identities/15_customize-identity-schema.mdx
@@ -207,10 +207,9 @@ their GitHub handle, which is clear thanks to the field description defined in t
 
 ## Restrict values with `enum`
 
-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.
+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.
 
 ```json
 {
@@ -232,17 +231,14 @@ only accepts values from the list at registration, settings, and admin updates.
 }
 ```
 
-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 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.
 
 :::note
 
-Only top-level string properties under `traits` are supported. The
-rendered option value is used as both the submitted value and the visible
-label.
+Only top-level string properties under `traits` are supported. The rendered option value is used as both the submitted value and
+the visible label.
 
 :::