From fdc012ac01e35343dbc4abb7bffd696c23eaa133 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 13 Feb 2025 17:54:21 +0000
Subject: [PATCH 01/81] Describe MSC4133 profile endpoint changes

---
 data/api/client-server/profile.yaml | 294 +++++++++++++++-------------
 1 file changed, 156 insertions(+), 138 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 6e588ae3..70966b07 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -16,48 +16,85 @@ info:
   title: Matrix Client-Server Profile API
   version: 1.0.0
 paths:
-  "/profile/{userId}/displayname":
+  "/profile/{userId}/{key_name}":
     put:
-      summary: Set the user's display name.
+      summary: Set the user's profile field.
       description: |-
-        This API sets the given user's display name. You must have permission to
-        set this user's display name, e.g. you need to have their `access_token`.
-      operationId: setDisplayName
+        This API sets or updates a specified profile field in a user's profile. You must have the
+        appropriate permissions (i.e. an access token) to modify the profile field. Note that setting
+        a `null` value SHOULD NOT delete the field.
+      operationId: setProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to set.
+          description: The user whose profile field to set.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: key_name
+          description: The profile field key name to set.
+          required: true
+          example: "displayname"
+          schema:
+            oneOf:
+              - type: string
+                enum: ["displayname", "avatar_url"]
+              - type: string
+                description: Must follow the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
+        description: The new profile field value. The JSON object must contain the "key_name" specified in the URL.
+        required: true
         content:
           application/json:
             schema:
               type: object
-              example: {
-                "displayname": "Alice Margatroid"
-              }
-              properties:
-                displayname:
-                  type: string
-                  description: The new display name for this user.
-        description: The new display name information.
-        required: true
+              additionalProperties:
+                type: string
+              example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
-          description: The display name was set.
+          description: The profile field was set.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object # empty JSON object
               examples:
                 response:
                   value: {}
+        "400":
+          description: >
+            The request is malformed, missing a required parameter, or the profile data exceeds allowed limits.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_request:
+                  value:
+                    {
+                      "errcode": "M_BAD_JSON",
+                      "error": "Malformed JSON payload.",
+                    }
+        "403":
+          description: >
+            The server is unwilling to perform the operation—either due to insufficient permissions
+            or because profile modifications are disabled.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -67,98 +104,126 @@ paths:
       tags:
         - User data
     get:
-      summary: Get the user's display name.
+      summary: Get the user's profile field.
       description: |-
-        Get the user's display name. This API may be used to fetch the user's
-        own displayname or to query the name of other users; either locally or
-        on remote homeservers.
-      operationId: getDisplayName
+        Get the value of a user's profile field. This API can retrieve the profile fields of the user
+        or other users, either locally or on remote homeservers. It supports both standard fields
+        (e.g. "displayname" and "avatar_url") and custom keys.
+      operationId: getProfileField
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to get.
+          description: The user whose profile field to get.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: key_name
+          description: The profile field key name to retrieve (e.g. "displayname", "avatar_url", or custom).
+          required: true
+          example: "displayname"
+          schema:
+            oneOf:
+              - type: string
+                enum: ["displayname", "avatar_url"]
+              - type: string
+                description: Must follow the
+                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       responses:
         "200":
-          description: The display name for this user.
+          description: The profile field value was retrieved.
           content:
             application/json:
               schema:
                 type: object
-                properties:
-                  displayname:
-                    type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
+                additionalProperties:
+                  type: string
               examples:
                 response:
-                  value: {
-                    "displayname": "Alice Margatroid"
-                  }
+                  value: { "displayname": "Alice" }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has a display name.
+          description:
+            The server is unwilling to disclose whether the user exists and/or
+            has the specified profile field.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no display name for this user or this user does not exist.
+          description: There is no profile field with this key for this user, or the user does not exist.
       tags:
         - User data
-  "/profile/{userId}/avatar_url":
-    put:
-      summary: Set the user's avatar URL.
-      description: |-
-        This API sets the given user's avatar URL. You must have permission to
-        set this user's avatar URL, e.g. you need to have their `access_token`.
-      operationId: setAvatarUrl
+    delete:
+      summary: Delete a profile field.
+      description: Delete the specified profile field from a user's profile.
+      operationId: deleteProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose avatar URL to set.
+          description: The user whose profile field to delete.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example: {
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
-              }
-              properties:
-                avatar_url:
-                  type: string
-                  format: uri
-                  description: The new avatar URL for this user.
-        description: The new avatar information.
-        required: true
+        - in: path
+          name: key_name
+          description: The profile field key name to delete.
+          required: true
+          example: "displayname"
+          schema:
+            oneOf:
+              - type: string
+                enum: ["displayname", "avatar_url"]
+              - type: string
+                description: Must follow the
+                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       responses:
         "200":
-          description: The avatar URL was set.
+          description: The profile field was deleted.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object
               examples:
                 response:
                   value: {}
+        "400":
+          description: >
+            The request is malformed or specifies an invalid key.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_request:
+                  value:
+                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
+        "403":
+          description: >
+            The user is not authorised to delete this profile field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -167,63 +232,12 @@ paths:
                 $ref: definitions/errors/rate_limited.yaml
       tags:
         - User data
-    get:
-      summary: Get the user's avatar URL.
-      description: |-
-        Get the user's avatar URL. This API may be used to fetch the user's
-        own avatar URL or to query the URL of other users; either locally or
-        on remote homeservers.
-      operationId: getAvatarUrl
-      parameters:
-        - in: path
-          name: userId
-          description: The user whose avatar URL to get.
-          required: true
-          example: "@alice:example.com"
-          schema:
-            type: string
-      responses:
-        "200":
-          description: The avatar URL for this user.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  avatar_url:
-                    type: string
-                    format: uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
-              examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-                  }
-        "403":
-          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has an avatar URL.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
-        "404":
-          description: There is no avatar URL for this user or this user does not exist.
-      tags:
-        - User data
   "/profile/{userId}":
     get:
       summary: Get this user's profile information.
       description: |-
-        Get the combined profile information for this user. This API may be used
-        to fetch the user's own profile information or other users; either
-        locally or on remote homeservers.
+        Retrieve the combined profile information for a user. In addition to the standard fields,
+        this API may include extended custom profile fields as defined in MSC4133.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -241,23 +255,27 @@ paths:
               schema:
                 type: object
                 properties:
-                  avatar_url:
+                  "avatar_url":
                     type: string
                     format: uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
-                  displayname:
+                    description: The user's avatar URL if set.
+                  "displayname":
                     type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
-              examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                    "displayname": "Alice Margatroid"
-                  }
+                    description: The user's display name if set.
+                additionalProperties:
+                  type: string
+                examples:
+                  response:
+                    value:
+                      {
+                        "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                        "displayname": "Alice Margatroid",
+                        "m.example_field": "custom_value",
+                      }
         "403":
           x-addedInMatrixVersion: "1.2"
-          description: The server is unwilling to disclose whether the user exists and/or
+          description:
+            The server is unwilling to disclose whether the user exists and/or
             has profile information.
           content:
             application/json:
@@ -265,12 +283,14 @@ paths:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no profile information for this user or this user does not
+          description:
+            There is no profile information for this user or this user does not
             exist.
           content:
             application/json:
@@ -278,10 +298,8 @@ paths:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Profile not found"
-                  }
+                  value:
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
       tags:
         - User data
 servers:

From 1fc01189f311015aad6958bac834ae48428af2ea Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 09:59:22 +0000
Subject: [PATCH 02/81] 2071 change log

---
 changelogs/client_server/newsfragments/2071.clarification | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelogs/client_server/newsfragments/2071.clarification

diff --git a/changelogs/client_server/newsfragments/2071.clarification b/changelogs/client_server/newsfragments/2071.clarification
new file mode 100644
index 00000000..3097a512
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2071.clarification
@@ -0,0 +1 @@
+Clarification: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys (e.g. "displayname" and "avatar_url") are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

From b2e122f3080bf5711106423d43cc988b896d08cf Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 10:12:29 +0000
Subject: [PATCH 03/81] Update changelog from `clarification` to `feature`

---
 changelogs/client_server/newsfragments/2071.clarification | 1 -
 changelogs/client_server/newsfragments/2071.feature       | 1 +
 2 files changed, 1 insertion(+), 1 deletion(-)
 delete mode 100644 changelogs/client_server/newsfragments/2071.clarification
 create mode 100644 changelogs/client_server/newsfragments/2071.feature

diff --git a/changelogs/client_server/newsfragments/2071.clarification b/changelogs/client_server/newsfragments/2071.clarification
deleted file mode 100644
index 3097a512..00000000
--- a/changelogs/client_server/newsfragments/2071.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarification: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys (e.g. "displayname" and "avatar_url") are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
new file mode 100644
index 00000000..85fe9db4
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -0,0 +1 @@
+Feature: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys (e.g. "displayname" and "avatar_url") are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

From 59d2c62d2d39c8596af538ed2829bd45c47517d0 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 10:40:09 +0000
Subject: [PATCH 04/81] Link to MSC4133 in endpoint descriptions

---
 data/api/client-server/profile.yaml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 70966b07..5900cf1b 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -22,7 +22,8 @@ paths:
       description: |-
         This API sets or updates a specified profile field in a user's profile. You must have the
         appropriate permissions (i.e. an access token) to modify the profile field. Note that setting
-        a `null` value SHOULD NOT delete the field.
+        a `null` value SHOULD NOT delete the field. For more details, see
+        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -108,7 +109,8 @@ paths:
       description: |-
         Get the value of a user's profile field. This API can retrieve the profile fields of the user
         or other users, either locally or on remote homeservers. It supports both standard fields
-        (e.g. "displayname" and "avatar_url") and custom keys.
+        (e.g. "displayname" and "avatar_url") and custom keys. For more details, see
+        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: getProfileField
       parameters:
         - in: path
@@ -164,7 +166,9 @@ paths:
         - User data
     delete:
       summary: Delete a profile field.
-      description: Delete the specified profile field from a user's profile.
+      description: |-
+        Delete the specified profile field from a user's profile. For more details, see
+        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: deleteProfileField
       security:
         - accessTokenQuery: []
@@ -237,7 +241,8 @@ paths:
       summary: Get this user's profile information.
       description: |-
         Retrieve the combined profile information for a user. In addition to the standard fields,
-        this API may include extended custom profile fields as defined in MSC4133.
+        this API may include extended custom profile fields as defined in
+        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: getUserProfile
       parameters:
         - in: path

From ee9b5ddcca0264866e6179c1d761c1a518098b52 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:02:11 +0000
Subject: [PATCH 05/81] Correct types and errors

---
 data/api/client-server/profile.yaml | 75 ++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 23 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 5900cf1b..4a2fdbbe 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -48,14 +48,24 @@ paths:
               - type: string
                 description: Must follow the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
-        description: The new profile field value. The JSON object must contain the "key_name" specified in the URL.
+        description: >
+          The new profile field value. The JSON object must contain the "key_name" specified in the URL.
+          For custom keys, the value may be any valid JSON type. However, if the key is "displayname"
+          or "avatar_url", the value MUST be a string as per the stabilised spec requirements.
         required: true
         content:
           application/json:
             schema:
               type: object
+              properties:
+                displayname:
+                  type: string
+                  description: "Spec-conformant displayname value; must be a string."
+                avatar_url:
+                  type: string
+                  description: "Spec-conformant avatar URL value; must be a string."
               additionalProperties:
-                type: string
+                description: "Any additional profile field value; may be any valid JSON type."
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -69,18 +79,25 @@ paths:
                   value: {}
         "400":
           description: >
-            The request is malformed, missing a required parameter, or the profile data exceeds allowed limits.
+            The request is malformed, missing a required parameter, contains invalid JSON (for the value),
+            or specifies an invalid key, or the profile data exceeds allowed limits.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
-                bad_request:
+                bad_json:
                   value:
                     {
                       "errcode": "M_BAD_JSON",
                       "error": "Malformed JSON payload.",
                     }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
         "403":
           description: >
             The server is unwilling to perform the operation—either due to insufficient permissions
@@ -108,8 +125,7 @@ paths:
       summary: Get the user's profile field.
       description: |-
         Get the value of a user's profile field. This API can retrieve the profile fields of the user
-        or other users, either locally or on remote homeservers. It supports both standard fields
-        (e.g. "displayname" and "avatar_url") and custom keys. For more details, see
+        or other users, either locally or on remote homeservers. For more details, see
         [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: getProfileField
       parameters:
@@ -122,7 +138,7 @@ paths:
             type: string
         - in: path
           name: key_name
-          description: The profile field key name to retrieve (e.g. "displayname", "avatar_url", or custom).
+          description: The profile field key name to retrieve.
           required: true
           example: "displayname"
           schema:
@@ -139,8 +155,15 @@ paths:
             application/json:
               schema:
                 type: object
+                properties:
+                  displayname:
+                    type: string
+                    description: "Spec-conformant displayname value; must be a string."
+                  avatar_url:
+                    type: string
+                    description: "Spec-conformant avatar URL value; must be a string."
                 additionalProperties:
-                  type: string
+                  description: "Any additional profile field value; may be any valid JSON type."
               examples:
                 response:
                   value: { "displayname": "Alice" }
@@ -205,15 +228,21 @@ paths:
                   value: {}
         "400":
           description: >
-            The request is malformed or specifies an invalid key.
+            The request is malformed, contains invalid JSON, or specifies an invalid key.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
-                bad_request:
+                bad_json:
                   value:
                     { "errcode": "M_BAD_JSON", "error": "Malformed request." }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
         "403":
           description: >
             The user is not authorised to delete this profile field.
@@ -260,23 +289,23 @@ paths:
               schema:
                 type: object
                 properties:
-                  "avatar_url":
+                  avatar_url:
                     type: string
                     format: uri
-                    description: The user's avatar URL if set.
-                  "displayname":
+                    description: "Spec-conformant avatar URL value; must be a string."
+                  displayname:
                     type: string
-                    description: The user's display name if set.
+                    description: "Spec-conformant displayname value; must be a string."
                 additionalProperties:
-                  type: string
-                examples:
-                  response:
-                    value:
-                      {
-                        "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                        "displayname": "Alice Margatroid",
-                        "m.example_field": "custom_value",
-                      }
+                  description: "Any additional profile field value; may be any valid JSON type."
+              examples:
+                response:
+                  value:
+                    {
+                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                      "displayname": "Alice Margatroid",
+                      "m.example_field": "custom_value",
+                    }
         "403":
           x-addedInMatrixVersion: "1.2"
           description:

From 8e9874ad223d6b0b31e5ff59f097ac209592ac7a Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:15:00 +0000
Subject: [PATCH 06/81] Simplify change log

---
 changelogs/client_server/newsfragments/2071.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
index 85fe9db4..61ea25b3 100644
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -1 +1 @@
-Feature: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys (e.g. "displayname" and "avatar_url") are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
+Feature: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

From 41c64c877b2f188a889fab0f382143c65a05b8d3 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:16:40 +0000
Subject: [PATCH 07/81] Linkify MSC4133 in change log

---
 changelogs/client_server/newsfragments/2071.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
index 61ea25b3..00695c46 100644
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -1 +1 @@
-Feature: Update profile endpoints to become generic to support MSC4133 extended fields. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
+Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

From 82adcec4913e33bbc694f82a9322ea09945756f1 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:21:45 +0000
Subject: [PATCH 08/81] Clarify `avatar_url` should be MXC

---
 data/api/client-server/profile.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 4a2fdbbe..5fcb840f 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -63,7 +63,7 @@ paths:
                   description: "Spec-conformant displayname value; must be a string."
                 avatar_url:
                   type: string
-                  description: "Spec-conformant avatar URL value; must be a string."
+                  description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
               additionalProperties:
                 description: "Any additional profile field value; may be any valid JSON type."
               example: { "displayname": "Alice Wonderland" }
@@ -161,7 +161,7 @@ paths:
                     description: "Spec-conformant displayname value; must be a string."
                   avatar_url:
                     type: string
-                    description: "Spec-conformant avatar URL value; must be a string."
+                    description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
                 additionalProperties:
                   description: "Any additional profile field value; may be any valid JSON type."
               examples:
@@ -292,7 +292,7 @@ paths:
                   avatar_url:
                     type: string
                     format: uri
-                    description: "Spec-conformant avatar URL value; must be a string."
+                    description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
                   displayname:
                     type: string
                     description: "Spec-conformant displayname value; must be a string."

From 4f8999be0ae60d47c37063520c39cbb6aec7f3aa Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:32:39 +0000
Subject: [PATCH 09/81] Tweak wording on full profile `GET`

---
 data/api/client-server/profile.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 5fcb840f..846c14c6 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -269,8 +269,8 @@ paths:
     get:
       summary: Get this user's profile information.
       description: |-
-        Retrieve the combined profile information for a user. In addition to the standard fields,
-        this API may include extended custom profile fields as defined in
+        Retrieve the combined profile information for a user. In addition to the
+        stabilised fields, this API may include custom profile fields as defined in
         [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: getUserProfile
       parameters:

From 992cf9dc359142da9906e4c98509ae405c3707ce Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 11:53:19 +0000
Subject: [PATCH 10/81] Clarify `null` behaviour for `PUT` and `DELETE`

---
 data/api/client-server/profile.yaml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 846c14c6..e4525a17 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -21,9 +21,11 @@ paths:
       summary: Set the user's profile field.
       description: |-
         This API sets or updates a specified profile field in a user's profile. You must have the
-        appropriate permissions (i.e. an access token) to modify the profile field. Note that setting
-        a `null` value SHOULD NOT delete the field. For more details, see
-        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
+        appropriate permissions (i.e. an access token) to modify the profile field.
+
+        **Note:** Setting a `null` value SHOULD NOT delete the field. However, servers MAY reject
+        requests to store `null` values if they do not allow keys to exist with a `null` value.
+        For more details, see [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -190,7 +192,10 @@ paths:
     delete:
       summary: Delete a profile field.
       description: |-
-        Delete the specified profile field from a user's profile. For more details, see
+        Delete the specified profile field from a user's profile.
+
+        **Note:** Setting a null value using the `PUT` endpoint retains the key with a null value.
+        Use this `DELETE` endpoint to fully remove the key if required. For more details, see
         [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
       operationId: deleteProfileField
       security:

From 3311b084bf60e9704e14afe6af402a92aeb76fdb Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:03:49 +0000
Subject: [PATCH 11/81] Alphabetise `avatar_url` and `displayname` and remove
 redundant descriptions on `displayname`

---
 data/api/client-server/profile.yaml | 25 +++++++++++--------------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index e4525a17..fdeaeadc 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -46,26 +46,25 @@ paths:
           schema:
             oneOf:
               - type: string
-                enum: ["displayname", "avatar_url"]
+                enum: ["avatar_url", "displayname"]
               - type: string
                 description: Must follow the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
         description: >
           The new profile field value. The JSON object must contain the "key_name" specified in the URL.
           For custom keys, the value may be any valid JSON type. However, if the key is "displayname"
-          or "avatar_url", the value MUST be a string as per the stabilised spec requirements.
+          or "avatar_url", the value MUST be a string.
         required: true
         content:
           application/json:
             schema:
               type: object
               properties:
-                displayname:
-                  type: string
-                  description: "Spec-conformant displayname value; must be a string."
                 avatar_url:
                   type: string
-                  description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
+                  description: "Avatar URL value (MXC URI format)."
+                displayname:
+                  type: string
               additionalProperties:
                 description: "Any additional profile field value; may be any valid JSON type."
               example: { "displayname": "Alice Wonderland" }
@@ -146,7 +145,7 @@ paths:
           schema:
             oneOf:
               - type: string
-                enum: ["displayname", "avatar_url"]
+                enum: ["avatar_url", "displayname"]
               - type: string
                 description: Must follow the
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
@@ -158,12 +157,11 @@ paths:
               schema:
                 type: object
                 properties:
-                  displayname:
-                    type: string
-                    description: "Spec-conformant displayname value; must be a string."
                   avatar_url:
                     type: string
-                    description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
+                    description: "Avatar URL value (MXC URI format)."
+                  displayname:
+                    type: string
                 additionalProperties:
                   description: "Any additional profile field value; may be any valid JSON type."
               examples:
@@ -217,7 +215,7 @@ paths:
           schema:
             oneOf:
               - type: string
-                enum: ["displayname", "avatar_url"]
+                enum: ["avatar_url", "displayname"]
               - type: string
                 description: Must follow the
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
@@ -297,10 +295,9 @@ paths:
                   avatar_url:
                     type: string
                     format: uri
-                    description: "Spec-conformant avatar URL value (MXC URI format); must be a string."
+                    description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
-                    description: "Spec-conformant displayname value; must be a string."
                 additionalProperties:
                   description: "Any additional profile field value; may be any valid JSON type."
               examples:

From f3c269d95107d5e70c676274a766cf3b420098b3 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:20:25 +0000
Subject: [PATCH 12/81] Added capability

---
 .../client_server/newsfragments/2071.feature  |  2 +-
 data/api/client-server/capabilities.yaml      | 29 +++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
index 00695c46..25c338f2 100644
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -1 +1 @@
-Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
+Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Extended profile fields are now supported via the new `m.profile_fields` capability. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 523c6091..c2853586 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -86,6 +86,10 @@ paths:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
+                      m.profile_fields:
+                        $ref: "#/components/schemas/profileFieldsCapability"
+                        description: Capability to indicate if the user can set or modify extended profile fields.
+                          If absent, clients SHOULD assume extended profiles are supported in the correct spec version.
               examples:
                 response:
                   value: {
@@ -144,3 +148,28 @@ components:
           example: false
       required:
         - enabled
+    profileFieldsCapability:
+      type: object
+      title: ProfileFieldsCapability
+      properties:
+        enabled:
+          type: boolean
+          description: True if the user can set or modify any extended profile fields, false otherwise.
+          example: true
+        allowed:
+          type: array
+          description: List of allowed custom profile field keys. This takes precedence over disallowed if both are provided.
+          items:
+            type: string
+          example:
+            - "m.example_field"
+            - "org.example.job_title"
+        disallowed:
+          type: array
+          description: List of disallowed custom profile field keys. Ignored if allowed is provided.
+          items:
+            type: string
+          example:
+            - "org.example.secret_field"
+      required:
+        - enabled

From 93277930074b8758b38b2981dac3bcc8d8d69a64 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:39:19 +0000
Subject: [PATCH 13/81] Inline information from MSC4133, remove links

---
 data/api/client-server/profile.yaml | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index fdeaeadc..e210a145 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -23,9 +23,10 @@ paths:
         This API sets or updates a specified profile field in a user's profile. You must have the
         appropriate permissions (i.e. an access token) to modify the profile field.
 
-        **Note:** Setting a `null` value SHOULD NOT delete the field. However, servers MAY reject
-        requests to store `null` values if they do not allow keys to exist with a `null` value.
-        For more details, see [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
+        Setting a `null` value SHOULD NOT delete the field. Instead, it retains the key with a `null`
+        value, unless the server rejects the request due to lack of support for `null` values.
+        To fully remove a profile field, use the `DELETE` endpoint. Servers may impose an upper limit
+        on value length, and profile data is subject to a total size limit of 64 KiB.
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -48,7 +49,8 @@ paths:
               - type: string
                 enum: ["avatar_url", "displayname"]
               - type: string
-                description: Must follow the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+                description: Must follow the
+                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
         description: >
           The new profile field value. The JSON object must contain the "key_name" specified in the URL.
@@ -125,9 +127,8 @@ paths:
     get:
       summary: Get the user's profile field.
       description: |-
-        Get the value of a user's profile field. This API can retrieve the profile fields of the user
-        or other users, either locally or on remote homeservers. For more details, see
-        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
+        Get the value of a user's profile field. This API retrieves stabilised fields and custom
+        profile fields. Profile data is subject to a total size limit of 64 KiB.
       operationId: getProfileField
       parameters:
         - in: path
@@ -190,11 +191,8 @@ paths:
     delete:
       summary: Delete a profile field.
       description: |-
-        Delete the specified profile field from a user's profile.
-
-        **Note:** Setting a null value using the `PUT` endpoint retains the key with a null value.
-        Use this `DELETE` endpoint to fully remove the key if required. For more details, see
-        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
+        Delete the specified profile field from a user's profile. Note that setting a `null` value with the `PUT`
+        endpoint retains the key with a null value; use this `DELETE` endpoint to fully remove a profile field.
       operationId: deleteProfileField
       security:
         - accessTokenQuery: []
@@ -272,9 +270,9 @@ paths:
     get:
       summary: Get this user's profile information.
       description: |-
-        Retrieve the combined profile information for a user. In addition to the
-        stabilised fields, this API may include custom profile fields as defined in
-        [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).
+        Retrieve the global profile information for a user. In addition to stabilised fields such as
+        "avatar_url" and "displayname", this API may include custom profile fields.
+        The overall profile data is limited to a maximum of 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path

From 5d5b56114089ed44341c19dddd09f24f86230f98 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:47:14 +0000
Subject: [PATCH 14/81] Deprecate `m.set_displayname` and `m.set_avatar_url`
 capabilities

---
 data/api/client-server/capabilities.yaml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index c2853586..93e0cb90 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -73,11 +73,13 @@ paths:
                           - default
                           - available
                       m.set_displayname:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their display name.
+                        description: (Deprecated) Capability to indicate if the user can change their display name.
                       m.set_avatar_url:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their avatar.
+                        description: (Deprecated) Capability to indicate if the user can change their avatar.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations

From 76b48e25d004997b515f879bb9c971538a65821d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:56:16 +0000
Subject: [PATCH 15/81] Specify CNIG pattern for custom fields

---
 data/api/client-server/profile.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index e210a145..842d3484 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -49,6 +49,7 @@ paths:
               - type: string
                 enum: ["avatar_url", "displayname"]
               - type: string
+                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
                 description: Must follow the
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
@@ -148,6 +149,7 @@ paths:
               - type: string
                 enum: ["avatar_url", "displayname"]
               - type: string
+                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
                 description: Must follow the
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       responses:
@@ -215,6 +217,7 @@ paths:
               - type: string
                 enum: ["avatar_url", "displayname"]
               - type: string
+                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
                 description: Must follow the
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       responses:

From 79a1cded028c375047c1dc93b355c1e8ffc90874 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 12:57:51 +0000
Subject: [PATCH 16/81] Remove reference to spec version in `m.profile_field`
 capability

---
 data/api/client-server/capabilities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 93e0cb90..b340a517 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -91,7 +91,7 @@ paths:
                       m.profile_fields:
                         $ref: "#/components/schemas/profileFieldsCapability"
                         description: Capability to indicate if the user can set or modify extended profile fields.
-                          If absent, clients SHOULD assume extended profiles are supported in the correct spec version.
+                          If absent, clients should assume custom profile fields are supported.
               examples:
                 response:
                   value: {

From 17af55ddce5bf15215b34bce63fc4dda1c0d65ca Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 13:30:33 +0000
Subject: [PATCH 17/81] Fix broken link

---
 content/client-server-api/modules/guest_access.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index ada9e71e..7656beb3 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -63,7 +63,7 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
+* [PUT /profile/{userId}/{key_name}](#put_matrixclientv3profileuseridkeyname)
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

From 79af78022e8c078c76553b670c9c090c684dab2e Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 13:47:49 +0000
Subject: [PATCH 18/81] Camel case for endpoint variables

---
 data/api/client-server/profile.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 842d3484..583f6d19 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -16,7 +16,7 @@ info:
   title: Matrix Client-Server Profile API
   version: 1.0.0
 paths:
-  "/profile/{userId}/{key_name}":
+  "/profile/{userId}/{keyName}":
     put:
       summary: Set the user's profile field.
       description: |-
@@ -40,7 +40,7 @@ paths:
           schema:
             type: string
         - in: path
-          name: key_name
+          name: keyName
           description: The profile field key name to set.
           required: true
           example: "displayname"
@@ -54,7 +54,7 @@ paths:
                   [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
       requestBody:
         description: >
-          The new profile field value. The JSON object must contain the "key_name" specified in the URL.
+          The new profile field value. The JSON object must contain the `keyName` specified in the URL.
           For custom keys, the value may be any valid JSON type. However, if the key is "displayname"
           or "avatar_url", the value MUST be a string.
         required: true
@@ -140,7 +140,7 @@ paths:
           schema:
             type: string
         - in: path
-          name: key_name
+          name: keyName
           description: The profile field key name to retrieve.
           required: true
           example: "displayname"
@@ -208,7 +208,7 @@ paths:
           schema:
             type: string
         - in: path
-          name: key_name
+          name: keyName
           description: The profile field key name to delete.
           required: true
           example: "displayname"

From 1cc93ec951004e324b4717ffe3975736fa15dccf Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 14:53:29 +0000
Subject: [PATCH 19/81] Attempt to make descriptions look better in HTML
 rendered spec

---
 data/api/client-server/profile.yaml | 114 ++++++++++++----------------
 1 file changed, 47 insertions(+), 67 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 583f6d19..732ae34d 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -18,15 +18,14 @@ info:
 paths:
   "/profile/{userId}/{keyName}":
     put:
-      summary: Set the user's profile field.
+      summary: Set a profile field for a user.
       description: |-
-        This API sets or updates a specified profile field in a user's profile. You must have the
-        appropriate permissions (i.e. an access token) to modify the profile field.
+        Set or update a profile field for a user.
+        Must be authenticated with an access token authorised to make changes.
+        Servers may impose size limits on individual fields, and the total profile must be under 64 KiB.
 
-        Setting a `null` value SHOULD NOT delete the field. Instead, it retains the key with a `null`
-        value, unless the server rejects the request due to lack of support for `null` values.
-        To fully remove a profile field, use the `DELETE` endpoint. Servers may impose an upper limit
-        on value length, and profile data is subject to a total size limit of 64 KiB.
+        **Note**: Setting a field to `null` keeps the key but with a `null` value, which some servers may reject.
+        To remove a field completely, use the `DELETE` endpoint instead.
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -42,21 +41,18 @@ paths:
         - in: path
           name: keyName
           description: The profile field key name to set.
+            It must be either `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
-            oneOf:
-              - type: string
-                enum: ["avatar_url", "displayname"]
-              - type: string
-                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
-                description: Must follow the
-                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
-        description: >
-          The new profile field value. The JSON object must contain the `keyName` specified in the URL.
-          For custom keys, the value may be any valid JSON type. However, if the key is "displayname"
-          or "avatar_url", the value MUST be a string.
+        description:
+          A JSON object that must contain the `keyName` specified in the URL.
+          For custom keys, the value may be any valid JSON type,
+          but if the key is `avatar_url` or `displayname`, the value MUST be a string.
         required: true
         content:
           application/json:
@@ -65,11 +61,11 @@ paths:
               properties:
                 avatar_url:
                   type: string
-                  description: "Avatar URL value (MXC URI format)."
+                  description: Avatar URL value (MXC URI format).
                 displayname:
                   type: string
               additionalProperties:
-                description: "Any additional profile field value; may be any valid JSON type."
+                description: Any additional profile field value; may be any valid JSON type.
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -82,9 +78,8 @@ paths:
                 response:
                   value: {}
         "400":
-          description: >
-            The request is malformed, missing a required parameter, contains invalid JSON (for the value),
-            or specifies an invalid key, or the profile data exceeds allowed limits.
+          description: The request is malformed, contains invalid JSON,
+            missing a required parameter, specifies an invalid key, or exceeds allowed size limits.
           content:
             application/json:
               schema:
@@ -103,9 +98,8 @@ paths:
                       "error": "Invalid profile key.",
                     }
         "403":
-          description: >
-            The server is unwilling to perform the operation—either due to insufficient permissions
-            or because profile modifications are disabled.
+          description: The server is unwilling to perform the operation,
+            either due to insufficient permissions or because profile modifications are disabled.
           content:
             application/json:
               schema:
@@ -126,10 +120,9 @@ paths:
       tags:
         - User data
     get:
-      summary: Get the user's profile field.
+      summary: Get a profile field for a user.
       description: |-
-        Get the value of a user's profile field. This API retrieves stabilised fields and custom
-        profile fields. Profile data is subject to a total size limit of 64 KiB.
+        Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB.
       operationId: getProfileField
       parameters:
         - in: path
@@ -142,16 +135,13 @@ paths:
         - in: path
           name: keyName
           description: The profile field key name to retrieve.
+            It must be either `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
-            oneOf:
-              - type: string
-                enum: ["avatar_url", "displayname"]
-              - type: string
-                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
-                description: Must follow the
-                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
           description: The profile field value was retrieved.
@@ -162,19 +152,17 @@ paths:
                 properties:
                   avatar_url:
                     type: string
-                    description: "Avatar URL value (MXC URI format)."
+                    description: Avatar URL value (MXC URI format).
                   displayname:
                     type: string
                 additionalProperties:
-                  description: "Any additional profile field value; may be any valid JSON type."
+                  description: Any additional profile field value, of any valid JSON type.
               examples:
                 response:
                   value: { "displayname": "Alice" }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description:
-            The server is unwilling to disclose whether the user exists and/or
-            has the specified profile field.
+          description: The server is unwilling to disclose whether the user exists and/or has the specified profile field.
           content:
             application/json:
               schema:
@@ -191,10 +179,8 @@ paths:
       tags:
         - User data
     delete:
-      summary: Delete a profile field.
-      description: |-
-        Delete the specified profile field from a user's profile. Note that setting a `null` value with the `PUT`
-        endpoint retains the key with a null value; use this `DELETE` endpoint to fully remove a profile field.
+      summary: Remove a profile field from a user.
+      description: Remove a specific field from a user's profile.
       operationId: deleteProfileField
       security:
         - accessTokenQuery: []
@@ -210,16 +196,13 @@ paths:
         - in: path
           name: keyName
           description: The profile field key name to delete.
+            It must be either `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
-            oneOf:
-              - type: string
-                enum: ["avatar_url", "displayname"]
-              - type: string
-                pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
-                description: Must follow the
-                  [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
           description: The profile field was deleted.
@@ -231,8 +214,7 @@ paths:
                 response:
                   value: {}
         "400":
-          description: >
-            The request is malformed, contains invalid JSON, or specifies an invalid key.
+          description: The request is malformed, contains invalid JSON, or specifies an invalid key.
           content:
             application/json:
               schema:
@@ -248,8 +230,7 @@ paths:
                       "error": "Invalid profile key.",
                     }
         "403":
-          description: >
-            The user is not authorised to delete this profile field.
+          description: The user is not authorised to delete this profile field.
           content:
             application/json:
               schema:
@@ -271,11 +252,12 @@ paths:
         - User data
   "/profile/{userId}":
     get:
-      summary: Get this user's profile information.
+      summary: Get all profile information for a user.
       description: |-
-        Retrieve the global profile information for a user. In addition to stabilised fields such as
-        "avatar_url" and "displayname", this API may include custom profile fields.
-        The overall profile data is limited to a maximum of 64 KiB.
+        Get the complete profile for a user. The response includes `avatar_url` and `displayname`
+        (unless set to `null`) plus any custom profile fields.
+
+        **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -300,7 +282,9 @@ paths:
                   displayname:
                     type: string
                 additionalProperties:
-                  description: "Any additional profile field value; may be any valid JSON type."
+                  description:
+                    Any additional profile field value; may be any valid JSON type, with keys following the
+                    [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
               examples:
                 response:
                   value:
@@ -311,9 +295,7 @@ paths:
                     }
         "403":
           x-addedInMatrixVersion: "1.2"
-          description:
-            The server is unwilling to disclose whether the user exists and/or
-            has profile information.
+          description: The server is unwilling to disclose whether the user exists and/or has profile information.
           content:
             application/json:
               schema:
@@ -326,9 +308,7 @@ paths:
                       "error": "Profile lookup is disabled on this homeserver",
                     }
         "404":
-          description:
-            There is no profile information for this user or this user does not
-            exist.
+          description: There is no profile information for this user or this user does not exist.
           content:
             application/json:
               schema:

From 0b0942d1922459b96b93896db14a19b3f6e6c8cf Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 15:00:53 +0000
Subject: [PATCH 20/81] Clarify capability lists should support wildcards

---
 data/api/client-server/capabilities.yaml | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index b340a517..9e4810f1 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -154,13 +154,10 @@ components:
       type: object
       title: ProfileFieldsCapability
       properties:
-        enabled:
-          type: boolean
-          description: True if the user can set or modify any extended profile fields, false otherwise.
-          example: true
         allowed:
           type: array
-          description: List of allowed custom profile field keys. This takes precedence over disallowed if both are provided.
+          description: List of allowed custom profile field keys,
+            supporting `glob.*` wildcard format. Takes precedence over disallowed if both are provided.
           items:
             type: string
           example:
@@ -168,10 +165,15 @@ components:
             - "org.example.job_title"
         disallowed:
           type: array
-          description: List of disallowed custom profile field keys. Ignored if allowed is provided.
+          description: List of disallowed custom profile field keys,
+            supporting `glob.*` wildcard format. Ignored if allowed is provided.
           items:
             type: string
           example:
             - "org.example.secret_field"
+        enabled:
+          type: boolean
+          description: True if the user can set or modify any extended profile fields, false otherwise.
+          example: true
       required:
         - enabled

From 7a3b0c08045cb69d2d8e0831b138bc98dd9eced0 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 14 Feb 2025 15:03:17 +0000
Subject: [PATCH 21/81] Clarify in change log that `m.set_avatar_url` and
 `m.set_displayname` capabilities are now deprecated

---
 changelogs/client_server/newsfragments/2071.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
index 25c338f2..a083a3a6 100644
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -1 +1 @@
-Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Extended profile fields are now supported via the new `m.profile_fields` capability. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
+Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Extended profile fields are now supported via the new `m.profile_fields` capability, which deprecates the previous `m.set_avatar_url` and `m.set_displayname` capabilities. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

From 9859e20927e9519a9084729a21fcc23b0eb20aa2 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:31:27 +0000
Subject: [PATCH 22/81] Don't use reference for capability.

---
 data/api/client-server/capabilities.yaml | 52 +++++++++++-------------
 1 file changed, 24 insertions(+), 28 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 9e4810f1..a19bec1c 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -89,9 +89,32 @@ paths:
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
                       m.profile_fields:
-                        $ref: "#/components/schemas/profileFieldsCapability"
+                        type: object
+                        title: ProfileFieldsCapability
                         description: Capability to indicate if the user can set or modify extended profile fields.
                           If absent, clients should assume custom profile fields are supported.
+                        properties:
+                          allowed:
+                            type: array
+                            description: List of allowed custom profile field keys, supporting `glob.*` wildcard format. Takes precedence over disallowed if both are provided.
+                            items:
+                              type: string
+                            example:
+                              - "m.example_field"
+                              - "org.example/job_title"
+                          disallowed:
+                            type: array
+                            description: List of disallowed custom profile field keys, supporting `glob.*` wildcard format. Ignored if allowed is provided.
+                            items:
+                              type: string
+                            example:
+                              - "org.example.secret_field"
+                          enabled:
+                            type: boolean
+                            description: True if the user can set or modify any extended profile fields, false otherwise.
+                            example: true
+                        required:
+                          - enabled
               examples:
                 response:
                   value: {
@@ -150,30 +173,3 @@ components:
           example: false
       required:
         - enabled
-    profileFieldsCapability:
-      type: object
-      title: ProfileFieldsCapability
-      properties:
-        allowed:
-          type: array
-          description: List of allowed custom profile field keys,
-            supporting `glob.*` wildcard format. Takes precedence over disallowed if both are provided.
-          items:
-            type: string
-          example:
-            - "m.example_field"
-            - "org.example.job_title"
-        disallowed:
-          type: array
-          description: List of disallowed custom profile field keys,
-            supporting `glob.*` wildcard format. Ignored if allowed is provided.
-          items:
-            type: string
-          example:
-            - "org.example.secret_field"
-        enabled:
-          type: boolean
-          description: True if the user can set or modify any extended profile fields, false otherwise.
-          example: true
-      required:
-        - enabled

From 013502b0c0364456c940609294c86c4df961103e Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:35:26 +0000
Subject: [PATCH 23/81] Mention replacement for `m.set_displayname` and
 `m.set_avatar_url` capability deprecation

---
 data/api/client-server/capabilities.yaml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index a19bec1c..0dc983b8 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -75,11 +75,15 @@ paths:
                       m.set_displayname:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: (Deprecated) Capability to indicate if the user can change their display name.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their display name.
+                          Please refer to `m.profile_fields` for extended profile management.
                       m.set_avatar_url:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: (Deprecated) Capability to indicate if the user can change their avatar.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their avatar.
+                          Please refer to `m.profile_fields` for extended profile management.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations

From 9889fe3584aa0b13c980eaea58b474873645476d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:40:07 +0000
Subject: [PATCH 24/81] Use more accessible terminology than "glob"

---
 data/api/client-server/capabilities.yaml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 0dc983b8..aa69ef58 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -100,7 +100,9 @@ paths:
                         properties:
                           allowed:
                             type: array
-                            description: List of allowed custom profile field keys, supporting `glob.*` wildcard format. Takes precedence over disallowed if both are provided.
+                            description: List of allowed additional custom profile field keys. A `*` can be used as a
+                              wildcard to match any sequence of characters. This list takes precedence over the
+                              disallowed list if both are provided.
                             items:
                               type: string
                             example:
@@ -108,7 +110,8 @@ paths:
                               - "org.example/job_title"
                           disallowed:
                             type: array
-                            description: List of disallowed custom profile field keys, supporting `glob.*` wildcard format. Ignored if allowed is provided.
+                            description: List of disallowed additional custom profile field keys. A `*` can be used as
+                              a wildcard to match any sequence of characters. Ignored if an allowed list is provided.
                             items:
                               type: string
                             example:

From 3a5e5555fa325bc7e527da511ef3492259f343bf Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:48:20 +0000
Subject: [PATCH 25/81] Correct `PUT`/`GET` payload definitions

---
 data/api/client-server/profile.yaml | 19 +++++--------------
 1 file changed, 5 insertions(+), 14 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 732ae34d..438288c7 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -59,13 +59,8 @@ paths:
             schema:
               type: object
               properties:
-                avatar_url:
-                  type: string
-                  description: Avatar URL value (MXC URI format).
-                displayname:
-                  type: string
-              additionalProperties:
-                description: Any additional profile field value; may be any valid JSON type.
+                "<keyName>":
+                  description: The field value to set; may be any valid JSON type.
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -150,13 +145,9 @@ paths:
               schema:
                 type: object
                 properties:
-                  avatar_url:
-                    type: string
-                    description: Avatar URL value (MXC URI format).
-                  displayname:
-                    type: string
-                additionalProperties:
-                  description: Any additional profile field value, of any valid JSON type.
+                  "<keyName>":
+                    description: The field value to set; may be any valid JSON type.
+                additionalProperties: false
               examples:
                 response:
                   value: { "displayname": "Alice" }

From 7ef1d9d0ec15691772e7f29d658cf7c7a72ccf91 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:56:53 +0000
Subject: [PATCH 26/81] Add `x-changedInMatrixVersion`

---
 data/api/client-server/profile.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 438288c7..8b009a68 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -18,6 +18,8 @@ info:
 paths:
   "/profile/{userId}/{keyName}":
     put:
+      x-changedInMatrixVersion:
+        "1.14": Endpoint now accepts variable `keyName` parameter.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user.
@@ -115,6 +117,8 @@ paths:
       tags:
         - User data
     get:
+      x-changedInMatrixVersion:
+        "1.14": Endpoint now accepts variable `keyName` parameter.
       summary: Get a profile field for a user.
       description: |-
         Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB.

From b5e2edf2e573e5bd163550418be6bc90bb803fae Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 16:59:44 +0000
Subject: [PATCH 27/81] Add `x-addedInMatrixVersion`

---
 data/api/client-server/capabilities.yaml | 1 +
 data/api/client-server/profile.yaml      | 1 +
 2 files changed, 2 insertions(+)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index aa69ef58..4a0af7f4 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -93,6 +93,7 @@ paths:
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
                       m.profile_fields:
+                        x-addedInMatrixVersion: "1.14"
                         type: object
                         title: ProfileFieldsCapability
                         description: Capability to indicate if the user can set or modify extended profile fields.
diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 8b009a68..9792a402 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -174,6 +174,7 @@ paths:
       tags:
         - User data
     delete:
+      x-addedInMatrixVersion: "1.14"
       summary: Remove a profile field from a user.
       description: Remove a specific field from a user's profile.
       operationId: deleteProfileField

From d8cc250d208243d85e54485879bf0d42bc02e1c2 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 17:02:23 +0000
Subject: [PATCH 28/81] Tag `x-addedInMatrixVersion` on `additionalProperties`
 in entire profile `GET`

---
 data/api/client-server/profile.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 9792a402..63ddeef6 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -278,6 +278,7 @@ paths:
                   displayname:
                     type: string
                 additionalProperties:
+                  x-addedInMatrixVersion: "1.14"
                   description:
                     Any additional profile field value; may be any valid JSON type, with keys following the
                     [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).

From 37b1362bc1335c11ef1c90d11ffd5750d259d5e6 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 20 Feb 2025 18:08:10 +0000
Subject: [PATCH 29/81] Attempt to describe variable payload content

---
 data/api/client-server/profile.yaml | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 63ddeef6..17faa0d8 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -53,16 +53,16 @@ paths:
       requestBody:
         description:
           A JSON object that must contain the `keyName` specified in the URL.
-          For custom keys, the value may be any valid JSON type,
-          but if the key is `avatar_url` or `displayname`, the value MUST be a string.
+          For custom keys, the value may be any valid JSON type, but if the key is
+          `avatar_url` or `displayname`, the value MUST be a string.
         required: true
         content:
           application/json:
             schema:
               type: object
-              properties:
-                "<keyName>":
-                  description: The field value to set; may be any valid JSON type.
+              minProperties: 1
+              additionalProperties:
+                description: The field value to set; may be any valid JSON type. For `avatar_url` and `displayname`, the value MUST be a string.
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -148,10 +148,9 @@ paths:
             application/json:
               schema:
                 type: object
-                properties:
-                  "<keyName>":
-                    description: The field value to set; may be any valid JSON type.
-                additionalProperties: false
+                minProperties: 1
+                additionalProperties:
+                  description: The profile field value; may be any valid JSON type.
               examples:
                 response:
                   value: { "displayname": "Alice" }

From 50eab3501e1b2653d7591024c54285d7d2d54a73 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 21 Feb 2025 09:28:46 +0000
Subject: [PATCH 30/81] Standardise line-wrapping and update `avatar_url`
 format to `mx-mxc-uri`

---
 data/api/client-server/profile.yaml | 80 +++++++++++++++++------------
 1 file changed, 47 insertions(+), 33 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 17faa0d8..837dc851 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -22,12 +22,13 @@ paths:
         "1.14": Endpoint now accepts variable `keyName` parameter.
       summary: Set a profile field for a user.
       description: |-
-        Set or update a profile field for a user.
-        Must be authenticated with an access token authorised to make changes.
-        Servers may impose size limits on individual fields, and the total profile must be under 64 KiB.
+        Set or update a profile field for a user. Must be authenticated with an
+        access token authorised to make changes. Servers may impose size limits
+        on individual fields, and the total profile must be under 64 KiB.
 
-        **Note**: Setting a field to `null` keeps the key but with a `null` value, which some servers may reject.
-        To remove a field completely, use the `DELETE` endpoint instead.
+        **Note**: Setting a field to `null` keeps the key but with a `null` value,
+        which some servers may reject. To remove a field completely, use the
+        `DELETE` endpoint instead.
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -42,8 +43,8 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to set.
-            It must be either `avatar_url`, `displayname`, or a custom field following the
+          description: The profile field key name to set. It must be either
+            `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
@@ -51,10 +52,9 @@ paths:
             type: string
             pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
-        description:
-          A JSON object that must contain the `keyName` specified in the URL.
-          For custom keys, the value may be any valid JSON type, but if the key is
-          `avatar_url` or `displayname`, the value MUST be a string.
+        description: A JSON object containing the property whose name matches
+          the `keyName` specified in the URL. See `additionalProperties` for
+          further details.
         required: true
         content:
           application/json:
@@ -62,7 +62,10 @@ paths:
               type: object
               minProperties: 1
               additionalProperties:
-                description: The field value to set; may be any valid JSON type. For `avatar_url` and `displayname`, the value MUST be a string.
+                description: The JSON object must include a property whose key
+                  matches the `keyName` specified in the URL. Its value is the new
+                  profile field value and may be any valid JSON type. However, if the
+                  key is `avatar_url` or `displayname`, the value must be a string.
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -75,8 +78,9 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The request is malformed, contains invalid JSON,
-            missing a required parameter, specifies an invalid key, or exceeds allowed size limits.
+          description: The request is malformed, contains invalid JSON, missing
+            a required parameter, specifies an invalid key, or exceeds allowed
+            size limits.
           content:
             application/json:
               schema:
@@ -95,8 +99,9 @@ paths:
                       "error": "Invalid profile key.",
                     }
         "403":
-          description: The server is unwilling to perform the operation,
-            either due to insufficient permissions or because profile modifications are disabled.
+          description: The server is unwilling to perform the operation, either
+            due to insufficient permissions or because profile modifications
+            are disabled.
           content:
             application/json:
               schema:
@@ -120,8 +125,8 @@ paths:
       x-changedInMatrixVersion:
         "1.14": Endpoint now accepts variable `keyName` parameter.
       summary: Get a profile field for a user.
-      description: |-
-        Get the value of a profile field for a user. Any individual field must be within the total profile limit of 64 KiB.
+      description: Get the value of a profile field for a user. Any individual
+        field must be within the total profile limit of 64 KiB.
       operationId: getProfileField
       parameters:
         - in: path
@@ -133,8 +138,8 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to retrieve.
-            It must be either `avatar_url`, `displayname`, or a custom field following the
+          description: The profile field key name to retrieve. It must be either
+            `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
@@ -150,13 +155,18 @@ paths:
                 type: object
                 minProperties: 1
                 additionalProperties:
-                  description: The profile field value; may be any valid JSON type.
+                  description: The JSON response must include a property whose
+                    key matches the `keyName` specified in the URL. Its value is
+                    the profile field value and may be any valid JSON type.
+                    However, if the key is `avatar_url` or `displayname`, the
+                    value must be a string.
               examples:
                 response:
                   value: { "displayname": "Alice" }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or has the specified profile field.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has the specified profile field.
           content:
             application/json:
               schema:
@@ -169,7 +179,8 @@ paths:
                       "error": "Profile lookup is disabled on this homeserver",
                     }
         "404":
-          description: There is no profile field with this key for this user, or the user does not exist.
+          description: There is no profile field with this key for this user, or
+            the user does not exist.
       tags:
         - User data
     delete:
@@ -190,8 +201,8 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to delete.
-            It must be either `avatar_url`, `displayname`, or a custom field following the
+          description: The profile field key name to delete. It must be either
+            `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
@@ -209,7 +220,8 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The request is malformed, contains invalid JSON, or specifies an invalid key.
+          description: The request is malformed, contains invalid JSON, or
+            specifies an invalid key.
           content:
             application/json:
               schema:
@@ -249,8 +261,8 @@ paths:
     get:
       summary: Get all profile information for a user.
       description: |-
-        Get the complete profile for a user. The response includes `avatar_url` and `displayname`
-        (unless set to `null`) plus any custom profile fields.
+        Get the complete profile for a user. The response includes `avatar_url`
+        and `displayname` (unless set to `null`) plus any custom profile fields.
 
         **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
@@ -272,14 +284,14 @@ paths:
                 properties:
                   avatar_url:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
                     description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
                 additionalProperties:
                   x-addedInMatrixVersion: "1.14"
-                  description:
-                    Any additional profile field value; may be any valid JSON type, with keys following the
+                  description: Any additional profile field value; may be any
+                    valid JSON type, with keys following the
                     [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
               examples:
                 response:
@@ -291,7 +303,8 @@ paths:
                     }
         "403":
           x-addedInMatrixVersion: "1.2"
-          description: The server is unwilling to disclose whether the user exists and/or has profile information.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has profile information.
           content:
             application/json:
               schema:
@@ -304,7 +317,8 @@ paths:
                       "error": "Profile lookup is disabled on this homeserver",
                     }
         "404":
-          description: There is no profile information for this user or this user does not exist.
+          description: There is no profile information for this user or this
+            user does not exist.
           content:
             application/json:
               schema:

From dd4ea948b69d4825920f90a60024571b5bed6e9f Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 21 Feb 2025 09:53:43 +0000
Subject: [PATCH 31/81] Clarify why `avatar_url` and `displayname` can't be
 returned as `null`

---
 data/api/client-server/profile.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 837dc851..b0f0f8f7 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -262,7 +262,8 @@ paths:
       summary: Get all profile information for a user.
       description: |-
         Get the complete profile for a user. The response includes `avatar_url`
-        and `displayname` (unless set to `null`) plus any custom profile fields.
+        and `displayname` (unless set to `null`, as they can only be strings)
+        plus any custom profile fields.
 
         **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile

From 6183f2410f4d85e9f45a18050b6c9485db24edbb Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 21 Feb 2025 10:32:28 +0000
Subject: [PATCH 32/81] Clarify value validation requirements

---
 data/api/client-server/profile.yaml | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index b0f0f8f7..dfe4cb7b 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -63,9 +63,11 @@ paths:
               minProperties: 1
               additionalProperties:
                 description: The JSON object must include a property whose key
-                  matches the `keyName` specified in the URL. Its value is the new
-                  profile field value and may be any valid JSON type. However, if the
-                  key is `avatar_url` or `displayname`, the value must be a string.
+                  matches the `keyName` specified in the URL. For `avatar_url`,
+                  the value must be an MXC URI string. For `displayname`, the value
+                  must be a string. For custom keys, any JSON type is allowed -
+                  servers may not validate these values, but clients should follow
+                  the format defined for that key.
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -155,11 +157,11 @@ paths:
                 type: object
                 minProperties: 1
                 additionalProperties:
-                  description: The JSON response must include a property whose
-                    key matches the `keyName` specified in the URL. Its value is
-                    the profile field value and may be any valid JSON type.
-                    However, if the key is `avatar_url` or `displayname`, the
-                    value must be a string.
+                  description: The JSON response includes a property whose key
+                    matches the `keyName` specified in the URL. For `avatar_url`,
+                    the value will be an MXC URI string. For `displayname`, the
+                    value will be a string. For custom keys, any JSON type is
+                    possible - clients should expect the format defined for that key.
               examples:
                 response:
                   value: { "displayname": "Alice" }

From 6646146f8cdc94cdce7ed6bf18677330d688e7dd Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Fri, 13 Jun 2025 10:26:20 -0400
Subject: [PATCH 33/81] Accept minor suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/modules/guest_access.md |  2 +-
 data/api/client-server/capabilities.yaml          | 13 ++++++++-----
 data/api/client-server/profile.yaml               | 12 ++++++------
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index 7656beb3..0b61f8f4 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -63,7 +63,7 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/{key_name}](#put_matrixclientv3profileuseridkeyname)
+* [PUT /profile/{userId}/{keyName}](#put_matrixclientv3profileuseridkeyname)
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)
diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 4a0af7f4..4a9209ac 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -77,13 +77,13 @@ paths:
                         $ref: '#/components/schemas/booleanCapability'
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
-                          Please refer to `m.profile_fields` for extended profile management.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.set_avatar_url:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their avatar.
-                          Please refer to `m.profile_fields` for extended profile management.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -96,8 +96,11 @@ paths:
                         x-addedInMatrixVersion: "1.14"
                         type: object
                         title: ProfileFieldsCapability
-                        description: Capability to indicate if the user can set or modify extended profile fields.
-                          If absent, clients should assume custom profile fields are supported.
+                        description: Capability to indicate if the user can set or modify extended profile fields via
+                            [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients should assume custom profile fields are supported, provided the
+                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
+                          support for a sufficiently recent spec version.
                         properties:
                           allowed:
                             type: array
@@ -119,7 +122,7 @@ paths:
                               - "org.example.secret_field"
                           enabled:
                             type: boolean
-                            description: True if the user can set or modify any extended profile fields, false otherwise.
+                            description: `true` if the user can set or modify any extended profile fields, `false` otherwise.
                             example: true
                         required:
                           - enabled
diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index dfe4cb7b..b0feea82 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -23,8 +23,8 @@ paths:
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an
-        access token authorised to make changes. Servers may impose size limits
-        on individual fields, and the total profile must be under 64 KiB.
+        access token authorised to make changes. Servers MAY impose size limits
+        on individual fields, and the total profile MUST be under 64 KiB.
 
         **Note**: Setting a field to `null` keeps the key but with a `null` value,
         which some servers may reject. To remove a field completely, use the
@@ -36,7 +36,7 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to set.
+          description: The user whose profile field should be set.
           required: true
           example: "@alice:example.com"
           schema:
@@ -133,7 +133,7 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to get.
+          description: The user whose profile field should be returned.
           required: true
           example: "@alice:example.com"
           schema:
@@ -196,14 +196,14 @@ paths:
       parameters:
         - in: path
           name: userId
-          description: The user whose profile field to delete.
+          description: The user whose profile field should be deleted.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to delete. It must be either
+          description: The key name of the profile field to delete. It must be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true

From d60c847314dce2366b6c4ab56cd45cff9f2d46ca Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Thu, 31 Jul 2025 13:53:55 +0200
Subject: [PATCH 34/81] Add profile_fields capability and deprecations into
 text section

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 content/client-server-api/_index.md | 62 +++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index e7de10eb..7de422a0 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2491,8 +2491,59 @@ using an `unstable` version.
 When this capability is not listed, clients should use `"1"` as the
 default and only stable `available` room version.
 
+### `m.profile_fields` capability
+
+This capability has a flag, `enabled`, and two lists, `allowed` and
+`disallowed`, that together denote which fields the user is able to
+change via the profile endpoints.
+
+When `enabled` is `false`, all profile fields are managed by the server
+and the client is not permitted to make any changes.
+
+When `enabled` is `true`, clients are permitted to modify profile fields,
+subject to the restrictions implied by the OPTIONAL lists `allowed` and
+`disallowed`. If only `allowed` is present, clients can modify all
+contained fields but SHOULD assume all other fields to be managed by
+the server. Contrarily, if only `disallowed` is present, clients are
+unable to modify any contained fields but SHOULD assume all other fields
+to be unmanaged. If both `allowed` and `disallowed` are specified,
+`allowed` takes precendece. This means clients can modify all fields
+in `allowed` but none of the fields in `disallowed` unless they also
+occur in `allowed`. If neither `allowed` nor `disallowed` is present,
+clients can modify all fields without restrictions.
+
+When not listed, clients SHOULD assume the user is able to change
+profile fields without any restrictions, provided the homeserver
+advertises a specification version that includes the `m.profile_fields`
+capability in the [`/versions`](/client-server-api/#get_matrixclientversions)
+response.
+
+An example of the capability API's response for this capability is:
+
+```json
+{
+  "capabilities": {
+    "m.profile_fields": {
+      "enabled": true,
+      "disallowed": ["displayname"]
+    }
+  }
+}
+```
+
 ### `m.set_displayname` capability
 
+{{% boxes/note %}}
+{{% changed-in v="1.16" %}}
+This capability is now deprecated. Clients SHOULD use the
+[`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
+capability instead.
+
+For backwards compatibility, servers that directly or indirectly include
+the `displayname` profile field in the `m.profile_fields` capability
+MUST still set this capability accordingly.
+{{% /boxes/note %}}
+
 This capability has a single flag, `enabled`, to denote whether the user
 is able to change their own display name via profile endpoints. Cases for
 disabling might include users mapped from external identity/directory
@@ -2517,6 +2568,17 @@ An example of the capability API's response for this capability is:
 
 ### `m.set_avatar_url` capability
 
+{{% boxes/note %}}
+{{% changed-in v="1.16" %}}
+This capability is now deprecated. Clients SHOULD use the
+[`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
+capability instead.
+
+For backwards compatibility, servers that directly or indirectly include
+the `avatar_url` profile field in the `m.profile_fields` capability
+MUST still set this capability accordingly.
+{{% /boxes/note %}}
+
 This capability has a single flag, `enabled`, to denote whether the user
 is able to change their own avatar via profile endpoints. Cases for
 disabling might include users mapped from external identity/directory

From 5a082635f79b7ef92ddbc2b3b306e46fcd1e094d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:08:13 +0100
Subject: [PATCH 35/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index b0feea82..4acdc742 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -156,12 +156,13 @@ paths:
               schema:
                 type: object
                 minProperties: 1
-                additionalProperties:
-                  description: The JSON response includes a property whose key
-                    matches the `keyName` specified in the URL. For `avatar_url`,
-                    the value will be an MXC URI string. For `displayname`, the
-                    value will be a string. For custom keys, any JSON type is
-                    possible - clients should expect the format defined for that key.
+                description: If a value is stored for `keyName`, the JSON response
+                  includes a property whose key matches the `keyName` specified
+                  in the URL. For `avatar_url`, the value will be an MXC URI string.
+                  For `displayname`, the value will be a string. For custom keys, any
+                  JSON type is possible - clients should expect the format defined
+                  for that key.
+                additionalProperties: true
               examples:
                 response:
                   value: { "displayname": "Alice" }

From b834933171ed51ec40420d11a0092b5edadc95b3 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:08:24 +0100
Subject: [PATCH 36/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 4acdc742..443aad65 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -61,13 +61,13 @@ paths:
             schema:
               type: object
               minProperties: 1
-              additionalProperties:
-                description: The JSON object must include a property whose key
-                  matches the `keyName` specified in the URL. For `avatar_url`,
-                  the value must be an MXC URI string. For `displayname`, the value
-                  must be a string. For custom keys, any JSON type is allowed -
-                  servers may not validate these values, but clients should follow
-                  the format defined for that key.
+              description: The JSON object must include a property whose key
+                matches the `keyName` specified in the URL. For `avatar_url`,
+                the value must be an MXC URI string. For `displayname`, the value
+                must be a string. For custom keys, any JSON type is allowed -
+                servers may not validate these values, but clients should follow
+                the format defined for that key.
+              additionalProperties: true
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":

From 648c05002afc2e6cdfe7bdc63949422468455e09 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:08:41 +0100
Subject: [PATCH 37/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 443aad65..ba12bb70 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -267,8 +267,6 @@ paths:
         Get the complete profile for a user. The response includes `avatar_url`
         and `displayname` (unless set to `null`, as they can only be strings)
         plus any custom profile fields.
-
-        **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path

From 48ee9cf59c86bf09a658223122e0ab4517b4ca99 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:09:03 +0100
Subject: [PATCH 38/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index ba12bb70..7d84e88b 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -155,7 +155,6 @@ paths:
             application/json:
               schema:
                 type: object
-                minProperties: 1
                 description: If a value is stored for `keyName`, the JSON response
                   includes a property whose key matches the `keyName` specified
                   in the URL. For `avatar_url`, the value will be an MXC URI string.

From 9357cea9ce35139e7cdea91069f12d6859ab4a82 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:09:18 +0100
Subject: [PATCH 39/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 4a9209ac..90075382 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -114,8 +114,11 @@ paths:
                               - "org.example/job_title"
                           disallowed:
                             type: array
-                            description: List of disallowed additional custom profile field keys. A `*` can be used as
-                              a wildcard to match any sequence of characters. Ignored if an allowed list is provided.
+                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              and available for their use.
+                              
+                              Only one of `allowed` and `disallowed` is permitted at the same time.
                             items:
                               type: string
                             example:

From 3f5c14b6793bc1dca39f4ca904ad6ce75310bb55 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:09:33 +0100
Subject: [PATCH 40/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 90075382..3379bcd3 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -125,7 +125,7 @@ paths:
                               - "org.example.secret_field"
                           enabled:
                             type: boolean
-                            description: `true` if the user can set or modify any extended profile fields, `false` otherwise.
+                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
                             example: true
                         required:
                           - enabled

From 22a3405547dacccc72d88a9c4a7db1a75d17453d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:09:45 +0100
Subject: [PATCH 41/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 3379bcd3..6719602a 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -84,6 +84,10 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their avatar.
                           Refer to `m.profile_fields` for extended profile management.
+
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `avatar_url` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations

From 6a8b542d2c3addcbc12ebf4fca681158c8802087 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:09:53 +0100
Subject: [PATCH 42/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 7d84e88b..bce96b47 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -125,7 +125,7 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.14": Endpoint now accepts variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Get a profile field for a user.
       description: Get the value of a profile field for a user. Any individual
         field must be within the total profile limit of 64 KiB.

From 3da3b18779e1d1a6a77fb57dae5766647e6c1a65 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:00 +0100
Subject: [PATCH 43/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index bce96b47..cfdea894 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -186,7 +186,7 @@ paths:
       tags:
         - User data
     delete:
-      x-addedInMatrixVersion: "1.14"
+      x-addedInMatrixVersion: "1.16"
       summary: Remove a profile field from a user.
       description: Remove a specific field from a user's profile.
       operationId: deleteProfileField

From 0a87d1b0a187e9a54b9d6413b3b81ec2bc4eaef6 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:07 +0100
Subject: [PATCH 44/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index cfdea894..19099952 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -43,7 +43,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to set. It must be either
+          description: The profile field key name to set. This MUST be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true

From 4408198e49b52755b675539515cd0b384f88c981 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:20 +0100
Subject: [PATCH 45/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 19099952..f26f0052 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -26,9 +26,9 @@ paths:
         access token authorised to make changes. Servers MAY impose size limits
         on individual fields, and the total profile MUST be under 64 KiB.
 
-        **Note**: Setting a field to `null` keeps the key but with a `null` value,
-        which some servers may reject. To remove a field completely, use the
-        `DELETE` endpoint instead.
+        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
+        them rather than treating `null` as a deletion request. Clients that want to delete a
+        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
       operationId: setProfileField
       security:
         - accessTokenQuery: []

From e78b073bb8ec873ba14911344f9aa95969d211b7 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:32 +0100
Subject: [PATCH 46/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index f26f0052..2c34213b 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -290,7 +290,7 @@ paths:
                   displayname:
                     type: string
                 additionalProperties:
-                  x-addedInMatrixVersion: "1.14"
+                  x-addedInMatrixVersion: "1.16"
                   description: Any additional profile field value; may be any
                     valid JSON type, with keys following the
                     [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).

From c67980a58d94d3daecca90a0bbcc4c597317f2cd Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:39 +0100
Subject: [PATCH 47/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 2c34213b..6742f964 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -19,7 +19,7 @@ paths:
   "/profile/{userId}/{keyName}":
     put:
       x-changedInMatrixVersion:
-        "1.14": Endpoint now accepts variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an

From 7c18c4d091efe028b63de02c88c55218192080cf Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:10:45 +0100
Subject: [PATCH 48/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 6719602a..991a2780 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -97,7 +97,7 @@ paths:
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
                       m.profile_fields:
-                        x-addedInMatrixVersion: "1.14"
+                        x-addedInMatrixVersion: "1.16"
                         type: object
                         title: ProfileFieldsCapability
                         description: Capability to indicate if the user can set or modify extended profile fields via

From 0c6132ef8ebf351ea92ea08ed12bdb0a06be811d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:13:36 +0100
Subject: [PATCH 49/81] Deprecate `m.set_avatar_url` and `m.set_displayname`
 capabilities

---
 changelogs/client_server/newsfragments/2071.deprecation | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelogs/client_server/newsfragments/2071.deprecation

diff --git a/changelogs/client_server/newsfragments/2071.deprecation b/changelogs/client_server/newsfragments/2071.deprecation
new file mode 100644
index 00000000..34beb7a7
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2071.deprecation
@@ -0,0 +1 @@
+Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

From c197a23a7e1d767f3ce8757ff734541e3e04ea2a Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:14:45 +0100
Subject: [PATCH 50/81] Update
 changelogs/client_server/newsfragments/2071.feature

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 changelogs/client_server/newsfragments/2071.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/2071.feature b/changelogs/client_server/newsfragments/2071.feature
index a083a3a6..94b77218 100644
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/changelogs/client_server/newsfragments/2071.feature
@@ -1 +1 @@
-Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Extended profile fields are now supported via the new `m.profile_fields` capability, which deprecates the previous `m.set_avatar_url` and `m.set_displayname` capabilities. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.
+Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability,as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

From f5b92094439acb8b5874314788cdabe5353dcacd Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:15:52 +0100
Subject: [PATCH 51/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 991a2780..205ccfe7 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -115,7 +115,7 @@ paths:
                               type: string
                             example:
                               - "m.example_field"
-                              - "org.example/job_title"
+                              - "org.example.job_title"
                           disallowed:
                             type: array
                             description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to

From df9d3e6991d191b82577fb29640eb1b19ebde2ff Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:18:26 +0100
Subject: [PATCH 52/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 6742f964..4dbc3d8b 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -80,9 +80,16 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The request is malformed, contains invalid JSON, missing
-            a required parameter, specifies an invalid key, or exceeds allowed
-            size limits.
+          description: The input was invalid in some way. This can include one
+            of the following error codes:
+            
+            - `M_BAD_JSON`: The provided value is not valid JSON.
+            - `M_MISSING_PARAM`: The required `{keyName}` property is
+              missing from the request body.
+            - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
+              make the profile exceed its maximum allowed size of 64 KiB.
+            - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the
+              maximum allowed key length of 255 bytes.
           content:
             application/json:
               schema:

From c9057ed1b0152a932b795d1d750bc7c0bddb7e00 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:19:04 +0100
Subject: [PATCH 53/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 4dbc3d8b..90b15752 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -134,8 +134,7 @@ paths:
       x-changedInMatrixVersion:
         "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Get a profile field for a user.
-      description: Get the value of a profile field for a user. Any individual
-        field must be within the total profile limit of 64 KiB.
+      description: Get the value of a profile field for a user.
       operationId: getProfileField
       parameters:
         - in: path

From ea0277649b90f0bc3d064f2a72c32956aa9fff60 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:19:41 +0100
Subject: [PATCH 54/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 205ccfe7..71d8618c 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -101,10 +101,10 @@ paths:
                         type: object
                         title: ProfileFieldsCapability
                         description: Capability to indicate if the user can set or modify extended profile fields via
-                            [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
-                          If absent, clients should assume custom profile fields are supported, provided the
-                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
-                          support for a sufficiently recent spec version.
+                          [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients SHOULD assume custom profile fields are supported, provided the
+                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
                         properties:
                           allowed:
                             type: array

From 0051295e94384736d1cba9aa8499cdeffafdd4b0 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:20:39 +0100
Subject: [PATCH 55/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 71d8618c..1af8360a 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -78,6 +78,10 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
                           Refer to `m.profile_fields` for extended profile management.
+                          
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `displayname` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.set_avatar_url:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'

From 4293659dc58af3c6a9f199ad8f2a478a43eb7538 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Thu, 31 Jul 2025 14:21:28 +0100
Subject: [PATCH 56/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/capabilities.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 1af8360a..23385751 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -130,7 +130,7 @@ paths:
                             items:
                               type: string
                             example:
-                              - "org.example.secret_field"
+                              - "org.example.managed_field"
                           enabled:
                             type: boolean
                             description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."

From 578e1fbc82a100c8ea23cd38d4915fd553a0a947 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Fri, 1 Aug 2025 20:05:44 +0100
Subject: [PATCH 57/81] Update
 content/client-server-api/modules/guest_access.md

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
---
 content/client-server-api/modules/guest_access.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index 0b61f8f4..8fa5b9a0 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -63,7 +63,8 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/{keyName}](#put_matrixclientv3profileuseridkeyname)
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
+* [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

From f2c14eee9caef8a6fd051f19bf115599faa82080 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Tue, 5 Aug 2025 17:42:47 +0100
Subject: [PATCH 58/81] Fix invalid YAML

---
 data/api/client-server/profile.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 90b15752..38d30719 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -80,7 +80,8 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The input was invalid in some way. This can include one
+          description: |
+            The input was invalid in some way. This can include one
             of the following error codes:
             
             - `M_BAD_JSON`: The provided value is not valid JSON.

From f44ccf4c035c7cf156bb00b8fb5a0f07d5cf5ac6 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:46:42 +0100
Subject: [PATCH 59/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 38d30719..a03c4bba 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -298,9 +298,7 @@ paths:
                     type: string
                 additionalProperties:
                   x-addedInMatrixVersion: "1.16"
-                  description: Any additional profile field value; may be any
-                    valid JSON type, with keys following the
-                    [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+                  description: Additional profile fields.
               examples:
                 response:
                   value:

From a10fea207afcb475c6312a25e1064c41e36d458c Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:46:59 +0100
Subject: [PATCH 60/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index a03c4bba..a9dda534 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -296,6 +296,8 @@ paths:
                     description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
+                    description: The user's display name if they have set one, otherwise not
+                      present.
                 additionalProperties:
                   x-addedInMatrixVersion: "1.16"
                   description: Additional profile fields.

From c2827c4083fe49f6176d25b89215a71b8a94cf7b Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:47:12 +0100
Subject: [PATCH 61/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index a9dda534..b5ecc690 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -293,7 +293,7 @@ paths:
                   avatar_url:
                     type: string
                     format: mx-mxc-uri
-                    description: "Avatar URL value (MXC URI format)."
+                    description: The user's avatar URL if they have set one, otherwise not present.
                   displayname:
                     type: string
                     description: The user's display name if they have set one, otherwise not

From e64320880b298b82bdfd232bd2906c63015ff55a Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:47:25 +0100
Subject: [PATCH 62/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index b5ecc690..ac2bcb53 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -270,9 +270,7 @@ paths:
     get:
       summary: Get all profile information for a user.
       description: |-
-        Get the complete profile for a user. The response includes `avatar_url`
-        and `displayname` (unless set to `null`, as they can only be strings)
-        plus any custom profile fields.
+        Get the complete profile for a user.
       operationId: getUserProfile
       parameters:
         - in: path

From 105ad398455cbc7c1ce03fc004d76ae763ba0001 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:47:40 +0100
Subject: [PATCH 63/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index ac2bcb53..1cd959fc 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -43,7 +43,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to set. This MUST be either
+          description: The name of the profile field to set. This MUST be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true

From 6dba7990dec5ad6ae9561fd4864d0bfb8d109336 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:47:55 +0100
Subject: [PATCH 64/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 1cd959fc..6a80f454 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -19,7 +19,7 @@ paths:
   "/profile/{userId}/{keyName}":
     put:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an

From 88697f7fd98f888d2139be91bc239fc6b4b273d1 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:48:11 +0100
Subject: [PATCH 65/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/capabilities.yaml | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 23385751..98fe88d7 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -122,11 +122,12 @@ paths:
                               - "org.example.job_title"
                           disallowed:
                             type: array
-                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
-                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
-                              and available for their use.
+                            description:  |
+                              This property has no meaning if `allowed` is also specified.
                               
-                              Only one of `allowed` and `disallowed` is permitted at the same time.
+                              Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
+                              Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
+                              included in this list.
                             items:
                               type: string
                             example:

From ec7fa46581871daee46ca7bc2725194f503c4063 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:49:03 +0100
Subject: [PATCH 66/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 6a80f454..e6b68a9a 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -61,12 +61,16 @@ paths:
             schema:
               type: object
               minProperties: 1
-              description: The JSON object must include a property whose key
-                matches the `keyName` specified in the URL. For `avatar_url`,
-                the value must be an MXC URI string. For `displayname`, the value
-                must be a string. For custom keys, any JSON type is allowed -
-                servers may not validate these values, but clients should follow
-                the format defined for that key.
+              description: |
+                An object which contains exactly one property. The key
+                of that property MUST match the `keyName` specified in the URL.
+                
+                For `avatar_url`, the value MUST be an MXC URI string. 
+                
+                For `displayname`, the value MUST be a string.
+                
+                For custom keys, any JSON type is allowed. Servers MAY not validate
+                these values, but clients SHOULD follow the format defined for that key.
               additionalProperties: true
               example: { "displayname": "Alice Wonderland" }
       responses:

From ef266e87dd0c555849f8d632f7fe45c8c870d559 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:49:16 +0100
Subject: [PATCH 67/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index e6b68a9a..ba195553 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -137,7 +137,7 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
       summary: Get a profile field for a user.
       description: Get the value of a profile field for a user.
       operationId: getProfileField

From 6b85e93d203c72e744b0ab6e04c266d4b3e5a731 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:49:27 +0100
Subject: [PATCH 68/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index ba195553..eb394b04 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -151,9 +151,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to retrieve. It must be either
-            `avatar_url`, `displayname`, or a custom field following the
-            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          description: The name of the profile field to retrieve.
           required: true
           example: "displayname"
           schema:

From 4bb5ae85aea9f82e9f5bbcb7c7d8d01a4c71807d Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:49:41 +0100
Subject: [PATCH 69/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index eb394b04..0c519fa9 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -89,7 +89,7 @@ paths:
             of the following error codes:
             
             - `M_BAD_JSON`: The provided value is not valid JSON.
-            - `M_MISSING_PARAM`: The required `{keyName}` property is
+            - `M_MISSING_PARAM`: The required `keyName` property is
               missing from the request body.
             - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
               make the profile exceed its maximum allowed size of 64 KiB.

From 947cc30046b70f8d3207207febc15129ec99a8ad Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:50:24 +0100
Subject: [PATCH 70/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 0c519fa9..527475c6 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -164,12 +164,9 @@ paths:
             application/json:
               schema:
                 type: object
-                description: If a value is stored for `keyName`, the JSON response
-                  includes a property whose key matches the `keyName` specified
-                  in the URL. For `avatar_url`, the value will be an MXC URI string.
-                  For `displayname`, the value will be a string. For custom keys, any
-                  JSON type is possible - clients should expect the format defined
-                  for that key.
+                description: |
+                  An object with one property, whose key matches the `keyName` specified
+                  in the URL, and whose value is the current setting of that profile field.
                 additionalProperties: true
               examples:
                 response:

From 187aeb07a342f417625f12570c93b9331e0727ed Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:50:57 +0100
Subject: [PATCH 71/81] Update data/api/client-server/capabilities.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/capabilities.yaml | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 98fe88d7..2e8c8849 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -112,9 +112,12 @@ paths:
                         properties:
                           allowed:
                             type: array
-                            description: List of allowed additional custom profile field keys. A `*` can be used as a
-                              wildcard to match any sequence of characters. This list takes precedence over the
-                              disallowed list if both are provided.
+                            description: |
+                              If present, a list of profile fields that clients are allowed to create, modify or delete,
+                              provided `enabled` is `true`; no other profile fields may be changed.
+                              
+                              If absent, clients may set all profile fields except those forbidden by the `disallowed`
+                              list, where present.
                             items:
                               type: string
                             example:

From eb8d9ec14ef2d75c9826410f527c2cb71759ff33 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:51:14 +0100
Subject: [PATCH 72/81] Update data/api/client-server/profile.yaml

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 data/api/client-server/profile.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 527475c6..34525a4d 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -209,9 +209,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The key name of the profile field to delete. It must be either
-            `avatar_url`, `displayname`, or a custom field following the
-            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          description: The name of the profile field to delete.
           required: true
           example: "displayname"
           schema:

From 7c678656463da14fb8e14092905b100ea9377fb4 Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 07:52:46 +0100
Subject: [PATCH 73/81] Update
 content/client-server-api/modules/guest_access.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/modules/guest_access.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index 8fa5b9a0..2e5ee3a0 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -63,8 +63,8 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
-* [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname). Guest users may only modify their display name; other profile fields may not be changed.
+* {{% added-in v="1.16" %}} [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname). Again, guest users may delete their display name but not other profile fields.
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

From 729d50cd4a44d3e99e2b8414d7a6f31af3b39dbe Mon Sep 17 00:00:00 2001
From: Tom Foster <tom@tcpip.uk>
Date: Wed, 6 Aug 2025 08:58:07 +0100
Subject: [PATCH 74/81] Update data/api/client-server/profile.yaml

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 data/api/client-server/profile.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 34525a4d..dbbc1950 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -217,7 +217,7 @@ paths:
             pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The profile field was deleted.
+          description: The profile field was deleted or it doesn't exist.
           content:
             application/json:
               schema:

From 78ca69093553b552f9d1b1af083e3a1f2bc2c600 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:12:33 +0200
Subject: [PATCH 75/81] Update content/client-server-api/_index.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/_index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 7de422a0..e09a47bd 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2493,6 +2493,8 @@ default and only stable `available` room version.
 
 ### `m.profile_fields` capability
 
+{{% added-in v="1.16" %}}
+
 This capability has a flag, `enabled`, and two lists, `allowed` and
 `disallowed`, that together denote which fields the user is able to
 change via the profile endpoints.

From 08ef01beeca75eb65fb75bddb4647741c55267ce Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:12:56 +0200
Subject: [PATCH 76/81] Update content/client-server-api/_index.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/_index.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index e09a47bd..0b76a371 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2495,9 +2495,11 @@ default and only stable `available` room version.
 
 {{% added-in v="1.16" %}}
 
-This capability has a flag, `enabled`, and two lists, `allowed` and
-`disallowed`, that together denote which fields the user is able to
-change via the profile endpoints.
+This capability defines which [profile](#profiles) fields the user is
+able to change.
+
+The capability value has a required flag, `enabled`, and two optional lists, `allowed` and
+`disallowed`.
 
 When `enabled` is `false`, all profile fields are managed by the server
 and the client is not permitted to make any changes.

From a644bcd7a114e69bc4eee3ce0dd9a739a5937574 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:18:13 +0200
Subject: [PATCH 77/81] Update content/client-server-api/_index.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/_index.md | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 0b76a371..2a7cc5a2 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2506,15 +2506,18 @@ and the client is not permitted to make any changes.
 
 When `enabled` is `true`, clients are permitted to modify profile fields,
 subject to the restrictions implied by the OPTIONAL lists `allowed` and
-`disallowed`. If only `allowed` is present, clients can modify all
-contained fields but SHOULD assume all other fields to be managed by
-the server. Contrarily, if only `disallowed` is present, clients are
-unable to modify any contained fields but SHOULD assume all other fields
-to be unmanaged. If both `allowed` and `disallowed` are specified,
-`allowed` takes precendece. This means clients can modify all fields
-in `allowed` but none of the fields in `disallowed` unless they also
-occur in `allowed`. If neither `allowed` nor `disallowed` is present,
-clients can modify all fields without restrictions.
+`disallowed`. 
+
+If `allowed` is present, clients can modify only the fields
+listed. They SHOULD assume all other fields to be managed by
+the server. In this case, `disallowed` has no meaning and should be ignored.
+
+If `disallowed` is present (and `allowed` is not), clients should assume
+that the listed fields are managed by the server. Clients may modify any
+fields that are *not* listed, provided `enabled` is `true`.
+
+If neither `allowed` nor `disallowed` is present, clients can modify all fields
+without restrictions, provided `enabled` is `true`.
 
 When not listed, clients SHOULD assume the user is able to change
 profile fields without any restrictions, provided the homeserver

From cd527f5b58a4c371663dc15c079ff79aaa1c4d46 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:18:26 +0200
Subject: [PATCH 78/81] Update content/client-server-api/_index.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 2a7cc5a2..9110281b 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2519,7 +2519,7 @@ fields that are *not* listed, provided `enabled` is `true`.
 If neither `allowed` nor `disallowed` is present, clients can modify all fields
 without restrictions, provided `enabled` is `true`.
 
-When not listed, clients SHOULD assume the user is able to change
+When this capability is not listed, clients SHOULD assume the user is able to change
 profile fields without any restrictions, provided the homeserver
 advertises a specification version that includes the `m.profile_fields`
 capability in the [`/versions`](/client-server-api/#get_matrixclientversions)

From 11cc84829797738a58ba6d58a75758c137750fff Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:23:44 +0200
Subject: [PATCH 79/81] Update content/client-server-api/_index.md

---
 content/client-server-api/_index.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 9110281b..426245fc 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2581,9 +2581,9 @@ This capability is now deprecated. Clients SHOULD use the
 [`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
 capability instead.
 
-For backwards compatibility, servers that directly or indirectly include
-the `avatar_url` profile field in the `m.profile_fields` capability
-MUST still set this capability accordingly.
+For backwards compatibility, servers that forbid setting the 
+`avatar_url` profile field in the `m.profile_fields` capability
+MUST still present this capability with `"enabled": false`.
 {{% /boxes/note %}}
 
 This capability has a single flag, `enabled`, to denote whether the user

From 681a7618c0b85d5d074514481c55a93508dd8799 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:23:51 +0200
Subject: [PATCH 80/81] Update content/client-server-api/_index.md

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 content/client-server-api/_index.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 426245fc..4d23b636 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2546,9 +2546,9 @@ This capability is now deprecated. Clients SHOULD use the
 [`m.profile_fields`](/client-server-api/#mprofile_fields-capability)
 capability instead.
 
-For backwards compatibility, servers that directly or indirectly include
-the `displayname` profile field in the `m.profile_fields` capability
-MUST still set this capability accordingly.
+For backwards compatibility, servers that forbid setting the 
+`displayname` profile field in the `m.profile_fields` capability
+MUST still present this capability with `"enabled": false`.
 {{% /boxes/note %}}
 
 This capability has a single flag, `enabled`, to denote whether the user

From 0d89ec84e2dc908268438ca1cc512f4fdc12f4bb Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 6 Aug 2025 13:25:29 +0200
Subject: [PATCH 81/81] Update content/client-server-api/_index.md

---
 content/client-server-api/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 4d23b636..2c48a7b6 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2512,7 +2512,7 @@ If `allowed` is present, clients can modify only the fields
 listed. They SHOULD assume all other fields to be managed by
 the server. In this case, `disallowed` has no meaning and should be ignored.
 
-If `disallowed` is present (and `allowed` is not), clients should assume
+If `disallowed` is present (and `allowed` is not), clients SHOULD assume
 that the listed fields are managed by the server. Clients may modify any
 fields that are *not* listed, provided `enabled` is `true`.