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/33] Describe MSC4133 profile endpoint changes

---
 data/api/client-server/profile.yaml | 286 +++++++++++++++-------------
 1 file changed, 152 insertions(+), 134 deletions(-)

diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 6e588ae33..70966b076 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,163 +104,140 @@ 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: {}
-        "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $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.
+        "400":
+          description: >
+            The request is malformed or specifies an invalid key.
           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.
+                $ref: definitions/errors/error.yaml
               examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-                  }
+                bad_request:
+                  value:
+                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
         "403":
-          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has an avatar URL.
+          description: >
+            The user is not authorised to delete this 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"
-                  }
-        "404":
-          description: There is no avatar URL for this user or this user does not exist.
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       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/33] 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 000000000..3097a5122
--- /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/33] 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 3097a5122..000000000
--- 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 000000000..85fe9db49
--- /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/33] 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 70966b076..5900cf1b6 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/33] 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 5900cf1b6..4a2fdbbeb 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/33] 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 85fe9db49..61ea25b39 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/33] 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 61ea25b39..00695c462 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/33] 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 4a2fdbbeb..5fcb840f9 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/33] 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 5fcb840f9..846c14c69 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/33] 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 846c14c69..e4525a176 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/33] 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 e4525a176..fdeaeadce 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/33] 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 00695c462..25c338f24 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 523c6091c..c28535865 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/33] 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 fdeaeadce..e210a145e 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/33] 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 c28535865..93e0cb908 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/33] 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 e210a145e..842d34843 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/33] 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 93e0cb908..b340a5175 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/33] 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 ada9e71e9..7656beb38 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/33] 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 842d34843..583f6d199 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/33] 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 583f6d199..732ae34d5 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/33] 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 b340a5175..9e4810f1a 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/33] 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 25c338f24..a083a3a63 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/33] 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 9e4810f1a..a19bec1ca 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/33] 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 a19bec1ca..0dc983b87 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/33] 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 0dc983b87..aa69ef58b 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/33] 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 732ae34d5..438288c78 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/33] 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 438288c78..8b009a685 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/33] 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 aa69ef58b..4a0af7f48 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 8b009a685..9792a402c 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/33] 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 9792a402c..63ddeef64 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/33] 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 63ddeef64..17faa0d8f 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/33] 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 17faa0d8f..837dc851f 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/33] 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 837dc851f..b0f0f8f76 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/33] 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 b0f0f8f76..dfe4cb7b4 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/33] 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 7656beb38..0b61f8f42 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 4a0af7f48..4a9209ac3 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 dfe4cb7b4..b0feea826 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