Merge b036a24a61 into 7d2de48cb4

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2071.deprecation

@@ -1 +0,0 @@
-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 @@
-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).
+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.

data/api/client-server/capabilities.yaml

@@ -78,20 +78,12 @@ 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
@@ -101,14 +93,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.16"
+                        x-addedInMatrixVersion: "1.14"
                         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
+                          If absent, clients should assume custom profile fields are supported, provided the
-                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
-                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
+                          support for a sufficiently recent spec version.
                         properties:
                           allowed:
                             type: array
@@ -119,21 +111,18 @@ paths:
                               type: string
                             example:
                               - "m.example_field"
-                              - "org.example.job_title"
+                              - "org.example/job_title"
                           disallowed:
                             type: array
-                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                            description: List of disallowed additional custom profile field keys. A `*` can be used as
-                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              a wildcard to match any sequence of characters. Ignored if an allowed list is provided.
-                              and available for their use.
-                              
-                              Only one of `allowed` and `disallowed` is permitted at the same time.
                             items:
                               type: string
                             example:
-                              - "org.example.managed_field"
+                              - "org.example.secret_field"
                           enabled:
                             type: boolean
-                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
+                            description: `true` if the user can set or modify any extended 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.16": This endpoint now accepts a variable `keyName` parameter.
+        "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.
 
-        Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
+        **Note**: Setting a field to `null` keeps the key but with a `null` value,
-        them rather than treating `null` as a deletion request. Clients that want to delete a
+        which some servers may reject. To remove a field completely, use the
-        field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+        `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. This MUST be either
+          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
@@ -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.
-              additionalProperties: true
               example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
@@ -80,16 +80,9 @@ paths:
                 response:
                   value: {}
         "400":
-          description: The input was invalid in some way. This can include one
+          description: The request is malformed, contains invalid JSON, missing
-            of the following error codes:
+            a required parameter, specifies an invalid key, or exceeds allowed
-            
+            size limits.
-            - `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:
@@ -132,9 +125,10 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter.
+        "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.
+      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
@@ -161,13 +155,13 @@ paths:
             application/json:
               schema:
                 type: object
-                description: If a value is stored for `keyName`, the JSON response
+                minProperties: 1
-                  includes a property whose key matches the `keyName` specified
+                additionalProperties:
-                  in the URL. For `avatar_url`, the value will be an MXC URI string.
+                  description: The JSON response includes a property whose key
-                  For `displayname`, the value will be a string. For custom keys, any
+                    matches the `keyName` specified in the URL. For `avatar_url`,
-                  JSON type is possible - clients should expect the format defined
+                    the value will be an MXC URI string. For `displayname`, the
-                  for that key.
+                    value will be a string. For custom keys, any JSON type is
-                additionalProperties: true
+                    possible - clients should expect the format defined for that key.
               examples:
                 response:
                   value: { "displayname": "Alice" }
@@ -192,7 +186,7 @@ paths:
       tags:
         - User data
     delete:
-      x-addedInMatrixVersion: "1.16"
+      x-addedInMatrixVersion: "1.14"
       summary: Remove a profile field from a user.
       description: Remove a specific field from a user's profile.
       operationId: deleteProfileField
@@ -272,6 +266,8 @@ 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
@@ -296,7 +292,7 @@ paths:
                   displayname:
                     type: string
                 additionalProperties:
-                  x-addedInMatrixVersion: "1.16"
+                  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).