Merge 6183f2410f into 817ec5380f

Create funding-manifest-urls (#2115 )
* Create funding-manifest-urls * update funding-manifest-urls location, add news Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --------- Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>
2026-04-13 14:44:10 +02:00 · 2025-03-28 14:09:10 +00:00 · 2025-03-28 13:19:23 +00:00 · 2025-03-27 10:30:02 -06:00 · 2025-03-27 10:28:55 -06:00 · 2025-03-27 10:23:09 -06:00
52 changed files with 408 additions and 192 deletions
--- a/changelogs/appendices/newsfragments/1506.clarification
+++ b/changelogs/appendices/newsfragments/1506.clarification
@ -1 +0,0 @@
-Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.
--- a/changelogs/client_server/newsfragments/2036.clarification
+++ b/changelogs/client_server/newsfragments/2036.clarification
@ -1 +0,0 @@
-The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.
--- a/changelogs/client_server/newsfragments/2038.clarification
+++ b/changelogs/client_server/newsfragments/2038.clarification
@ -1 +0,0 @@
-Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.
--- a/changelogs/client_server/newsfragments/2046.clarification
+++ b/changelogs/client_server/newsfragments/2046.clarification
@ -1 +0,0 @@
-Clarify formats of string types.
--- a/changelogs/client_server/newsfragments/2047.clarification
+++ b/changelogs/client_server/newsfragments/2047.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2048.clarification
+++ b/changelogs/client_server/newsfragments/2048.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2051.clarification
+++ b/changelogs/client_server/newsfragments/2051.clarification
@ -1 +0,0 @@
-Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.
--- a/changelogs/client_server/newsfragments/2055.clarification
+++ b/changelogs/client_server/newsfragments/2055.clarification
@ -1 +0,0 @@
-Applying redactions is a SHOULD for clients.
--- a/changelogs/client_server/newsfragments/2059.removal
+++ b/changelogs/client_server/newsfragments/2059.removal
@ -1 +0,0 @@
-Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).
--- a/changelogs/client_server/newsfragments/2064.clarification
+++ b/changelogs/client_server/newsfragments/2064.clarification
@ -1 +0,0 @@
-Clarify which rooms are returned from `/hierarchy`.
--- a/changelogs/client_server/newsfragments/2071.feature
+++ b/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.
--- a/changelogs/client_server/newsfragments/2072.clarification
+++ b/changelogs/client_server/newsfragments/2072.clarification
@ -1 +0,0 @@
-Clients can choose which history visibility options they offer to users when creating rooms.
--- a/changelogs/client_server/newsfragments/2080.clarification
+++ b/changelogs/client_server/newsfragments/2080.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2091.clarification
+++ b/changelogs/client_server/newsfragments/2091.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2093.new
+++ b/changelogs/client_server/newsfragments/2093.new
@ -1 +0,0 @@
-Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260).
--- a/changelogs/internal/newsfragments/2033.clarification
+++ b/changelogs/internal/newsfragments/2033.clarification
@ -1 +0,0 @@
-Generate the changelog release info with Hugo, rather than the changelog generation script.
--- a/changelogs/internal/newsfragments/2041.clarification
+++ b/changelogs/internal/newsfragments/2041.clarification
@ -1 +0,0 @@
-Update release steps documentation.
--- a/changelogs/internal/newsfragments/2042.clarification
+++ b/changelogs/internal/newsfragments/2042.clarification
@ -1 +0,0 @@
-Remove unused `release_date` from Hugo config.
--- a/changelogs/internal/newsfragments/2045.clarification
+++ b/changelogs/internal/newsfragments/2045.clarification
@ -1 +0,0 @@
-Clarify that v1.0 of Matrix was a release prior to the current global versioning system.
--- a/changelogs/internal/newsfragments/2049.clarification
+++ b/changelogs/internal/newsfragments/2049.clarification
@ -1 +0,0 @@
-Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.
--- a/changelogs/internal/newsfragments/2061.clarification
+++ b/changelogs/internal/newsfragments/2061.clarification
@ -1 +0,0 @@
-Fix the version of the Identity Service API when Matrix 1.0 was introduced.
--- a/changelogs/internal/newsfragments/2069.clarification
+++ b/changelogs/internal/newsfragments/2069.clarification
@ -1 +0,0 @@
-Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials.
--- a/changelogs/internal/newsfragments/2073.clarification
+++ b/changelogs/internal/newsfragments/2073.clarification
@ -1 +0,0 @@
-Deduplicate the definition of `RoomKeysUpdateResponse`.
--- a/changelogs/internal/newsfragments/2074.clarification
+++ b/changelogs/internal/newsfragments/2074.clarification
@ -1 +0,0 @@
-Deduplicate the definitions of `Invite3pid`.
--- a/changelogs/internal/newsfragments/2076.clarification
+++ b/changelogs/internal/newsfragments/2076.clarification
@ -1 +0,0 @@
-Support more locations for examples in OpenAPI definitions and JSON schemas.
--- a/changelogs/internal/newsfragments/2078.clarification
+++ b/changelogs/internal/newsfragments/2078.clarification
@ -1 +0,0 @@
-Add link to the git commit for the unstable changelog.
--- a/changelogs/internal/newsfragments/2115.clarification
+++ b/changelogs/internal/newsfragments/2115.clarification
@ -0,0 +1 @@
+Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.
--- a/changelogs/room_versions/newsfragments/2065.clarification
+++ b/changelogs/room_versions/newsfragments/2065.clarification
@ -1 +0,0 @@
-For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions.
--- a/changelogs/room_versions/newsfragments/2066.clarification
+++ b/changelogs/room_versions/newsfragments/2066.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/room_versions/newsfragments/2070.clarification
+++ b/changelogs/room_versions/newsfragments/2070.clarification
@ -1 +0,0 @@
-Refactor PDU definitions to reduce duplication.
--- a/changelogs/room_versions/newsfragments/2105.feature
+++ b/changelogs/room_versions/newsfragments/2105.feature
@ -1 +0,0 @@
-Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239).
--- a/changelogs/server_server/newsfragments/2050.clarification
+++ b/changelogs/server_server/newsfragments/2050.clarification
@ -1 +0,0 @@
-Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.
--- a/changelogs/server_server/newsfragments/2063.clarification
+++ b/changelogs/server_server/newsfragments/2063.clarification
@ -1 +0,0 @@
-Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`.
--- a/changelogs/server_server/newsfragments/2076.clarification
+++ b/changelogs/server_server/newsfragments/2076.clarification
@ -1 +0,0 @@
-Remove an erroneous `room_id` field in a few examples.
--- a/config/_default/hugo.toml
+++ b/config/_default/hugo.toml
@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 # major = "1"
-# minor = "13"
+# minor = "14"

 # User interface configuration
 [params.ui]
--- a/content/changelog/v1.14.md
+++ b/content/changelog/v1.14.md
@ -0,0 +1,93 @@
+---
+title: v1.14 Changelog
+linkTitle: v1.14
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-03-27
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
+
+**Removed Endpoints**
+
+- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
+
+**Spec Clarifications**
+
+- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
+- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
+- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
+- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
+- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
+- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
+- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
+- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
+
+
+## Server-Server API
+
+**Spec Clarifications**
+
+- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
+- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
+- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
+
+**Spec Clarifications**
+
+- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
+- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
+- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
+- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
+- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
+- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
+- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
+- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
+- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
+- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
+- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
+- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
+- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
+- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))
--- a/content/client-server-api/modules/guest_access.md
+++ b/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)
--- a/content/rooms/fragments/v6-event-format.md
+++ b/content/rooms/fragments/v6-event-format.md
@ -0,0 +1,4 @@
+
+Events in rooms of this version have the following structure:
+
+{{% definition path="api/server-server/definitions/pdu_v6" %}}
--- a/content/rooms/v10.md
+++ b/content/rooms/v10.md
@ -281,7 +281,7 @@ completeness.

 ### Event format

-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}

 ### State resolution

--- a/content/rooms/v6.md
+++ b/content/rooms/v6.md
@ -39,6 +39,13 @@ in [room version 5](/rooms/v5).

 [See above](#redactions).

+### Event format
+
+{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
+the `depth` limit has been reduced in this room version.
+
+{{% rver-fragment name="v6-event-format" %}}
+
 ### Authorization rules

 {{% added-in v=6 %}} Rule 4, which related specifically to events
@ -229,10 +236,6 @@ completeness.

 {{% rver-fragment name="v4-event-ids" %}}

-### Event format
-
-{{% rver-fragment name="v4-event-format" %}}
-
 #### Deprecated event content schemas

 {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}
--- a/content/rooms/v7.md
+++ b/content/rooms/v7.md
@ -225,7 +225,7 @@ completeness.

 ### Event format

-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}

 #### Deprecated event content schemas

--- a/content/rooms/v8.md
+++ b/content/rooms/v8.md
@ -109,7 +109,7 @@ completeness.

 ### Event format

-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}

 #### Deprecated event content schemas

--- a/content/rooms/v9.md
+++ b/content/rooms/v9.md
@ -74,7 +74,7 @@ completeness.

 ### Event format

-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}

 #### Deprecated event content schemas

--- a/data/api/client-server/capabilities.yaml
+++ b/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.
+                          Please 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.
+                          Please 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,37 @@ 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.
+                          If absent, clients should assume custom profile fields are supported.
+                        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: {
--- a/data/api/client-server/profile.yaml
+++ b/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 this user's display name, e.g. you need to have their `access_token`.
-      operationId: setDisplayName
+        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.
+      operationId: setProfileField
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: userId
-          description: The user whose display name to set.
+          description: The user whose profile field to 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: {
-                "displayname": "Alice Margatroid"
-              }
-              properties:
-                displayname:
-                  type: string
-                  description: The new display name for this user.
-        description: The new display name information.
-        required: true
+              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.
+              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.
-      description: |-
-        Get the user's display name. This API may be used to fetch the user's
-        own displayname or to query the name of other users; either locally or
-        on remote homeservers.
-      operationId: getDisplayName
+      x-changedInMatrixVersion:
+        "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. Any individual
+        field must be within the total profile limit of 64 KiB.
+      operationId: getProfileField
      parameters:
        - in: path
          name: userId
-          description: The user whose display name to get.
+          description: The user whose profile field to get.
          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:
-                  displayname:
-                    type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
+                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.
              examples:
                response:
-                  value: {
-                    "displayname": "Alice Margatroid"
-                  }
+                  value: { "displayname": "Alice" }
        "403":
          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has a display name.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has the specified profile field.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "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":
-    put:
-      summary: Set the user's avatar URL.
-      description: |-
-        This API sets the given user's avatar URL. You must have permission to
-        set this user's avatar URL, e.g. you need to have their `access_token`.
-      operationId: setAvatarUrl
+    delete:
+      x-addedInMatrixVersion: "1.14"
+      summary: Remove a profile field from a user.
+      description: Remove a specific field from a user's profile.
+      operationId: deleteProfileField
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      parameters:
        - in: path
          name: userId
-          description: The user whose avatar URL to set.
+          description: The user whose profile field to delete.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example: {
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
-              }
-              properties:
-                avatar_url:
-                  type: string
-                  format: uri
-                  description: The new avatar URL for this user.
-        description: The new avatar information.
-        required: true
+        - in: path
+          name: keyName
+          description: The profile field key name to delete. 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 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
-        to fetch the user's own profile information or other users; either
-        locally or on remote homeservers.
+        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
@ -243,45 +287,49 @@ paths:
                properties:
                  avatar_url:
                    type: string
-                    format: uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
+                    format: mx-mxc-uri
+                    description: "Avatar URL value (MXC URI format)."
                  displayname:
                    type: string
-                    description: The user's display name if they have set one, otherwise not
-                      present.
+                additionalProperties:
+                  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: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                    "displayname": "Alice Margatroid"
-                  }
+                  value:
+                    {
+                      "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
-            has profile information.
+          description: The server is unwilling to disclose whether the user
+            exists and/or has profile information.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
+                  value:
+                    {
+                      "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
-            exist.
+          description: There is no profile information for this user or this
+            user does not exist.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
-                  value: {
-                    "errcode": "M_NOT_FOUND",
-                    "error": "Profile not found"
-                  }
+                  value:
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
      tags:
        - User data
 servers:
--- a/data/api/server-server/definitions/components/pdu_base.yaml
+++ b/data/api/server-server/definitions/components/pdu_base.yaml
@ -41,13 +41,6 @@ properties:
    type: object
    description: The content of the event.
    example: {"key": "value"}
-  depth:
-    type: integer
-    description: |-
-      The maximum depth of the `prev_events`, plus one. Must be less than the
-      maximum value for an integer (2^63 - 1). If the room's depth is already at
-      the limit, the depth must be set to the limit.
-    example: 12
  hashes:
    $ref: "event_hash.yaml"
  signatures:
--- a/data/api/server-server/definitions/pdu_v1.yaml
+++ b/data/api/server-server/definitions/pdu_v1.yaml
@ -28,6 +28,13 @@ allOf:
        type: string
        description: For redaction events, the ID of the event being redacted.
        example: "$def456:matrix.org"
+      depth:
+        type: integer
+        description: |-
+          The maximum depth of the `prev_events`, plus one. Must be less than the
+          maximum value for an integer (2^63 - 1). If the room's depth is already at
+          the limit, the depth must be set to the limit.
+        example: 12
      auth_events:
        type: array
        description: |-
--- a/data/api/server-server/definitions/pdu_v11.yaml
+++ b/data/api/server-server/definitions/pdu_v11.yaml
@ -17,6 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
 example:
  $ref: "../examples/pdu_v11.json"
 allOf:
-  # v11 is the v4 event, but without redacts.
+  # v11 is the v6 event, but without redacts.
  - $ref: "components/pdu_base.yaml"
-  - $ref: "components/auth_events_prev_events_v4.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"
+  - type: object
+    properties:
+      # v6 enforces Canonical JSON and therefore needs a depth limit change
+      depth:
+        type: integer
+        description: |-
+          The maximum depth of the `prev_events`, plus one. Must be less than the
+          maximum value for an integer (2^53 - 1). If the room's depth is already at
+          the limit, the depth must be set to the limit.
+        example: 12
--- a/data/api/server-server/definitions/pdu_v3.yaml
+++ b/data/api/server-server/definitions/pdu_v3.yaml
@ -24,6 +24,13 @@ allOf:
        type: string
        description: For redaction events, the ID of the event being redacted.
        example: "$def/456+oldevent"
+      depth:
+        type: integer
+        description: |-
+          The maximum depth of the `prev_events`, plus one. Must be less than the
+          maximum value for an integer (2^63 - 1). If the room's depth is already at
+          the limit, the depth must be set to the limit.
+        example: 12
      auth_events:
        type: array
        items:
--- a/data/api/server-server/definitions/pdu_v4.yaml
+++ b/data/api/server-server/definitions/pdu_v4.yaml
@ -26,3 +26,10 @@ allOf:
        type: string
        description: For redaction events, the ID of the event being redacted.
        example: "$def_456-oldevent"
+      depth:
+        type: integer
+        description: |-
+          The maximum depth of the `prev_events`, plus one. Must be less than the
+          maximum value for an integer (2^63 - 1). If the room's depth is already at
+          the limit, the depth must be set to the limit.
+        example: 12
--- a/data/api/server-server/definitions/pdu_v6.yaml
+++ b/data/api/server-server/definitions/pdu_v6.yaml
@ -0,0 +1,36 @@
+# Copyright 2025 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Persistent Data Unit
+description: |-
+  A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
+example:
+  $ref: "../examples/pdu_v4.json"
+allOf:
+  - $ref: "components/pdu_base.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"
+  - type: object
+    properties:
+      redacts:
+        type: string
+        description: For redaction events, the ID of the event being redacted.
+        example: "$def_456-oldevent"
+      # v6 enforces Canonical JSON and therefore needs a depth limit change
+      depth:
+        type: integer
+        description: |-
+          The maximum depth of the `prev_events`, plus one. Must be less than the
+          maximum value for an integer (2^53 - 1). If the room's depth is already at
+          the limit, the depth must be set to the limit.
+        example: 12
--- a/static/.well-known/funding-manifest-urls
+++ b/static/.well-known/funding-manifest-urls
@ -0,0 +1 @@
+https://matrix.org/funding.json
Author	SHA1	Message	Date
Tom Foster	1337671ee6	Merge `6183f2410f` into `817ec5380f`	2025-03-28 14:09:10 +00:00
Kim Brose	817ec5380f	Create funding-manifest-urls (#2115 ) * Create funding-manifest-urls * update funding-manifest-urls location, add news Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --------- Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>	2025-03-28 13:19:23 +00:00
Travis Ralston	029be205b9	-> unstable Some checks are pending Spec / 🔎 Validate OpenAPI specifications (push) Waiting to run Details Spec / 🔎 Check Event schema examples (push) Waiting to run Details Spec / 🔎 Check OpenAPI definitions examples (push) Waiting to run Details Spec / 🔎 Check JSON Schemas inline examples (push) Waiting to run Details Spec / ⚙️ Calculate baseURL for later jobs (push) Waiting to run Details Spec / 🐍 Build OpenAPI definitions (push) Blocked by required conditions Details Spec / 📢 Run towncrier for changelog (push) Waiting to run Details Spec / 📖 Build the spec (push) Blocked by required conditions Details Spec / 🔎 Validate generated HTML (push) Blocked by required conditions Details Spec / 📖 Build the historical backup spec (push) Blocked by required conditions Details Spell Check / Spell Check with Typos (push) Waiting to run Details	2025-03-27 10:30:02 -06:00
Travis Ralston	fe880fdaf4	v1.14	2025-03-27 10:28:55 -06:00
Travis Ralston	71ce620fc0	Add a v6 event format with correct `depth` limits (#2114 ) * Add a v6 event format with correct `depth` limits * Changelog * numbers are hard	2025-03-27 10:23:09 -06:00
Tom Foster	6183f2410f	Clarify value validation requirements	2025-02-21 10:32:28 +00:00
Tom Foster	dd4ea948b6	Clarify why `avatar_url` and `displayname` can't be returned as `null`	2025-02-21 09:53:43 +00:00
Tom Foster	50eab3501e	Standardise line-wrapping and update `avatar_url` format to `mx-mxc-uri`	2025-02-21 09:28:46 +00:00
Tom Foster	37b1362bc1	Attempt to describe variable payload content	2025-02-20 18:08:10 +00:00
Tom Foster	d8cc250d20	Tag `x-addedInMatrixVersion` on `additionalProperties` in entire profile `GET`	2025-02-20 17:02:23 +00:00
Tom Foster	b5e2edf2e5	Add `x-addedInMatrixVersion`	2025-02-20 16:59:44 +00:00
Tom Foster	7ef1d9d0ec	Add `x-changedInMatrixVersion`	2025-02-20 16:56:53 +00:00
Tom Foster	3a5e5555fa	Correct `PUT`/`GET` payload definitions	2025-02-20 16:48:20 +00:00
Tom Foster	9889fe3584	Use more accessible terminology than "glob"	2025-02-20 16:40:07 +00:00
Tom Foster	013502b0c0	Mention replacement for `m.set_displayname` and `m.set_avatar_url` capability deprecation	2025-02-20 16:35:26 +00:00
Tom Foster	9859e20927	Don't use reference for capability.	2025-02-20 16:31:27 +00:00
Tom Foster	7a3b0c0804	Clarify in change log that `m.set_avatar_url` and `m.set_displayname` capabilities are now deprecated	2025-02-14 15:03:17 +00:00
Tom Foster	0b0942d192	Clarify capability lists should support wildcards	2025-02-14 15:00:53 +00:00
Tom Foster	1cc93ec951	Attempt to make descriptions look better in HTML rendered spec	2025-02-14 14:53:29 +00:00
Tom Foster	79af78022e	Camel case for endpoint variables	2025-02-14 13:47:49 +00:00
Tom Foster	17af55ddce	Fix broken link	2025-02-14 13:30:33 +00:00
Tom Foster	79a1cded02	Remove reference to spec version in `m.profile_field` capability	2025-02-14 12:57:51 +00:00
Tom Foster	76b48e25d0	Specify CNIG pattern for custom fields	2025-02-14 12:56:16 +00:00
Tom Foster	5d5b561140	Deprecate `m.set_displayname` and `m.set_avatar_url` capabilities	2025-02-14 12:47:14 +00:00
Tom Foster	9327793007	Inline information from MSC4133, remove links	2025-02-14 12:39:19 +00:00
Tom Foster	f3c269d951	Added capability	2025-02-14 12:20:25 +00:00
Tom Foster	3311b084bf	Alphabetise `avatar_url` and `displayname` and remove redundant descriptions on `displayname`	2025-02-14 12:03:49 +00:00
Tom Foster	992cf9dc35	Clarify `null` behaviour for `PUT` and `DELETE`	2025-02-14 11:53:19 +00:00
Tom Foster	4f8999be0a	Tweak wording on full profile `GET`	2025-02-14 11:32:39 +00:00
Tom Foster	82adcec491	Clarify `avatar_url` should be MXC	2025-02-14 11:21:45 +00:00
Tom Foster	41c64c877b	Linkify MSC4133 in change log	2025-02-14 11:16:40 +00:00
Tom Foster	8e9874ad22	Simplify change log	2025-02-14 11:15:00 +00:00
Tom Foster	ee9b5ddcca	Correct types and errors	2025-02-14 11:02:11 +00:00
Tom Foster	59d2c62d2d	Link to MSC4133 in endpoint descriptions	2025-02-14 10:40:09 +00:00
Tom Foster	b2e122f308	Update changelog from `clarification` to `feature`	2025-02-14 10:12:29 +00:00
Tom Foster	1fc01189f3	2071 change log	2025-02-14 09:59:22 +00:00
Tom Foster	212377e393	Merge branch 'matrix-org:main' into MSC4133	2025-02-14 09:50:59 +00:00
Tom Foster	fdc012ac01	Describe MSC4133 profile endpoint changes	2025-02-13 17:54:21 +00:00
				`@ -1 +0,0 @@`
				`Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.`
				`@ -1 +0,0 @@`
				The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.
				`@ -1 +0,0 @@`
				Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.
				`@ -1 +0,0 @@`
				`Fix various typos throughout the specification.`
				`@ -1 +0,0 @@`
				Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.
				`@ -1 +0,0 @@`
				`Applying redactions is a SHOULD for clients.`
				`@ -1 +0,0 @@`
				Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).
				`@ -1 +0,0 @@`
				Clarify which rooms are returned from `/hierarchy`.
				`@ -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.