feat: add docs for new identity schema editor (#1739)

* feat: add docs for new identity schema editor

* chore: cr

* chore: format

docs/identities/model/manage-identity-schema.mdx

@@ -1,27 +1,53 @@
 ---
 id: manage-identity-schema
-title: Create, update, and manage identity schemas
+title: Manage identity schemas
 ---
 
+```mdx-code-block
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+```
+
 This document explains how to create, update, and manage identity schemas in Ory Network.
 
-## Create identity schemas
+## Use an existing preset
 
-Follow these steps to create a custom identity schema in Ory Network:
+Ory Network provides four basic preset schemas that are ready to use out of the box. If you are just getting started with Ory
+Network, use one of the presets to make your life easier.
 
-````mdx-code-block
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
+1. Go to [**Identities > Identity Schema**](https://console.ory.sh/projects/current/identity-schema) in the Ory Console.
+2. From the **Active schema** drop down, select the schema you want to use.
+3. Click the **Change active schema** button to apply the schema to your project.
+
+![Active schema dropdown](./_assets/activate-preset-schema.png)
+
+:::caution
+
+Be aware that changing the active schema will affect all new identities created in the project. Existing identities might not be
+able to sign in, for example if you change from an email based schema, to a username based schema.
+
+:::
+
+## Create custom schema
+
+If the presets do not fit your needs, you can create a custom schema. Follow these steps to create a custom schema:
 
 <Tabs>
 <TabItem value="console" label="Ory Console" default>
 
-1. Sign in to Ory Console and select [**Identity Schema**](https://console.ory.sh/projects/current/identity-schema).
-2. Using the dropdown menu, select one of the preset schemas or the empty template as the starting point for your custom schema.
-3. Check the **Customize Identity Schema** box to enable editing of the schema.
-4. Adjust the schema to your needs. Add, remove, or adjust traits.
-5. Define the name of the custom schema in the **Identity Model Schema** text box.
-6. Click the **Update** button to save.
+1. Go to [**Identities > Identity Schema**](https://console.ory.sh/projects/current/identity-schema) in the Ory Console.
+2. From the **Select template** drop down, select the schema you want to use as a template.
+3. Click the **Duplicate to make changes** button.
+4. Give your schema a name.
+5. Customize the schema to your needs. Read more about the
+   [customization options](/kratos/manage-identities/15_customize-identity-schema.mdx).
+6. Click the **Save** button to save.
+7. Confirm the changes by clicking the **Confirm** button in the confirmation dialog.
+
+![Create a new schema](./_assets/custom-schema-editor.png)
+
+To make this schema the active schema for your project, select the newly created schema from the **Active schema** dropdown and
+click the **Change active schema** button.
 
 </TabItem>
 <TabItem value="cli" label="Ory CLI">
@@ -38,20 +64,12 @@ ory patch identity-config {your-project-id} \
 
 </TabItem>
 </Tabs>
-````
 
 ## Update identity schemas
 
-To update an identity schema, you must create a new revision of that schema. You can't update existing identity schemas by editing
-them.
-
-For example, to update an identity schema named "Customer Type 1", follow these steps:
-
-1. Sign in to Ory Console and select [**Identity Schema**](https://console.ory.sh/projects/current/identity-schema).
-1. Using the dropdown menu, select the "Customer Type 1" schema.
-1. Check the **Customize Identity Schema** box to enable editing and make the necessary changes.
-1. Enter a new name in the **Identity Model Schema** text box, for example, "Customer Type 2".
-1. Click the **Update** button to save.
+Identity schemas are immutable to prevent inconsistencies in the data. This means, that you cannot update an existing schema.
+However, you can use the existing schema as a template to create a new schema. Simply follow the steps in
+[Creating custom schemas](#creating-custom-schemas) and select the current schema as a template.
 
 It's recommended to manage identity schemas in version control. Learn more about
 [managing Ory Network configuration in git](http://ory.sh/docs/guides/gitops).

docs/kratos/manage-identities/05_identity-schema.mdx

@@ -7,9 +7,9 @@ sidebar_label: Identity schema
 # Identity schema
 
 The identity schema implements the [JSON Schema Standard](https://json-schema.org) and allows you to adjust Ory specifically to
-your requirements. Identity schema specifies the types of data the system can store for users, such as their names, email
-addresses, phone numbers, and 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.
+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:
 
@@ -73,7 +73,7 @@ With this preset, every identity has a single trait - the `username`. The `usern
 
 ### Example with name and newsletter opt-in
 
-This preset has an email field, a first name, last name, and a "newsletter" checkbox.
+This preset has an `email` field, a `first name`, `last name`, and a `newsletter` checkbox.
 
 ```json5
 // Identity example

docs/kratos/manage-identities/10_managing-users-identities-metadata.mdx

@@ -11,17 +11,18 @@ Identities have traits and metadata:
 - **Traits** are the attributes of an identity, that can be updated by the identity owner, for example the username or email
   address.
 - **Metadata** are the attributes defined by the system admin that can't be updated or modified by the identity owner. The only
-  way to update the metadata is to use the `/admin/identities` APIs. These fields can be used to store, for example, the user's
-  roles, subscription status, etc.
+  way to update the metadata is through the `/admin/identities` APIs. These fields can be used to store additional information,
+  such as the original sign up date if the identity was created through a migration. Other use cases include, but are not limited
+  to,
 
 ## Metadata
 
 There are two types of identity metadata:
 
-- **Public:** Attributes which can only be modified using the `/admin/identities` APIs. They are visible to the user when calling
-  `toSession()` or `/sessions/whoami`.
-- **Admin:** Attributes which can only be modified and read using the `/admin/identities` APIs. They are never directly exposed to
-  the identity/user.
+- **Public:** Attributes that can only be modified using the `/admin/identities` APIs. They are visible to anyone having access to
+  the user's sessions, for example by calling `toSession()` or `/sessions/whoami`. This allows you to access the metadata in the
+  frontend without calling the admin APIs.
+- **Admin:** Attributes that can only be modified and read using the `/admin/identities` APIs.
 
 :::note