Merge 6646146f8c 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/application_service/newsfragments/2182.clarification

@@ -0,0 +1 @@
+Minor fixes to JSON schemas.

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.

changelogs/client_server/newsfragments/2182.clarification

@@ -0,0 +1 @@
+Minor fixes to JSON schemas.

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}/{keyName}](#put_matrixclientv3profileuseridkeyname)
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

data/api/application-service/definitions/protocol.yaml

@@ -23,3 +23,4 @@ allOf:
       type: array
       items:
         $ref: protocol_instance.yaml
+  required: ['instances']

data/api/application-service/definitions/protocol_base.yaml

@@ -77,4 +77,4 @@ properties:
         "placeholder": "#foobar"
       }
     }
-required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']
+required: ['user_fields', 'location_fields', 'icon', 'field_types']

data/api/client-server/capabilities.yaml

@@ -73,11 +73,17 @@ 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.
                       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.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -86,6 +92,40 @@ 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.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
+                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
+                          support for a sufficiently recent spec version.
+                        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: 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:
+                              - "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: {

data/api/client-server/definitions/protocol.yaml

@@ -37,7 +37,8 @@ allOf:
                   A unique identifier for this instance on the homeserver. This field is added
                   to the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
                   by the homeserver.
-                  
+
                   This is the identifier to use as the `third_party_instance_id` in a request to
                   [`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms).
                 example: "irc-freenode"
+  required: ['instances']

data/api/client-server/definitions/room_summary.yaml

@@ -42,9 +42,3 @@ allOf:
       room_version:
         description: The version of the room.
         type: string
-
-required:
-  - room_id
-  - num_joined_members
-  - world_readable
-  - guest_can_join

data/api/client-server/profile.yaml

@@ -16,48 +16,105 @@ info:
   title: Matrix Client-Server Profile API
   version: 1.0.0
 paths:
-  "/profile/{userId}/displayname":
+  "/profile/{userId}/{keyName}":
     put:
-      summary: Set the user's display name.
+      x-changedInMatrixVersion:
+        "1.14": Endpoint now accepts variable `keyName` parameter.
+      summary: Set a profile field for a user.
       description: |-
-        This API sets the given user's display name. You must have permission to
+        Set or update a profile field for a user. Must be authenticated with an
-        set this user's display name, e.g. you need to have their `access_token`.
+        access token authorised to make changes. Servers MAY impose size limits
-      operationId: setDisplayName
+        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.
+      operationId: setProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to set.
+          description: The user whose profile field should be set.
           required: true
           example: "@alice:example.com"
           schema:
             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
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
+        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:
             schema:
               type: object
-              example: {
+              minProperties: 1
-                "displayname": "Alice Margatroid"
+              additionalProperties:
-              }
+                description: The JSON object must include a property whose key
-              properties:
+                  matches the `keyName` specified in the URL. For `avatar_url`,
-                displayname:
+                  the value must be an MXC URI string. For `displayname`, the value
-                  type: string
+                  must be a string. For custom keys, any JSON type is allowed -
-                  description: The new display name for this user.
+                  servers may not validate these values, but clients should follow
-        description: The new display name information.
+                  the format defined for that key.
-        required: true
+              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, contains invalid JSON, missing
+            a required parameter, specifies an invalid key, or exceeds allowed
+            size limits.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                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 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,98 +124,133 @@ paths:
       tags:
         - User data
     get:
-      summary: Get the user's display name.
+      x-changedInMatrixVersion:
-      description: |-
+        "1.14": Endpoint now accepts variable `keyName` parameter.
-        Get the user's display name. This API may be used to fetch the user's
+      summary: Get a profile field for a user.
-        own displayname or to query the name of other users; either locally or
+      description: Get the value of a profile field for a user. Any individual
-        on remote homeservers.
+        field must be within the total profile limit of 64 KiB.
-      operationId: getDisplayName
+      operationId: getProfileField
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to get.
+          description: The user whose profile field should be returned.
           required: true
           example: "@alice:example.com"
           schema:
             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
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The display name for this user.
+          description: The profile field value was retrieved.
           content:
             application/json:
               schema:
                 type: object
-                properties:
+                minProperties: 1
-                  displayname:
+                additionalProperties:
-                    type: string
+                  description: The JSON response includes a property whose key
-                    description: The user's display name if they have set one, otherwise not
+                    matches the `keyName` specified in the URL. For `avatar_url`,
-                      present.
+                    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: {
+                  value: { "displayname": "Alice" }
-                    "displayname": "Alice Margatroid"
-                  }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
+          description: The server is unwilling to disclose whether the user
-            has a display name.
+            exists and/or has the specified profile field.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_FORBIDDEN",
+                    {
-                    "error": "Profile lookup is disabled on this homeserver"
+                      "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":
+    delete:
-    put:
+      x-addedInMatrixVersion: "1.14"
-      summary: Set the user's avatar URL.
+      summary: Remove a profile field from a user.
-      description: |-
+      description: Remove a specific field from a user's profile.
-        This API sets the given user's avatar URL. You must have permission to
+      operationId: deleteProfileField
-        set this user's avatar URL, e.g. you need to have their `access_token`.
-      operationId: setAvatarUrl
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose avatar URL to set.
+          description: The user whose profile field should be deleted.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
-      requestBody:
+        - in: path
-        content:
+          name: keyName
-          application/json:
+          description: The key name of the profile field to delete. It must be either
-            schema:
+            `avatar_url`, `displayname`, or a custom field following the
-              type: object
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
-              example: {
+          required: true
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
+          example: "displayname"
-              }
+          schema:
-              properties:
+            type: string
-                avatar_url:
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
-                  type: string
-                  format: uri
-                  description: The new avatar URL for this user.
-        description: The new avatar information.
-        required: true
       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: {}
+        "400":
+          description: The request is malformed, contains invalid JSON, or
+            specifies an invalid key.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                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.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -167,63 +259,15 @@ paths:
                 $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.
-          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.
-              examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-                  }
-        "403":
-          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has an avatar URL.
-          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.
-      tags:
-        - User data
   "/profile/{userId}":
     get:
-      summary: Get this user's profile information.
+      summary: Get all profile information for a user.
       description: |-
-        Get the combined profile information for this user. This API may be used
+        Get the complete profile for a user. The response includes `avatar_url`
-        to fetch the user's own profile information or other users; either
+        and `displayname` (unless set to `null`, as they can only be strings)
-        locally or on remote homeservers.
+        plus any custom profile fields.
+
+        **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -243,45 +287,49 @@ paths:
                 properties:
                   avatar_url:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
+                    description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
-                    description: The user's display name if they have set one, otherwise not
+                additionalProperties:
-                      present.
+                  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).
               examples:
                 response:
-                  value: {
+                  value:
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                    {
-                    "displayname": "Alice Margatroid"
+                      "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
-            has profile information.
+            exists and/or has profile information.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_FORBIDDEN",
+                    {
-                    "error": "Profile lookup is disabled on this homeserver"
+                      "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
-            exist.
+            user does not exist.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_NOT_FOUND",
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
-                    "error": "Profile not found"
-                  }
       tags:
         - User data
 servers:

data/api/client-server/room_summary.yaml

@@ -89,11 +89,6 @@ paths:
                           - leave
                           - ban
                         type: string
-                required:
-                  - guest_can_join
-                  - num_joined_members
-                  - room_id
-                  - world_readable
               examples:
                 response:
                   value: {

data/event-schemas/schema/core-event-schema/room_event.yaml

@@ -1,13 +1,13 @@
+title: RoomEvent
+description: Room Events have the following fields.
 allOf:
 - $ref: sync_room_event.yaml
-description: Room Events have the following fields.
+- type: object
-properties:
+  properties:
-  room_id:
+    room_id:
-    description: |-
+      description: |-
-      The ID of the room associated with this event. Will not be present on events
+        The ID of the room associated with this event. Will not be present on events
-      that arrive through `/sync`, despite being required everywhere else.
+        that arrive through `/sync`, despite being required everywhere else.
-    type: string
+      type: string
-required:
+  required:
-- room_id
+  - room_id
-title: RoomEvent
-type: object

data/event-schemas/schema/core-event-schema/sync_room_event.yaml

@@ -17,27 +17,27 @@
 # be on events, so we give it a whole event structure as a base for room_event.
 # This base doesn't declare a room_id, which instead appears in the room_event.
 
-allOf:
+title: SyncRoomEvent
-- $ref: event.yaml
 description: In addition to the Event fields, Room Events have the following additional
   fields.
-properties:
+allOf:
-  event_id:
+- $ref: event.yaml
-    description: The globally unique event identifier.
+- type: object
-    type: string
+  properties:
-  sender:
+    event_id:
-    description: Contains the fully-qualified ID of the user who sent this event.
+      description: The globally unique event identifier.
-    type: string
+      type: string
-  origin_server_ts:
+    sender:
-    description: Timestamp in milliseconds on originating homeserver
+      description: Contains the fully-qualified ID of the user who sent this event.
-      when this event was sent.
+      type: string
-    type: integer
+    origin_server_ts:
-    format: int64
+      description: Timestamp in milliseconds on originating homeserver
-  unsigned:
+        when this event was sent.
-    $ref: unsigned_prop.yaml
+      type: integer
-required:
+      format: int64
-- event_id
+    unsigned:
-- sender
+      $ref: unsigned_prop.yaml
-- origin_server_ts
+  required:
-title: SyncRoomEvent
+  - event_id
-type: object
+  - sender
+  - origin_server_ts

data/event-schemas/schema/core-event-schema/sync_state_event.yaml

@@ -14,21 +14,21 @@
 
 # See sync_room_event.yaml for why this file is here.
 
-allOf:
+title: SyncStateEvent
-- $ref: sync_room_event.yaml
 description: In addition to the Room Event fields, State Events have the following
   additional fields.
-properties:
+allOf:
-  state_key:
+- $ref: sync_room_event.yaml
-    description: A unique key which defines the overwriting semantics for this piece
+- type: object
-      of room state. This value is often a zero-length string. The presence of this
+  properties:
-      key makes this event a State Event.
+    state_key:
+      description: A unique key which defines the overwriting semantics for this piece
+        of room state. This value is often a zero-length string. The presence of this
+        key makes this event a State Event.
 
-      State keys starting with an `@` are reserved for referencing user IDs, such
+        State keys starting with an `@` are reserved for referencing user IDs, such
-      as room members. With the exception of a few events, state events set with a
+        as room members. With the exception of a few events, state events set with a
-      given user's ID as the state key MUST only be set by that user.
+        given user's ID as the state key MUST only be set by that user.
-    type: string
+      type: string
-required:
+  required:
-- state_key
+  - state_key
-title: SyncStateEvent
-type: object