Merge 4293659dc5 into 7d2de48cb4

Co-authored-by: Johannes Marbach <n0-0ne+github@mailbox.org>

changelogs/client_server/newsfragments/2071.deprecation

@@ -0,0 +1 @@
+Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

changelogs/client_server/newsfragments/2071.feature

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

data/api/client-server/capabilities.yaml

@@ -78,12 +78,20 @@ paths:
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their display name.
                           Refer to `m.profile_fields` for extended profile management.
+                          
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `displayname` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.set_avatar_url:
                         deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
                         description: |
                           **Deprecated:** Capability to indicate if the user can change their avatar.
                           Refer to `m.profile_fields` for extended profile management.
+
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `avatar_url` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -93,14 +101,14 @@ paths:
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
                       m.profile_fields:
-                        x-addedInMatrixVersion: "1.14"
+                        x-addedInMatrixVersion: "1.16"
                         type: object
                         title: ProfileFieldsCapability
                         description: Capability to indicate if the user can set or modify extended profile fields via
-                            [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
-                          If absent, clients should assume custom profile fields are supported, provided the
-                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
-                          support for a sufficiently recent spec version.
+                          [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients SHOULD assume custom profile fields are supported, provided the
+                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
                         properties:
                           allowed:
                             type: array
@@ -111,18 +119,21 @@ paths:
                               type: string
                             example:
                               - "m.example_field"
-                              - "org.example/job_title"
+                              - "org.example.job_title"
                           disallowed:
                             type: array
-                            description: List of disallowed additional custom profile field keys. A `*` can be used as
-                              a wildcard to match any sequence of characters. Ignored if an allowed list is provided.
+                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              and available for their use.
+                              
+                              Only one of `allowed` and `disallowed` is permitted at the same time.
                             items:
                               type: string
                             example:
-                              - "org.example.secret_field"
+                              - "org.example.managed_field"
                           enabled:
                             type: boolean
-                            description: `true` if the user can set or modify any extended profile fields, `false` otherwise.
+                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
                             example: true
                         required:
                           - enabled

data/api/client-server/profile.yaml

@@ -19,16 +19,16 @@ paths:
   "/profile/{userId}/{keyName}":
     put:
       x-changedInMatrixVersion:
-        "1.14": Endpoint now accepts variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an
         access token authorised to make changes. Servers MAY impose size limits
         on individual fields, and the total profile MUST be under 64 KiB.
 
-        **Note**: Setting a field to `null` keeps the key but with a `null` value,
-        which some servers may reject. To remove a field completely, use the
-        `DELETE` endpoint instead.
+        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
+        them rather than treating `null` as a deletion request. Clients that want to delete a
+        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
       operationId: setProfileField
       security:
         - accessTokenQuery: []
@@ -43,7 +43,7 @@ paths:
             type: string
         - in: path
           name: keyName
-          description: The profile field key name to set. It must be either
+          description: The profile field key name to set. This MUST be either
             `avatar_url`, `displayname`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
@@ -61,13 +61,13 @@ paths:
             schema:
               type: object
               minProperties: 1
-              additionalProperties:
-                description: The JSON object must include a property whose key
-                  matches the `keyName` specified in the URL. For `avatar_url`,
-                  the value must be an MXC URI string. For `displayname`, the value
-                  must be a string. For custom keys, any JSON type is allowed -
-                  servers may not validate these values, but clients should follow
-                  the format defined for that key.
+              description: The JSON object must include a property whose key
+                matches the `keyName` specified in the URL. For `avatar_url`,
+                the value must be an MXC URI string. For `displayname`, the value
+                must be a string. For custom keys, any JSON type is allowed -
+                servers may not validate these values, but clients should follow
+                the format defined for that key.
+              additionalProperties: true
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -80,9 +80,16 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The request is malformed, contains invalid JSON, missing
-            a required parameter, specifies an invalid key, or exceeds allowed
-            size limits.
+          description: The input was invalid in some way. This can include one
+            of the following error codes:
+            
+            - `M_BAD_JSON`: The provided value is not valid JSON.
+            - `M_MISSING_PARAM`: The required `{keyName}` property is
+              missing from the request body.
+            - `M_PROFILE_TOO_LARGE`: Storing the supplied value would
+              make the profile exceed its maximum allowed size of 64 KiB.
+            - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the
+              maximum allowed key length of 255 bytes.
           content:
             application/json:
               schema:
@@ -125,10 +132,9 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.14": Endpoint now accepts variable `keyName` parameter.
+        "1.16": This endpoint now accepts a variable `keyName` parameter.
       summary: Get a profile field for a user.
-      description: Get the value of a profile field for a user. Any individual
-        field must be within the total profile limit of 64 KiB.
+      description: Get the value of a profile field for a user.
       operationId: getProfileField
       parameters:
         - in: path
@@ -155,13 +161,13 @@ paths:
             application/json:
               schema:
                 type: object
-                minProperties: 1
-                additionalProperties:
-                  description: The JSON response includes a property whose key
-                    matches the `keyName` specified in the URL. For `avatar_url`,
-                    the value will be an MXC URI string. For `displayname`, the
-                    value will be a string. For custom keys, any JSON type is
-                    possible - clients should expect the format defined for that key.
+                description: If a value is stored for `keyName`, the JSON response
+                  includes a property whose key matches the `keyName` specified
+                  in the URL. For `avatar_url`, the value will be an MXC URI string.
+                  For `displayname`, the value will be a string. For custom keys, any
+                  JSON type is possible - clients should expect the format defined
+                  for that key.
+                additionalProperties: true
               examples:
                 response:
                   value: { "displayname": "Alice" }
@@ -186,7 +192,7 @@ paths:
       tags:
         - User data
     delete:
-      x-addedInMatrixVersion: "1.14"
+      x-addedInMatrixVersion: "1.16"
       summary: Remove a profile field from a user.
       description: Remove a specific field from a user's profile.
       operationId: deleteProfileField
@@ -266,8 +272,6 @@ paths:
         Get the complete profile for a user. The response includes `avatar_url`
         and `displayname` (unless set to `null`, as they can only be strings)
         plus any custom profile fields.
-
-        **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -292,7 +296,7 @@ paths:
                   displayname:
                     type: string
                 additionalProperties:
-                  x-addedInMatrixVersion: "1.14"
+                  x-addedInMatrixVersion: "1.16"
                   description: Any additional profile field value; may be any
                     valid JSON type, with keys following the
                     [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).