Spec for MSC4133: Update profile endpoints to support extended fields

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

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

content/client-server-api/modules/guest_access.md

@@ -63,7 +63,8 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
+* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
+* [DELETE /profile/{userId}/displayname](#delete_matrixclientv3profileuseridkeyname) guests users may only modify their displayname in their profile
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

data/api/client-server/capabilities.yaml

@@ -73,11 +73,25 @@ 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.
+                          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: Capability to indicate if the user can change their avatar.
+                        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
@@ -86,6 +100,43 @@ 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:
+                        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
+                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
+                        properties:
+                          allowed:
+                            type: array
+                            description: List of allowed additional custom profile field keys. A `*` can be used as a
+                              wildcard to match any sequence of characters. This list takes precedence over the
+                              disallowed list if both are provided.
+                            items:
+                              type: string
+                            example:
+                              - "m.example_field"
+                              - "org.example.job_title"
+                          disallowed:
+                            type: array
+                            description: If `enabled` is `true`, a list of profile fields that clients are _not_ allowed to
+                              create, modify or delete. Clients SHOULD assume all fields not in this list to be unmanaged
+                              and available for their use.
+
+                              Only one of `allowed` and `disallowed` is permitted at the same time.
+                            items:
+                              type: string
+                            example:
+                              - "org.example.managed_field"
+                          enabled:
+                            type: boolean
+                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
+                            example: true
+                        required:
+                          - enabled
               examples:
                 response:
                   value: {