Spec for MSC4133: Update profile endpoints to support extended fields

changelogs/client_server/newsfragments/2071.feature

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

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)

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
@@ -86,6 +88,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 custom profile fields are supported.
               examples:
                 response:
                   value: {
@@ -144,3 +150,30 @@ 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