Merge upstream main into MSC4133

.github/workflows/main.yml

@@ -2,6 +2,7 @@ name: "Spec"
 
 env:
   HUGO_VERSION: 0.139.0
+  PYTHON_VERSION: 3.13
 
 on:
   push:
@@ -40,7 +41,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -59,7 +60,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -78,7 +79,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -120,7 +121,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -154,6 +155,11 @@ jobs:
               --api server-server \
               -r "$RELEASE" \
               -o spec/server-server-api/api.json
+          scripts/dump-openapi.py \
+              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
+              --api identity \
+              -r "$RELEASE" \
+              -o spec/identity-service-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v4
@@ -172,7 +178,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
@@ -283,10 +289,11 @@ jobs:
           npm i
           npm run get-proposals
       - name: "⚙️ hugo"
+        env:
+          HUGO_PARAMS_VERSION_STATUS: "historical"
         # Create a baseURL like `/v1.2` out of the `v1.2` tag
         run: |
-          echo -e '[params.version]\nstatus="historical"' > historical.toml
+          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
-          hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
         uses: actions/download-artifact@v4

assets/scss/_styles_project.scss

@@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 3rem 0 .5rem 0;
+    margin: 1.5rem 0 1rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 .75rem 0;
+    margin: 1.5rem 0 1rem 0;
+
+  }
+
+  /* Reduce top margin of h3 if previous sibling is a h2 */
+  h2 + h3 {
+    margin-top: 1rem;
   }
 
   hr {
@@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec
       }
     }
 
-    // add some space between two tables when they are right next to each other
-    & + table {
-        margin-top: 4rem;
-    }
-
     caption {
       caption-side: top;
       color: $dark;
@@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec
     }
   }
 
+  /* Have consistent spacing around tables and examples */
+  table, .highlight {
+    margin-top: 0;
+    margin-bottom: 2rem;
+
+    /* We don't need the margin on the last child of the .rendered-data block */
+    &:last-child {
+      margin-bottom: 0;
+    } 
+  }
+
   pre {
     border: 0;
     border-left: solid 5px $secondary;

changelogs/appendices/newsfragments/1506.clarification

@@ -1 +0,0 @@
-Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.

changelogs/application_service/newsfragments/2182.clarification

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

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.

changelogs/client_server/newsfragments/2038.clarification

@@ -1 +0,0 @@
-Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2046.clarification

@@ -1 +0,0 @@
-Clarify formats of string types.

changelogs/client_server/newsfragments/2051.clarification

@@ -1,2 +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}`.

changelogs/client_server/newsfragments/2055.clarification

@@ -1 +0,0 @@
-Applying redactions is a SHOULD for clients.

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).

changelogs/client_server/newsfragments/2167.clarification

@@ -0,0 +1 @@
+Clarify that `format` is required if `formatted_body` is specified.

changelogs/client_server/newsfragments/2169.clarification

@@ -0,0 +1 @@
+The `latest_event` in an aggregated set of thread events uses the same format as the event itself.

changelogs/client_server/newsfragments/2175.feature

@@ -0,0 +1 @@
+Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event.

changelogs/client_server/newsfragments/2182.clarification

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

changelogs/internal/newsfragments/2033.clarification

@@ -1 +0,0 @@
-Generate the changelog release info with Hugo, rather than the changelog generation script.

changelogs/internal/newsfragments/2041.clarification

@@ -1 +0,0 @@
-Update release steps documentation.

changelogs/internal/newsfragments/2042.clarification

@@ -1 +0,0 @@
-Remove unused `release_date` from Hugo config.

changelogs/internal/newsfragments/2045.clarification

@@ -1 +0,0 @@
-Clarify that v1.0 of Matrix was a release prior to the current global versioning system.

changelogs/internal/newsfragments/2049.clarification

@@ -1 +0,0 @@
-Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.

changelogs/internal/newsfragments/2061.clarification

@@ -1 +0,0 @@
-Fix the version of the Identity Service API when Matrix 1.0 was introduced.

changelogs/internal/newsfragments/2157.feature

@@ -0,0 +1 @@
+Add "placeholder MSC" process definition.

changelogs/internal/newsfragments/2172.clarification

@@ -0,0 +1 @@
+GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file.

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.

config/_default/hugo.toml

@@ -23,15 +23,15 @@ description = "Home of the Matrix specification for decentralised communication"
 [menus]
 [[menus.main]]
     name = 'Foundation'
-    url = 'https://matrix.org/foundation/'
+    url = 'https://matrix.org/foundation/about/'
     weight = 10
 [[menus.main]]
-    name = 'FAQs'
+    name = 'User Docs'
-    url = 'https://matrix.org/faq'
+    url = 'https://matrix.org/docs/'
     weight = 20
 [[menus.main]]
     name = 'Blog'
-    url = 'https://matrix.org/blog/posts'
+    url = 'https://matrix.org/blog/'
     weight = 30
 
 [markup]
@@ -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 = "15"
 
 # User interface configuration
 [params.ui]

content/application-service-api.md

@@ -492,10 +492,10 @@ via the query string). It is expected that the application service use
 the transactions pushed to it to handle events rather than syncing with
 the user implied by `sender_localpart`.
 
-#### Application service room directories
+#### Published room directories
 
-Application services can maintain their own room directories for their
+Application services can maintain their own published room directories for
-defined third-party protocols. These room directories may be accessed by
+their defined third-party protocols. These directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 

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))

content/changelog/v1.15.md

@@ -0,0 +1,97 @@
+---
+title: v1.15 Changelog
+linkTitle: v1.15
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-06-26
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+- Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). ([#2147](https://github.com/matrix-org/matrix-spec/issues/2147))
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147). ([#2122](https://github.com/matrix-org/matrix-spec/issues/2122))
+- Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125), [#2158](https://github.com/matrix-org/matrix-spec/issues/2158))
+- Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals. ([#2141](https://github.com/matrix-org/matrix-spec/issues/2141), [#2148](https://github.com/matrix-org/matrix-spec/issues/2148), [#2149](https://github.com/matrix-org/matrix-spec/issues/2149), [#2150](https://github.com/matrix-org/matrix-spec/issues/2150), [#2151](https://github.com/matrix-org/matrix-spec/issues/2151), [#2159](https://github.com/matrix-org/matrix-spec/issues/2159), [#2164](https://github.com/matrix-org/matrix-spec/issues/2164))
+
+**Spec Clarifications**
+
+- Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. ([#2068](https://github.com/matrix-org/matrix-spec/issues/2068))
+- Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. ([#2077](https://github.com/matrix-org/matrix-spec/issues/2077))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- "Public" rooms in profile look-ups are defined through their join rule and history visibility. ([#2101](https://github.com/matrix-org/matrix-spec/issues/2101))
+- "Public" rooms in user directory queries are defined through their join rule and history visibility. ([#2102](https://github.com/matrix-org/matrix-spec/issues/2102))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- "Public" rooms with respect to call invites are defined through their join rule. ([#2106](https://github.com/matrix-org/matrix-spec/issues/2106))
+- "Public" rooms have no specific meaning with respect to moderation policy lists. ([#2107](https://github.com/matrix-org/matrix-spec/issues/2107))
+- "Public" rooms with respect to presence are defined through their join rule. ([#2108](https://github.com/matrix-org/matrix-spec/issues/2108))
+- Spaces are subject to the same access mechanisms as rooms. ([#2109](https://github.com/matrix-org/matrix-spec/issues/2109))
+- Fix various typos throughout the specification. ([#2121](https://github.com/matrix-org/matrix-spec/issues/2121), [#2144](https://github.com/matrix-org/matrix-spec/issues/2144))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+- Add missing fields in example for `ExportedSessionData`. ([#2154](https://github.com/matrix-org/matrix-spec/issues/2154))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+
+**Spec Clarifications**
+
+- Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room. ([#2067](https://github.com/matrix-org/matrix-spec/issues/2067))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`. ([#2100](https://github.com/matrix-org/matrix-spec/issues/2100))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- Fix various typos throughout the specification. ([#2128](https://github.com/matrix-org/matrix-spec/issues/2128))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify in the application service registration schema the `url: null` behaviour. ([#2130](https://github.com/matrix-org/matrix-spec/issues/2130))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify that public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Adjust margins in rendered endpoints. ([#2081](https://github.com/matrix-org/matrix-spec/issues/2081))
+- Replace Hugo shortcodes in OpenAPI output. ([#2088](https://github.com/matrix-org/matrix-spec/issues/2088))
+- Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. ([#2115](https://github.com/matrix-org/matrix-spec/issues/2115))
+- Fix the historical info box when generating the historical spec in CI. ([#2123](https://github.com/matrix-org/matrix-spec/issues/2123))
+- Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks. ([#2137](https://github.com/matrix-org/matrix-spec/issues/2137))

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

@@ -528,7 +528,7 @@ messages, Alice only sends one request event (an event with type
 `m.room.message` with `msgtype: m.key.verification.request`, rather than an
 event with type `m.key.verification.request`), to the room. In addition, Alice
 does not send an `m.key.verification.cancel` event to tell Bob's other devices
-that the request as already been accepted; instead, when Bob's other devices
+that the request has already been accepted; instead, when Bob's other devices
 see his `m.key.verification.ready` event, they will know that the request has
 already been accepted, and that they should ignore the request.
 
@@ -1124,7 +1124,7 @@ The process between Alice and Bob verifying each other would be:
    framework as described above.
 3. Alice's client displays a QR code that Bob is able to scan if Bob's client
    indicated the ability to scan, an option to scan Bob's QR code if her client
-   is able to scan.  Bob's client prompts displays a QR code that Alice can
+   is able to scan. Bob's client displays a QR code that Alice can
    scan if Alice's client indicated the ability to scan, and an option to scan
    Alice's QR code if his client is able to scan. The format for the QR code
    is described below. Other options, like starting SAS Emoji verification,
@@ -1512,40 +1512,11 @@ message.
 
 The plaintext payload is of the form:
 
-```json
+{{% definition path="api/client-server/definitions/olm_payload" %}}
-{
-  "type": "<type of the plaintext event>",
-  "content": "<content for the plaintext event>",
-  "sender": "<sender_user_id>",
-  "recipient": "<recipient_user_id>",
-  "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
-  },
-  "keys": {
-    "ed25519": "<sender_ed25519_key>"
-  }
-}
-```
 
 The type and content of the plaintext message event are given in the
 payload.
 
-Other properties are included in order to prevent an attacker from
-publishing someone else's curve25519 keys as their own and subsequently
-claiming to have sent messages which they didn't. `sender` must
-correspond to the user who sent the event, `recipient` to the local
-user, and `recipient_keys` to the local ed25519 key.
-
-Clients must confirm that the `sender_key` property in the cleartext
-`m.room.encrypted` event body, and the `keys.ed25519` property in the
-decrypted plaintext, match the keys returned by
-[`/keys/query`](#post_matrixclientv3keysquery) for
-the given user. Clients must also verify the signature of the keys from the
-`/keys/query` response. Without this check, a client cannot be sure that
-the sender device owns the private part of the ed25519 key it claims to
-have in the Olm payload. This is crucial when the ed25519 key corresponds
-to a verified device.
-
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully
 decrypted a message. For these purposes, a session that has not received
@@ -1555,6 +1526,68 @@ maximum number of olm sessions that it will maintain for each device,
 and expiring sessions on a Least Recently Used basis. The maximum number
 of olm sessions maintained per device should be at least 4.
 
+###### Validation of incoming decrypted events
+
+{{% changed-in v="1.15" %}} Existing checks made more explicit, and checks for `sender_device_keys` added.
+
+After decrypting an incoming encrypted event, clients MUST apply the
+following checks:
+
+1.  The `sender` property in the decrypted content must match the
+    `sender` of the event.
+2.  The `keys.ed25519` property in the decrypted content must match
+    the `sender_key` property in the cleartext `m.room.encrypted`
+    event body.
+3.  The `recipient` property in the decrypted content must match
+    the user ID of the local user.
+4.  The `recipient_keys.ed25519` property in the decrypted content
+    must match the client device's [Ed25519 signing key](#device-keys).
+5.  Where `sender_device_keys` is present in the decrypted content:
+    1.  `sender_device_keys.user_id` must also match the `sender`
+        of the event.
+    2.  `sender_device_keys.keys.ed25519:<device_id>` must also match
+        the `sender_key` property in the cleartext `m.room.encrypted`
+        event body.
+    3.  `sender_device_keys.keys.curve25519:<device_id>` must match
+        the Curve25519 key used to establish the Olm session.
+    4.  The `sender_device_keys` structure must have a valid signature
+        from the key with ID `ed25519:<device_id>` (i.e., the sending
+        device's Ed25519 key).
+
+Any event that does not comply with these checks MUST be discarded.
+
+###### Verification of the sending user for incoming events
+
+{{% added-in v="1.15" %}}
+
+In addition, for each Olm session, clients MUST verify that the
+Curve25519 key used to establish the Olm session does indeed belong
+to the claimed `sender`. This requires a signed "device keys" structure
+for that Curve25519 key, which can be obtained in one of two ways:
+
+1.  An Olm message may be received with a `sender_device_keys` property
+    in the decrypted content.
+2.  The keys are returned via a [`/keys/query`](#post_matrixclientv3keysquery)
+    request. Note that both the Curve25519 key **and** the Ed25519 key in
+    the returned device keys structure must match those used in an
+    Olm-encrypted event as above. (In particular, the Ed25519 key must
+    be present in the **encrypted** content of an Olm-encrypted event
+    to prevent an attacker from claiming another user's Curve25519 key
+    as their own.)
+
+Ownership of the Curve25519 key is then established in one of two ways:
+
+1.  Via [cross-signing](#cross-signing). For this to be sufficient, the
+    device keys structure must be signed by the sender's self-signing key,
+    and that self-signing key must itself have been validated (either via
+    [explicit verification](#device-verification) or a "trust on first use" (TOFU) mechanism).
+2.  Via explicit verification of the device's Ed25519 signing key, as
+    contained in the device keys structure. This is no longer recommended.
+
+A failure to complete these verifications does not necessarily mean that
+the session is bogus; however it is the case that there is no proof that
+the claimed sender is accurate, and the user should be warned accordingly.
+
 ###### Recovering from undecryptable messages
 
 Occasionally messages may be undecryptable by clients due to a variety

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

@@ -364,7 +364,7 @@ property under `m.new_content`.
 
 A particular constraint applies to events which replace a [reply](#rich-replies):
 in contrast to the original reply, there should be no `m.in_reply_to` property
-in the the `m.relates_to` object, since it would be redundant (see
+in the `m.relates_to` object, since it would be redundant (see
 [Applying `m.new_content`](#applying-mnew_content) above, which notes that the
 original event's `m.relates_to` is preserved), as well as being contrary to the
 spirit of the event relationships mechanism which expects only one "parent" per

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

@@ -43,11 +43,8 @@ setting at that time was more restrictive.
 
 #### Client behaviour
 
-Clients that implement this module MUST present to the user the possible
+Clients may want to display a notice that events may be read by
-options for setting history visibility when creating a room.
+non-joined people if the history visibility is set to `world_readable`.
-
-Clients may want to display a notice that their events may be read by
-non-joined people if the value is set to `world_readable`.
 
 #### Server behaviour
 

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

@@ -18,8 +18,9 @@ the entity making the decisions on filtering is best positioned to
 interpret the rules how it sees fit.
 
 Moderation policy lists are stored as room state events. There are no
-restrictions on how the rooms can be configured (they could be public,
+restrictions on how the rooms can be configured in terms of
-private, encrypted, etc).
+[join rules](#mroomjoin_rules), [history visibility](#room-history-visibility),
+encryption, etc.
 
 There are currently 3 kinds of entities which can be affected by rules:
 `user`, `server`, and `room`. All 3 are described with

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

@@ -68,5 +68,7 @@ will cause the server to automatically set their presence to `online`.
 
 #### Security considerations
 
-Presence information is shared with all users who share a room with the
+Presence information is published to all users who share a room with the
-target user. In large public rooms this could be undesirable.
+target user. If the target user is a member of a room with a `public`
+[join rule](#mroomjoin_rules), any other user in the federation is
+able to gain access to the target user's presence. This could be undesirable.

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

@@ -29,3 +29,9 @@ is in before accepting a report.
 based on whether or not the reporting user is joined to the room. This is
 because users can be exposed to harmful content without being joined to a
 room. For instance, through room directories or invites.
+
+{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
+based on whether or not the reporting user is joined to any rooms that the
+reported user is joined to. This is because users can be exposed to harmful
+content without being joined to a room. For instance, through user
+directories or invites.

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

@@ -26,9 +26,10 @@ on certain keys of certain event types.
 
 The supported keys to search over are:
 
--   `content.body` in `m.room.message`
+-   `content.body` in [`m.room.message`](/client-server-api/#mroommessage)
--   `content.name` in `m.room.name`
+-   `content.name` in [`m.room.name`](/client-server-api/#mroomname)
--   `content.topic` in `m.room.topic`
+-   In [`m.room.topic`](/client-server-api/#mroomtopic), `content.topic`
+    as well as the `body` of the `text/plain` representation in `content['m.topic']`.
 
 The search will *not* include rooms that are end to end encrypted.
 

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

@@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise,
 clients will try to use the default key to decrypt secrets.
 
 Clients that want to present a simplified interface to users by not supporting
-multiple keys should use the default key if one is specified. If not default
+multiple keys should use the default key if one is specified. If no default
 key is specified, the client may behave as if there is no key is present at
 all. When such a client creates a key, it should mark that key as being the
 default key.

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

@@ -2,8 +2,8 @@
 
 {{% added-in v="1.2" %}}
 
-Often used to group rooms of similar subject matter (such as a public "Official
+Often used to group rooms of similar subject matter (such as an "Official
-matrix.org rooms" space or personal "Work stuff" space), spaces are a way to
+matrix.org rooms" space or a "Work stuff" space), spaces are a way to
 organise rooms while being represented as rooms themselves.
 
 A space is defined by the [`m.space` room type](#types), making it known as a
@@ -18,11 +18,11 @@ In the default power level structure, this would be `100`. Clients might wish to
 go a step further and explicitly ignore notification counts on space-rooms.
 
 Membership of a space is defined and controlled by the existing mechanisms which
-govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
+govern a room: [`m.room.member`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
-and [`m.room.join_rules`](#mroomjoin_rules). Public spaces are encouraged to have
+and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
-a similar setup to public rooms: `world_readable` history visibility, published
+third-party invites, still work just as they do in normal rooms as well. Furthermore,
-canonical alias, and suitably public `join_rule`. Invites, including third-party
+spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
-invites, still work just as they do in normal rooms as well.
+discoverable.
 
 All other aspects of regular rooms are additionally carried over, such as the
 ability to set arbitrary state events, hold room account data, etc. Spaces are
@@ -87,10 +87,9 @@ the state of `#space:example.org` would consist of:
 }
 ```
 
-No state events in the child rooms themselves would be required (though they
+No state events in the child rooms themselves would be required (though they can also
-can also be present). This allows for users
+be present). This allows for users to define spaces without needing explicit permission
-to define personal/private spaces to organise their own rooms without needing explicit
+from the room moderators/admins.
-permission from the room moderators/admins.
 
 Child rooms can be removed from a space by omitting the `via` key of `content` on the
 relevant state event, such as through redaction or otherwise clearing the `content`.

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

@@ -6,9 +6,10 @@ allow users to log into applications via a single web-based
 authentication portal. Examples include OpenID Connect, "Central
 Authentication Service" (CAS) and SAML.
 
-This module allows a Matrix homeserver to delegate user authentication
+This module allows a Matrix homeserver that supports the [legacy authentication
-to an external authentication server supporting one of these protocols.
+API](#legacy-api) to delegate user authentication to an external authentication
-In this process, there are three systems involved:
+server supporting one of these protocols. In this process, there are three
+systems involved:
 
 -   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
@@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix
 homeserver implementations might support different SSO protocols.
 
 Clients and homeservers implementing the SSO flow will need to consider
-both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
+both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
 similar in both cases, but there are slight differences.
 
 Typically, SSO systems require a single "callback" URI to be configured

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

@@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
 their Matrix user ID is not known, instead addressing them by a third-party
 identifier such as an email address. There are two flows here; one
 if a Matrix user ID is known for the third-party identifier, and one if
-not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the
+not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
-third-party identifier.
+with the details of the third-party identifier.
 
 The homeserver asks the identity server whether a Matrix user ID is
 known for that identifier:
@@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
 
 #### Server behaviour
 
-Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
+Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
-third-party identifier with the provided identity server. If the lookup
+the server is expected to look up the third-party identifier with the provided
-yields a result for a Matrix User ID then the normal invite process can
+identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
-be initiated. This process ends up looking like this:
+If the lookup yields a result for a Matrix User ID then the normal [invite
+process](/server-server-api/#inviting-to-a-room) can be initiated. This process
+ends up looking like this:
 
 ```
     +---------+                         +-------------+                                    +-----------------+
@@ -66,10 +68,11 @@ be initiated. This process ends up looking like this:
         |                                     |                                                    |
 ```
 
-However, if the lookup does not yield a bound User ID, the homeserver
+However, if the lookup does not yield a bound User ID, the homeserver must store
-must store the invite on the identity server and emit a valid
+the invite on the identity server with a call to
-`m.room.third_party_invite` event to the room. This process ends up
+[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
-looking like this:
+and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
+to the room. This process ends up looking like this:
 
 ```
     +---------+                         +-------------+                                               +-----------------+
@@ -101,15 +104,18 @@ looking like this:
         |                                     |                                                               |
 ```
 
-All homeservers MUST verify the signature in the event's
+The third-party user will then need to verify their identity, which results in a
-`content.third_party_invite.signed` object.
+request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
+from the identity server to the homeserver that bound the third-party identifier
+to a user. The homeserver then exchanges the `m.room.third_party_invite` event
+in the room for a complete [`m.room.member`](#mroommember) event with
+`content.membership: invite` and a `content.third_party_invite` property for the
+user that has bound the third-party identifier. If the invitee is on a different
+homeserver than the inviting user, the invitee's homeserver makes a request to
+[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
 
-The third-party user will then need to verify their identity, which
+All homeservers MUST verify the signature in the `m.room.member` event's
-results in a call from the identity server to the homeserver that bound
+`content.third_party_invite.signed` object.
-the third-party identifier to a user. The homeserver then exchanges the
-`m.room.third_party_invite` event in the room for a complete
-`m.room.member` event for `membership: invite` for the user that has
-bound the third-party identifier.
 
 If a homeserver is joining a room for the first time because of an
 `m.room.third_party_invite`, the server which is already participating
@@ -193,8 +199,8 @@ at any time - the completion is not shown in the diagram.
 
 H1 MUST verify the request from H3 to ensure the `signed` property is
 correct as well as the `key_validity_url` as still being valid. This is
-done by making a request to the [identity server
+done by making a request to the identity server's
-/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
+[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
 endpoint, using the provided URL rather than constructing a new one. The
 query string and response for the provided URL must match the Identity
 Service Specification.

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

@@ -185,7 +185,7 @@ included under the `m.relations` property in `unsigned` for the thread root. For
 ```
 
 `latest_event` is the most recent event (topologically to the server) in the thread sent by an
-un-[ignored user](#ignoring-users).
+un-[ignored user](#ignoring-users). It should be serialized in the same form as the event itself.
 
 Note that, as in the example above, child events of the `latest_event` should
 themselves be aggregated and included under `m.relations` for that event. The

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

@@ -202,11 +202,13 @@ specific user, and should be set to the Matrix user ID of that user. Invites
 without an `invitee` field are defined to be intended for any member of the
 room other than the sender of the event.
 
-Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either
+Clients should consider an incoming call if they see a non-expired invite event
-absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
+where the `invitee` field is either absent or equal to their user's Matrix ID.
-user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
+They should, however, evaluate whether or not to ring based on their user's trust
-suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
+relationship with the callers and/or where the call was placed. As a starting
-when clients do not ring for an incoming call invite, they still display the call invite in the room and
+point, it is RECOMMENDED that clients ignore call invites in rooms with a
+[join rule](#mroomjoin_rules) of `public`. When clients suppress ringing for an
+incoming call invite, they SHOULD still display the call invite in the room and
 annotate that it was ignored.
 
 ##### Glare

content/proposals.md

@@ -185,6 +185,10 @@ is as follows:
     -   Take care in creating your proposal. Specify your intended
         changes, and give reasoning to back them up. Changes without
         justification will likely be poorly received by the community.
+    -   At the time of creating your draft you will not yet know the PR number, so you
+        should use a placeholder number to name your file and edit that
+        after PR submission. The suggested steps are described in
+        detail [in the proposals guide](https://github.com/matrix-org/matrix-spec-proposals#1-writing-the-proposal).
 -   Fork and make a PR to the
     [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals) repository.
     The ID of your PR will become the MSC ID for the lifetime of your
@@ -493,6 +497,42 @@ In summary:
     a small table at the bottom mapping the various values from stable
     to unstable.
 
+### Placeholder MSCs
+
+Some proposals may contain security-sensitive or private context which can't be
+publicly disclosed until a later stage in the idea or solution process. Typically,
+the initial idea is validated using some amount of implementation or experimentation
+and may require an MSC number to make that implementation easier.
+
+Placeholder MSCs are used to represent proposals in a state where implementation
+is ongoing, but the MSC details can't yet be disclosed. Authors which feel as
+though their MSC could be highly sensitive MUST get in contact with the Spec Core
+Team or [Security Team](https://matrix.org/security-disclosure-policy/) prior to
+opening their MSC. If either team determines that a placeholder MSC is required,
+it may be opened as such.
+
+There are a few expectations attached to placeholder MSCs:
+
+* They have a title which marks them WIP, and are in the "draft" state.
+* They have the following labels: `[proposal-placeholder, action-required, needs-implementation]`.
+  * Notably, *not* `proposal`.
+* They are relatively short-lived (ideally less than 6-12 months in placeholder).
+* They propose solutions which are reasonably likely to be accepted. If a placeholder
+  needs to be closed because the idea won't work, isn't needed, etc, then the MSC's
+  content MUST be published ahead of that closure.
+  * Note: the MSC's publication (and therefore closure) may be delayed until an
+    appropriate point in the security disclosure cycle. For example, an alternative
+    MSC being published, or a stream of work being completed.
+* When they are updated to receive real content, the following happens:
+  1. The Spec Core Team or the author leaves a comment to cause a notification
+     that the MSC has been replaced with real content.
+  2. The `proposal` label (or its equivalent) is added to trigger chat notifications
+     in the public Matrix rooms. The `proposal-placeholder` and `action-required`
+     labels should be removed at this stage as well. Other labels are removed/applied
+     per normal process.
+* The Spec Core Team is aware of the intended MSC's title and purpose. This is
+  especially important if the Security Team approved the use of a placeholder MSC.
+
 ## Proposal Tracking
 
 This is a living document generated from the list of proposals on the

content/rooms/_index.md

@@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including
 discovered security vulnerabilities and age.
 
 Clients should not ask room administrators to upgrade their rooms if the
-room is running a stable version. Servers SHOULD use **room version 10** as
+room is running a stable version. Servers SHOULD use **room version 11** as
 the default room version when creating new rooms.
 
 The available room versions are:

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" %}}

content/rooms/v1.md

@@ -51,7 +51,7 @@ inconsistencies may occur.
 
 Events in version 1 rooms have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

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
 

content/rooms/v2.md

@@ -49,7 +49,7 @@ completeness.
 
 Events in rooms of this version have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

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
@@ -88,14 +95,20 @@ The rules are as follows:
         version, reject.
     4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
-2.  Reject if event has `auth_events` that:
+2.  Considering the event's `auth_events`:
-    1.  have duplicate entries for a given `type` and `state_key` pair
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
-    2.  have entries whose `type` and `state_key` don't match those
+        reject.
+    2.  If there are entries whose `type` and `state_key` don't match those
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
-        algorithm described in the server specification.
+        algorithm described in the server specification, reject.
-3.  If event does not have a `m.room.create` in its `auth_events`,
+    3.  If there are entries which were themselves rejected under the [checks
-    reject.
+        performed on receipt of a
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+    4. If there is no `m.room.create` event among the entries, reject.
+3. If the `content` of the `m.room.create` event in the room state has the
+   property `m.federate` set to `false`, and the `sender` domain of the event
+   does not match the `sender` domain of the create event, reject.
 4.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in
         `content`, reject.
@@ -223,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" %}}

content/rooms/v7.md

@@ -74,14 +74,20 @@ The rules are as follows:
         version, reject.
     4.  If `content` has no `creator` property, reject.
     5.  Otherwise, allow.
-2.  Reject if event has `auth_events` that:
+2.  Considering the event's `auth_events`:
-    1.  have duplicate entries for a given `type` and `state_key` pair
+    1.  If there are duplicate entries for a given `type` and `state_key` pair,
-    2.  have entries whose `type` and `state_key` don't match those
+        reject.
+    2.  If there are entries whose `type` and `state_key` don't match those
         specified by the [auth events
         selection](/server-server-api#auth-events-selection)
-        algorithm described in the server specification.
+        algorithm described in the server specification, reject.
-3.  If event does not have a `m.room.create` in its `auth_events`,
+    3.  If there are entries which were themselves rejected under the [checks
-    reject.
+        performed on receipt of a
+        PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
+    4. If there is no `m.room.create` event among the entries, reject.
+3. If the `content` of the `m.room.create` event in the room state has the
+   property `m.federate` set to `false`, and the `sender` domain of the event
+   does not match the `sender` domain of the create event, reject.
 4.  If type is `m.room.member`:
     1.  If there is no `state_key` property, or no `membership` property in
         `content`, reject.
@@ -219,7 +225,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v4-event-format" %}}
+{{% rver-fragment name="v6-event-format" %}}
 
 #### Deprecated event content schemas
 

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
 

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
 

content/server-server-api.md

@@ -119,7 +119,8 @@ to send. The process overall is as follows:
     server must present a valid certificate for the hostname.
 
 3.  If the hostname is not an IP literal, a regular HTTPS request is
-    made to `https://<hostname>/.well-known/matrix/server`, expecting
+    made to `https://<hostname>/.well-known/matrix/server` (according to 
+    [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), expecting
     the schema defined later in this section. 30x redirects should be
     followed, however redirection loops should be avoided. Responses
     (successful or otherwise) to the `/.well-known` endpoint should be
@@ -537,14 +538,14 @@ the following subset of the room state:
 - If type is `m.room.member`:
 
     - The target's current `m.room.member` event, if any.
-    - If `membership` is `join` or `invite`, the current
+    - If `membership` is `join`, `invite` or `knock`, the current
       `m.room.join_rules` event, if any.
     - If membership is `invite` and `content` contains a
       `third_party_invite` property, the current
       `m.room.third_party_invite` event with `state_key` matching
       `content.third_party_invite.signed.token`, if any.
-    - If `content.join_authorised_via_users_server` is present,
+    - If `membership` is `join`, `content.join_authorised_via_users_server`
-      and the [room version supports restricted rooms](/rooms/#feature-matrix),
+      is present, and the [room version supports restricted rooms](/rooms/#feature-matrix),
       then the `m.room.member` event with `state_key` matching
       `content.join_authorised_via_users_server`.
 
@@ -970,9 +971,8 @@ the event to other servers in the room.
 ## Third-party invites
 
 {{% boxes/note %}}
-More information about third-party invites is available in the
+More information about third-party invites is available in the Client-Server API
-[Client-Server API](/client-server-api) under
+under the [Third-party invites](/client-server-api/#third-party-invites) module.
-the Third-party Invites module.
 {{% /boxes/note %}}
 
 When a user wants to invite another user in a room but doesn't know the
@@ -985,38 +985,41 @@ API](/identity-service-api).
 
 ### Cases where an association exists for a third-party identifier
 
-If the third-party identifier is already bound to a Matrix ID, a lookup
+If the third-party identifier is already bound to a Matrix ID, a [lookup
-request on the identity server will return it. The invite is then
+request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
-processed by the inviting homeserver as a standard `m.room.member`
+server will return it. The invite is then processed by the inviting homeserver
-invite event. This is the simplest case.
+as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
+simplest case.
 
 ### Cases where an association doesn't exist for a third-party identifier
 
 If the third-party identifier isn't bound to any Matrix ID, the inviting
-homeserver will request the identity server to store an invite for this
+homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
-identifier and to deliver it to whoever binds it to its Matrix ID. It
+for this identifier and to deliver it to whoever binds it to its Matrix ID. It
-will also send an `m.room.third_party_invite` event in the room to
+will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
-specify a display name, a token and public keys the identity server
+event in the room to specify a display name, a token and public keys the
-provided as a response to the invite storage request.
+identity server provided as a response to the invite storage request.
 
-When a third-party identifier with pending invites gets bound to a
+When a third-party identifier with pending invites gets bound to a Matrix ID,
-Matrix ID, the identity server will send a POST request to the ID's
+the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
-homeserver as described in the [Invitation
+endpoint of the the ID's homeserver as described in the [Invitation
-Storage](/identity-service-api#invitation-storage)
+Storage](/identity-service-api#invitation-storage) section of the Identity
-section of the Identity Service API.
+Service API.
 
 The following process applies for each invite sent by the identity
 server:
 
-The invited homeserver will create an `m.room.member` invite event
+The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
-containing a special `third_party_invite` section containing the token
+invite event containing a special `third_party_invite` section containing the
-and a signed object, both provided by the identity server.
+token and a `signed` object, both provided by the identity server.
 
 If the invited homeserver is in the room the invite came from, it can
 auth the event and send it.
 
 However, if the invited homeserver isn't in the room the invite came
-from, it will need to request the room's homeserver to auth the event.
+from, it will need to request the inviting homeserver to auth the event
+at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid)
+endpoint.
 
 {{% http-api spec="server-server" api="third_party_invite" %}}
 
@@ -1045,11 +1048,10 @@ user's Matrix ID and the token delivered when the invite was stored,
 this verification will prove that the `m.room.member` invite event comes
 from the user owning the invited third-party identifier.
 
-## Public Room Directory
+## Published Room Directory
 
-To complement the [Client-Server
+To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory), 
-API](/client-server-api)'s room directory,
+homeservers need a way to query the published rooms of another server.
-homeservers need a way to query the public rooms for another server.
 This can be done by making a request to the `/publicRooms` endpoint for
 the server the room directory should be retrieved for.
 
@@ -1337,7 +1339,7 @@ calculated as follows.
 The *content hash* of an event covers the complete event including the
 *unredacted* contents. It is calculated as follows.
 
-First, any existing `unsigned`, `signature`, and `hashes` members are
+First, any existing `unsigned`, `signatures`, and `hashes` properties are
 removed. The resulting object is then encoded as [Canonical
 JSON](/appendices#canonical-json), and the JSON is hashed using
 SHA-256.

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/application-service/definitions/registration.yaml

@@ -19,7 +19,7 @@ properties:
     type: string
     description: A unique, user-defined ID of the application service which will never change.
   url:
-    type: string
+    type: ["null", "string"]
     description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
   as_token:
     type: string

data/api/client-server/account_deactivation.yaml

@@ -0,0 +1,141 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Account Deactivation API
+  version: 1.0.0
+paths:
+  /account/deactivate:
+    post:
+      summary: Deactivate a user's account.
+      description: |-
+        Deactivate the user's account, removing all ability for the user to
+        login again.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+
+        Unlike other endpoints, this endpoint does not take an `id_access_token`
+        parameter because the homeserver is expected to sign the request to the
+        identity server instead.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: deactivateAccount
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+                id_server:
+                  type: string
+                  description: |-
+                    The identity server to unbind all of the user's 3PIDs from.
+                    If not provided, the homeserver MUST use the `id_server`
+                    that was originally use to bind each identifier. If the
+                    homeserver does not know which `id_server` that was,
+                    it must return an `id_server_unbind_result` of
+                    `no-support`.
+                  example: example.org
+                erase:
+                  x-addedInMatrixVersion: "1.10"
+                  type: boolean
+                  description: |-
+                    Whether the user would like their content to be erased as
+                    much as possible from the server.
+
+                    Erasure means that any users (or servers) which join the
+                    room after the erasure request are served redacted copies of
+                    the events sent by this account. Users which had visibility
+                    on those events prior to the erasure are still able to see
+                    unredacted copies. No redactions are sent and the erasure
+                    request is not shared over federation, so other servers
+                    might still serve unredacted copies.
+
+                    The server should additionally erase any non-event data
+                    associated with the user, such as [account data](/client-server-api/#client-config)
+                    and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
+
+                    Defaults to `false` if not present.
+        required: true
+      responses:
+        "200":
+          description: The account has been deactivated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id_server_unbind_result:
+                    type: string
+                    enum:
+                      - success
+                      - no-support
+                    description: |-
+                      An indicator as to whether or not the homeserver was able to unbind
+                      the user's 3PIDs from the identity server(s). `success` indicates
+                      that all identifiers have been unbound from the identity server while
+                      `no-support` indicates that one or more identifiers failed to unbind
+                      due to the identity server refusing the request or the homeserver
+                      being unable to determine an identity server to unbind from. This
+                      must be `success` if the homeserver has no identifiers to unbind
+                      for the user.
+                    example: success
+                required:
+                  - id_server_unbind_result
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/administrative_contact.yaml

@@ -201,6 +201,11 @@ paths:
 
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: add3PID
       security:
         - accessTokenQuery: []

data/api/client-server/appservice_room_directory.yaml

@@ -13,18 +13,21 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Application Service Room Directory API
+  title: Matrix Client-Server Application Service Published Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: Updates a room's visibility in the application service's room directory.
+      summary: |-
-      description: |-
+        Updates a room's visibility in the application service's published room
-        Updates the visibility of a given room on the application service's room
         directory.
+      description: |-
+        Updates the visibility of a given room in the application service's
+        published room directory.
 
-        This API is similar to the room directory visibility API used by clients
+        This API is similar to the
-        to update the homeserver's more general room directory.
+        [visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
+        used by clients to update the homeserver's more general published room directory.
 
         This API requires the use of an application service access token (`as_token`)
         instead of a typical client's access_token. This API cannot be invoked by

data/api/client-server/create_room.yaml

@@ -87,12 +87,9 @@ paths:
                     - public
                     - private
                   description: |-
-                    A `public` visibility indicates that the room will be shown
+                    The room's visibility in the server's
-                    in the published room list. A `private` visibility will hide
+                    [published room directory](/client-server-api#published-room-directory).
-                    the room from the published room list. Rooms default to
+                    Defaults to `private`.
-                    `private` visibility if this key is not included. NB: This
-                    should not be confused with `join_rules` which also uses the
-                    word `public`.
                 room_alias_name:
                   type: string
                   description: |-
@@ -109,15 +106,17 @@ paths:
                 name:
                   type: string
                   description: |-
-                    If this is included, an `m.room.name` event will be sent
+                    If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
-                    into the room to indicate the name of the room. See Room
+                    will be sent into the room to indicate the name for the room.
-                    Events for more information on `m.room.name`.
+                    This overwrites any [`m.room.name`](/client-server-api/#mroomname)
+                    event in `initial_state`.
                 topic:
                   type: string
                   description: |-
-                    If this is included, an `m.room.topic` event will be sent
+                    If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
-                    into the room to indicate the topic for the room. See Room
+                    event with a `text/plain` mimetype will be sent into the room
-                    Events for more information on `m.room.topic`.
+                    to indicate the topic for the room. This overwrites any
+                    [`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
                 invite:
                   type: array
                   description: |-
@@ -131,32 +130,7 @@ paths:
                     A list of objects representing third-party IDs to invite into
                     the room.
                   items:
-                    type: object
+                    $ref: definitions/invite_3pid.yaml
-                    title: Invite3pid
-                    properties:
-                      id_server:
-                        type: string
-                        description: The hostname+port of the identity server which should be used for
-                          third-party identifier lookups.
-                      id_access_token:
-                        type: string
-                        description: |-
-                          An access token previously registered with the identity server. Servers
-                          can treat this as optional to distinguish between r0.5-compatible clients
-                          and this specification version.
-                      medium:
-                        type: string
-                        description: |-
-                          The kind of address being passed in the address field, for example `email`
-                          (see [the list of recognised values](/appendices/#3pid-types)).
-                      address:
-                        type: string
-                        description: The invitee's third-party identifier.
-                    required:
-                      - id_server
-                      - id_access_token
-                      - medium
-                      - address
                 room_version:
                   type: string
                   description: |-

data/api/client-server/cross_signing.yaml

@@ -26,7 +26,7 @@ paths:
         Publishes cross-signing keys for the user.
 
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
-        
+
         User-Interactive Authentication MUST be performed, except in these cases:
         - there is no existing cross-signing master key uploaded to the homeserver, OR
         - there is an existing cross-signing master key and it exactly matches the
@@ -34,11 +34,16 @@ paths:
           keys provided in the request (self-signing key, user-signing key) they MUST also
           match the existing keys stored on the server. In other words, the request contains
           no new keys.
-        
+
         This allows clients to freely upload one set of keys, but not modify/overwrite keys if
-        they already exist. Allowing clients to upload the same set of keys more than once 
+        they already exist. Allowing clients to upload the same set of keys more than once
         makes this endpoint idempotent in the case where the response is lost over the network,
         which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

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

@@ -0,0 +1,45 @@
+# 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: Invite3pid
+properties:
+  id_server:
+    type: string
+    description: The hostname+port of the identity server which should be used for
+      third-party identifier lookups.
+  id_access_token:
+    type: string
+    description: |-
+      An access token previously registered with the identity server. Servers
+      can treat this as optional to distinguish between r0.5-compatible clients
+      and this specification version.
+  medium:
+    type: string
+    description: |-
+      The kind of address being passed in the address field, for example `email`
+      (see [the list of recognised values](/appendices/#3pid-types)).
+  address:
+    type: string
+    description: The invitee's third-party identifier.
+required:
+  - id_server
+  - id_access_token
+  - medium
+  - address
+example: {
+  "id_server": "matrix.org",
+  "id_access_token": "abc123_OpaqueString",
+  "medium": "email",
+  "address": "cheeky@monkey.com"
+}

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

@@ -23,6 +23,7 @@ properties:
     type: string
     description: |-
       The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`.
+    example: "m.megolm.v1.aes-sha2"
   forwarding_curve25519_key_chain:
     type: array
     items:
@@ -30,31 +31,24 @@ properties:
     description: |-
       Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
       events.
+    example: [ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ]
   sender_key:
     type: string
     description: |-
       Unpadded base64-encoded device Curve25519 key.
+    example: "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
   sender_claimed_keys:
     type: object
     additionalProperties:
       type: string
     description: |-
       A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device.
+    example: { "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" }
   session_key:
     type: string
     description: |-
       Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
-example: {
+    example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
-  "algorithm": "m.megolm.v1.aes-sha2",
-  "forwarding_curve25519_key_chain": [
-    "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
-  ],
-  "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
-  "sender_claimed_keys": {
-    "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
-  },
-  "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
-}
 required:
   - algorithm
   - forwarding_curve25519_key_chain

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

@@ -0,0 +1,88 @@
+# 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: OlmPayload
+description: |-
+  The plaintext payload of Olm message events.
+properties:
+  type:
+    type: string
+    description: The type of the event.
+  content:
+    type: object
+    description: The event content.
+  sender:
+    type: string
+    description: The user ID of the event sender.
+  recipient:
+    type: string
+    description: The user ID of the intended event recipient.
+  recipient_keys:
+    description: The recipient's signing keys of the encrypted event.
+    $ref: "#/components/schemas/SigningKeys"
+  keys:
+    $ref: "#/components/schemas/SigningKeys"
+    description: The sender's signing keys of the encrypted event.
+  sender_device_keys:
+    $ref: device_keys.yaml 
+    description: The sender's device keys.
+    x-addedInMatrixVersion: "1.15"
+required:
+  - type
+  - content
+  - sender
+  - recipient
+  - recipient_keys
+  - keys
+components:
+  schemas:
+    SigningKeys:
+      type: object
+      title: SigningKeys
+      description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
+      properties:
+        ed25519:
+          type: string
+          description: The Ed25519 public key encoded using unpadded base64.
+      required:
+        - ed25519
+example: {
+  "type": "<type of the plaintext event>",
+  "content": "<content for the plaintext event>",
+  "sender": "<sender_user_id>",
+  "recipient": "<recipient_user_id>",
+  "recipient_keys": {
+    "ed25519": "<our_ed25519_key>"
+  },
+  "keys": {
+    "ed25519": "<sender_ed25519_key>"
+  },
+  "sender_device_keys": {
+    "algorithms": ["<supported>", "<algorithms>"],
+    "user_id": "<user_id>",
+    "device_id": "<device_id>",
+    "keys": {
+      "ed25519:<device_id>": "<sender_ed25519_key>",
+      "curve25519:<device_id>": "<sender_curve25519_key>"
+    },
+    "signatures": {
+      "<user_id>": {
+        "ed25519:<device_id>": "<device_signature>",
+        "ed25519:<ssk_id>": "<ssk_signature>",
+      }
+    }
+  }
+}

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/public_rooms_chunk.yaml

@@ -13,10 +13,12 @@
 # limitations under the License.
 
 type: object
-title: "PublicRoomsChunk"
+title: "PublishedRoomsChunk"
 properties:
   canonical_alias:
     type: string
+    format: mx-room-alias
+    pattern: "^#"
     description: The canonical alias of the room, if any.
     example: "#general:example.org"
   name:
@@ -29,11 +31,15 @@ properties:
     example: 42
   room_id:
     type: string
+    format: mx-room-id
+    pattern: "^!"
     description: The ID of the room.
     example: "!abcdefg:example.org"
   topic:
     type: string
-    description: The topic of the room, if any.
+    description: |-
+      The plain text topic of the room. Omitted if no `text/plain` mimetype
+      exists in [`m.room.topic`](/client-server-api/#mroomtopic).
     example: "All things general"
   world_readable:
     type: boolean
@@ -59,7 +65,6 @@ properties:
     example: "public"
   room_type:
     type: string
-    x-addedInMatrixVersion: "1.4"
     description: |-
       The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
 required:

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

@@ -13,28 +13,15 @@
 # limitations under the License.
 
 type: object
-description: A list of the rooms on the server.
+description: A list of the published rooms on the server.
 required: ["chunk"]
 properties:
   chunk:
     type: array
     description: |-
-      A paginated chunk of public rooms.
+      A paginated chunk of published rooms.
     items:
-      allOf:
+      $ref: "public_rooms_chunk.yaml"
-        - $ref: "public_rooms_chunk.yaml"
-        - type: object
-          title: PublicRoomsChunk
-          properties:
-            # Override description of join_rule
-            join_rule:
-              type: string
-              description: |-
-                The room's join rule. When not present, the room is assumed to
-                be `public`. Note that rooms with `invite` join rules are not
-                expected here, but rooms with `knock` rules are given their
-                near-public nature.
-              example: "public"
   next_batch:
     type: string
     description: |-
@@ -50,7 +37,7 @@ properties:
   total_room_count_estimate:
     type: integer
     description: |-
-        An estimate on the total number of public rooms, if the
+        An estimate on the total number of published rooms, if the
         server has an estimate.
 example: {
   "chunk": [

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

@@ -0,0 +1,44 @@
+# 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: RoomSummary
+allOf:
+  - $ref: public_rooms_chunk.yaml
+  - type: object
+    properties:
+      room_type:
+        type: string
+        description: The `type` of room (from
+          [`m.room.create`](/client-server-api/#mroomcreate)),
+          if any.
+      allowed_room_ids:
+        type: array
+        items:
+          type: string
+          format: mx-room-id
+          pattern: "^!"
+        description: |-
+          If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
+          are specified by the join rules. Empty or omitted otherwise.
+      encryption:
+        type: string
+        enum:
+          - "m.megolm.v1.aes-sha2"
+        description: |-
+          The encryption algorithm to be used to encrypt messages sent in the
+          room.
+      room_version:
+        description: The version of the room.
+        type: string

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

@@ -14,8 +14,8 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
+    **Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    parameter.
+    or [login](/client-server-api/#login), as a query parameter.
 
     It can also be the `as_token` of an application service.
   name: access_token
@@ -23,11 +23,11 @@ accessTokenQuery:
 accessTokenBearer:
   type: http
   description: |-
-    The `access_token` returned by a call to `/login` or `/register`, using the
+    The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    `Authorization: Bearer` header.
+    or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
-    
+
     This is the preferred method.
   scheme: bearer
 appserviceAccessTokenQuery:
@@ -42,6 +42,6 @@ appserviceAccessTokenBearer:
   description: |-
     The `as_token` of an application service, using the `Authorization: Bearer`
     header.
-    
+
     This is the preferred method.
   scheme: bearer

data/api/client-server/device_management.yaml

@@ -137,6 +137,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given device, and invalidates any access token associated with it.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -189,6 +194,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given devices, and invalidates any access token associated with them.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/api/client-server/key_backup.yaml

@@ -438,22 +438,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -571,22 +556,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -644,22 +614,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -778,22 +733,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -866,22 +806,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -1007,22 +932,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -1056,6 +966,26 @@ servers:
       basePath:
         default: /_matrix/client/v3
 components:
+  schemas:
+    RoomKeysUpdateResponse:
+      type: object
+      title: RoomKeysUpdateResponse
+      properties:
+        etag:
+          description: |-
+            The new etag value representing stored keys in the backup.
+            
+            See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
+            for more details.
+          type: string
+          example: abcdefg
+        count:
+          description: The number of keys stored in the backup
+          type: integer
+          example: 10
+      required:
+        - etag
+        - count
   securitySchemes:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery

data/api/client-server/list_public_rooms.yaml

@@ -13,14 +13,15 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Room Directory API
+  title: Matrix Client-Server Published Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/room/{roomId}":
     get:
       summary: Gets the visibility of a room in the directory
-      description: Gets the visibility of a given room on the server's public room
+      description: |-
-        directory.
+        Gets the visibility of a given room in the server's
+        published room directory.
       operationId: getRoomVisibilityOnDirectory
       parameters:
         - in: path
@@ -32,7 +33,7 @@ paths:
             type: string
       responses:
         "200":
-          description: The visibility of the room in the directory
+          description: The visibility of the room in the directory.
           content:
             application/json:
               schema:
@@ -50,7 +51,7 @@ paths:
                     "visibility": "public"
                   }
         "404":
-          description: The room is not known to the server
+          description: The room is not known to the server.
           content:
             application/json:
               schema:
@@ -64,14 +65,13 @@ paths:
       tags:
         - Room discovery
     put:
-      summary: Sets the visibility of a room in the room directory
+      summary: Sets the visibility of a room in the directory
       description: |-
-        Sets the visibility of a given room in the server's public room
+        Sets the visibility of a given room in the server's published room directory.
-        directory.
 
-        Servers may choose to implement additional access control checks
+        Servers MAY implement additional access control checks, for instance,
-        here, for instance that room visibility can only be changed by
+        to ensure that a room's visibility can only be changed by the room creator
-        the room creator or a server administrator.
+        or a server administrator.
       operationId: setRoomVisibilityOnDirectory
       security:
         - accessTokenQuery: []
@@ -97,11 +97,11 @@ paths:
                     - public
                   description: |-
                     The new visibility setting for the room.
-                    Defaults to 'public'.
+                    Defaults to `public`.
               example: {
                 "visibility": "public"
               }
-        description: The new visibility for the room on the room directory.
+        description: The new visibility for the room in the published room directory.
         required: true
       responses:
         "200":
@@ -114,7 +114,7 @@ paths:
                 response:
                   value: {}
         "404":
-          description: The room is not known to the server
+          description: The room is not known to the server.
           content:
             application/json:
               schema:
@@ -129,9 +129,9 @@ paths:
         - Room discovery
   /publicRooms:
     get:
-      summary: Lists the public rooms on the server.
+      summary: Lists a server's published room directory
       description: |-
-        Lists the public rooms on the server.
+        Lists a server's published room directory.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -154,13 +154,13 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the public room lists from. Defaults to the
+            The server to fetch the published room directory from. Defaults
-            local server. Case sensitive.
+            to the local server. Case sensitive.
           schema:
             type: string
       responses:
         "200":
-          description: A list of the rooms on the server.
+          description: A list of the published rooms on the server.
           content:
             application/json:
               schema:
@@ -168,9 +168,9 @@ paths:
       tags:
         - Room discovery
     post:
-      summary: Lists the public rooms on the server with optional filter.
+      summary: Lists a server's published room directory with an optional filter
       description: |-
-        Lists the public rooms on the server, with optional filter.
+        Lists a server's published room directory with an optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -182,8 +182,8 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the public room lists from. Defaults to the
+            The server to fetch the published room directory from. Defaults
-            local server. Case sensitive.
+            to the local server. Case sensitive.
           schema:
             type: string
       requestBody:
@@ -253,7 +253,7 @@ paths:
         required: true
       responses:
         "200":
-          description: A list of the rooms on the server.
+          description: A filtered list of the published rooms on the server.
           content:
             application/json:
               schema:

data/api/client-server/logout.yaml

@@ -47,7 +47,7 @@ paths:
         deleted alongside the device.
 
         This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because
-        User-Interactive Authentication is designed to protect against attacks where the
+        User-Interactive Authentication is designed to protect against attacks where
         someone gets hold of a single access token then takes over the account. This
         endpoint invalidates all access tokens for the user, including the token used in
         the request, and therefore the attacker is unable to take over the account in

data/api/client-server/oauth_server_metadata.yaml

@@ -0,0 +1,176 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server OAuth 2.0 Server Metadata Discovery API
+  version: 1.0.0
+paths:
+  "/auth_metadata":
+    get:
+      summary: Get the OAuth 2.0 authorization server metadata.
+      description: |-
+        Gets the OAuth 2.0 authorization server metadata, as defined in
+        [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
+        endpoint URLs and the supported parameters that can be used by the
+        clients.
+
+        This endpoint definition includes only the fields that are meaningful in
+        the context of the Matrix specification. The full list of possible
+        fields is available in the [OAuth Authorization Server Metadata
+        registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
+        and normative definitions of them are available in their respective
+        RFCs.
+
+        {{% boxes/note %}}
+        The authorization server metadata is relatively large and may change
+        over time. Clients should:
+
+        - Cache the metadata appropriately based on HTTP caching headers
+        - Refetch the metadata if it is stale
+        {{% /boxes/note %}}
+      operationId: getAuthMetadata
+      responses:
+        "200":
+          description: The OAuth 2.0 authorization server metadata.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  issuer:
+                    type: string
+                    format: uri
+                    description: |-
+                      The authorization server's issuer identifier, which is a URL that uses the
+                      `https` scheme and has no query or fragment components.
+
+                      This is not used in the context of the Matrix specification, but is required
+                      by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
+                  authorization_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the authorization endpoint, necessary to use the authorization code
+                      grant.
+                  token_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the token endpoint, necessary to use the authorization code grant and
+                      the refresh token grant.
+                  revocation_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the revocation endpoint, necessary to log out a client by invalidating
+                      its access and refresh tokens.
+                  registration_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the client registration endpoint, necessary to perform dynamic
+                      registration of a client.
+                  response_types_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 response type strings that the server supports at the
+                      authorization endpoint.
+
+                      This array MUST contain at least the `code` value, for clients to be able to
+                      use the authorization code grant.
+                    items:
+                      type: string
+                      description: A response type that the server supports.
+                  grant_types_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 grant type strings that the server supports at the token
+                      endpoint.
+
+                      This array MUST contain at least the `authorization_code` and `refresh_token`
+                      values, for clients to be able to use the authorization code grant and refresh
+                      token grant, respectively.
+                    items:
+                      type: string
+                      description: A grant type that the server supports.
+                  response_modes_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 response mode strings that the server supports at the
+                      authorization endpoint.
+
+                      This array MUST contain at least the `query` and `fragment` values, for
+                      improved security in the authorization code grant.
+                    items:
+                      type: string
+                      description: A response mode that the server supports.
+                  code_challenge_methods_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
+                      that the server supports at the authorization endpoint.
+
+                      This array MUST contain at least the `S256` value, for improved security in
+                      the authorization code grant.
+                    items:
+                      type: string
+                      description: A PKCE code challenge method that the server supports.
+                  prompt_values_supported:
+                    type: array
+                    description: |-
+                      List of OpenID Connect prompt values that the server supports at the
+                      authorization endpoint.
+
+                      Only the `create` value defined in [Initiating User Registration via OpenID
+                      Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
+                      supported, for a client to signal to the server that the user desires to
+                      register a new account.
+                    items:
+                      type: string
+                      description: A prompt value that the server supports.
+                required:
+                  - issuer
+                  - authorization_endpoint
+                  - token_endpoint
+                  - revocation_endpoint
+                  - registration_endpoint
+                  - response_types_supported
+                  - grant_types_supported
+                  - response_modes_supported
+                  - code_challenge_methods_supported
+                example: {
+                  "issuer": "https://account.example.com/",
+                  "authorization_endpoint": "https://account.example.com/oauth2/auth",
+                  "token_endpoint": "https://account.example.com/oauth2/token",
+                  "registration_endpoint": "https://account.example.com/oauth2/clients/register",
+                  "revocation_endpoint": "https://account.example.com/oauth2/revoke",
+                  "response_types_supported": ["code"],
+                  "grant_types_supported": ["authorization_code", "refresh_token"],
+                  "response_modes_supported": ["query", "fragment"],
+                  "code_challenge_methods_supported": ["S256"],
+                }
+      tags:
+        - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1

data/api/client-server/old_sync.yaml

@@ -214,7 +214,7 @@ paths:
                             - public
                           description: |-
                             Whether this room is visible to the `/publicRooms` API
-                            or not."
+                            or not.
                         account_data:
                           type: array
                           description: |-

data/api/client-server/password_management.yaml

@@ -0,0 +1,242 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Password Management API
+  version: 1.0.0
+paths:
+  /account/password:
+    post:
+      summary: Changes a user's password.
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
+        ensure the user changing the password is actually the owner of the
+        account.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided. The homeserver SHOULD NOT revoke the
+        access token provided in the request. Whether other access tokens for
+        the user are revoked depends on the request parameters.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: changePassword
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                new_password:
+                  type: string
+                  description: The new password for the account.
+                  example: ihatebananas
+                logout_devices:
+                  type: boolean
+                  description: |-
+                    Whether the user's other access tokens, and their associated devices, should be
+                    revoked if the request succeeds. Defaults to true.
+
+                    When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
+                    for the user's remaining devices.
+                  example: true
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+              required:
+                - new_password
+        required: true
+      responses:
+        "200":
+          description: The password has been changed.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+  /account/password/email/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given email address for the
+        purpose of resetting a user's password
+      description: |-
+        The homeserver must check that the given email address **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given email address could be found. The server may instead send an
+        email to the given address prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the email itself, either by sending a
+        validation email itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_email_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An email was sent to the given address.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Email not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+  /account/password/msisdn/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of resetting a user's password.
+      description: |-
+        The homeserver must check that the given phone number **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given phone number could be found. The server may instead send the SMS
+        to the given phone number prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the phone number itself, either by sending a
+        validation message itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordMSISDN
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An SMS message was sent to the given phone number.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Phone number not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/registration.yaml

@@ -373,315 +373,6 @@ paths:
                   }
       tags:
         - Account management
-  /account/password:
-    post:
-      summary: Changes a user's password.
-      description: |-
-        Changes the password for an account on this homeserver.
-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
-        ensure the user changing the password is actually the owner of the
-        account.
-
-        An access token should be submitted to this endpoint if the client has
-        an active session.
-
-        The homeserver may change the flows available depending on whether a
-        valid access token is provided. The homeserver SHOULD NOT revoke the
-        access token provided in the request. Whether other access tokens for
-        the user are revoked depends on the request parameters.
-      security:
-        - {}
-        - accessTokenQuery: []
-        - accessTokenBearer: []
-      operationId: changePassword
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                new_password:
-                  type: string
-                  description: The new password for the account.
-                  example: ihatebananas
-                logout_devices:
-                  type: boolean
-                  description: |-
-                    Whether the user's other access tokens, and their associated devices, should be
-                    revoked if the request succeeds. Defaults to true.
-
-                    When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
-                    for the user's remaining devices.
-                  example: true
-                auth:
-                  description: Additional authentication information for the user-interactive
-                    authentication API.
-                  allOf:
-                    - $ref: definitions/auth_data.yaml
-              required:
-                - new_password
-        required: true
-      responses:
-        "200":
-          description: The password has been changed.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "401":
-          description: The homeserver requires additional authentication information.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/auth_response.yaml
-        "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
-      tags:
-        - Account management
-  /account/password/email/requestToken:
-    post:
-      summary: Requests a validation token be sent to the given email address for the
-        purpose of resetting a user's password
-      description: |-
-        The homeserver must check that the given email address **is
-        associated** with an account on this homeserver. This API should be
-        used to request validation tokens when authenticating for the
-        `/account/password` endpoint.
-
-        This API's parameters and response are identical to that of the
-        [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
-        endpoint, except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given email address could be found. The server may instead send an
-        email to the given address prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
-
-        The homeserver should validate the email itself, either by sending a
-        validation email itself or by using a service it has control over.
-      operationId: requestTokenToResetPasswordEmail
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: definitions/request_email_validation.yaml
-        required: true
-      responses:
-        "200":
-          description: An email was sent to the given address.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/request_token_response.yaml
-        "400":
-          description: |-
-            The referenced third-party identifier is not recognised by the
-            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_NOT_FOUND",
-                    "error": "Email not found"
-                  }
-        "403":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_DENIED",
-                    "error": "Third-party identifier is not allowed"
-                  }
-      tags:
-        - Account management
-  /account/password/msisdn/requestToken:
-    post:
-      summary: Requests a validation token be sent to the given phone number for the
-        purpose of resetting a user's password.
-      description: |-
-        The homeserver must check that the given phone number **is
-        associated** with an account on this homeserver. This API should be
-        used to request validation tokens when authenticating for the
-        `/account/password` endpoint.
-
-        This API's parameters and response are identical to that of the
-        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
-        endpoint, except that
-        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
-        given phone number could be found. The server may instead send the SMS
-        to the given phone number prompting the user to create an account.
-        `M_THREEPID_IN_USE` may not be returned.
-
-        The homeserver should validate the phone number itself, either by sending a
-        validation message itself or by using a service it has control over.
-      operationId: requestTokenToResetPasswordMSISDN
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: definitions/request_msisdn_validation.yaml
-        required: true
-      responses:
-        "200":
-          description: An SMS message was sent to the given phone number.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/request_token_response.yaml
-        "400":
-          description: |-
-            The referenced third-party identifier is not recognised by the
-            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
-            can be returned if the server does not trust/support the identity server
-            provided in the request.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_NOT_FOUND",
-                    "error": "Phone number not found"
-                  }
-        "403":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_THREEPID_DENIED",
-                    "error": "Third-party identifier is not allowed"
-                  }
-      tags:
-        - Account management
-  /account/deactivate:
-    post:
-      summary: Deactivate a user's account.
-      description: |-
-        Deactivate the user's account, removing all ability for the user to
-        login again.
-
-        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
-
-        An access token should be submitted to this endpoint if the client has
-        an active session.
-
-        The homeserver may change the flows available depending on whether a
-        valid access token is provided.
-
-        Unlike other endpoints, this endpoint does not take an `id_access_token`
-        parameter because the homeserver is expected to sign the request to the
-        identity server instead.
-      security:
-        - {}
-        - accessTokenQuery: []
-        - accessTokenBearer: []
-      operationId: deactivateAccount
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                auth:
-                  description: Additional authentication information for the user-interactive
-                    authentication API.
-                  allOf:
-                    - $ref: definitions/auth_data.yaml
-                id_server:
-                  type: string
-                  description: |-
-                    The identity server to unbind all of the user's 3PIDs from.
-                    If not provided, the homeserver MUST use the `id_server`
-                    that was originally use to bind each identifier. If the
-                    homeserver does not know which `id_server` that was,
-                    it must return an `id_server_unbind_result` of
-                    `no-support`.
-                  example: example.org
-                erase:
-                  x-addedInMatrixVersion: "1.10"
-                  type: boolean
-                  description: |-
-                    Whether the user would like their content to be erased as
-                    much as possible from the server.
-
-                    Erasure means that any users (or servers) which join the
-                    room after the erasure request are served redacted copies of
-                    the events sent by this account. Users which had visibility
-                    on those events prior to the erasure are still able to see
-                    unredacted copies. No redactions are sent and the erasure
-                    request is not shared over federation, so other servers
-                    might still serve unredacted copies.
-
-                    The server should additionally erase any non-event data
-                    associated with the user, such as [account data](/client-server-api/#client-config)
-                    and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
-
-                    Defaults to `false` if not present.
-        required: true
-      responses:
-        "200":
-          description: The account has been deactivated.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id_server_unbind_result:
-                    type: string
-                    enum:
-                      - success
-                      - no-support
-                    description: |-
-                      An indicator as to whether or not the homeserver was able to unbind
-                      the user's 3PIDs from the identity server(s). `success` indicates
-                      that all identifiers have been unbound from the identity server while
-                      `no-support` indicates that one or more identifiers failed to unbind
-                      due to the identity server refusing the request or the homeserver
-                      being unable to determine an identity server to unbind from. This
-                      must be `success` if the homeserver has no identifiers to unbind
-                      for the user.
-                    example: success
-                required:
-                  - id_server_unbind_result
-        "401":
-          description: The homeserver requires additional authentication information.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/auth_response.yaml
-        "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
-      tags:
-        - Account management
   /register/available:
     get:
       summary: Checks to see if a username is available on the server.

data/api/client-server/report_content.yaml

@@ -45,7 +45,9 @@ paths:
               properties:
                 reason:
                   type: string
-                  description: The reason the room is being reported.
+                  description: The reason the room is being reported. May be blank.
+              required:
+                - reason
         required: true
       security:
         - accessTokenQuery: []
@@ -88,12 +90,11 @@ paths:
         Reports an event as inappropriate to the server, which may then notify
         the appropriate people. The caller must be joined to the room to report
         it.
-        
+
-        It might be possible for clients to deduce whether an event exists by
+        Furthermore, it might be possible for clients to deduce whether a reported
-        timing the response, as only a report for an event that does exist
+        event exists by timing the response. This is because only a report for an
-        will require the homeserver to check whether a user is joined to
+        existing event will require the homeserver to do further processing. To
-        the room. To combat this, homeserver implementations should add
+        combat this, homeservers MAY add a random delay when generating a response.
-        a random delay when generating a response.
       operationId: reportEvent
       parameters:
         - in: path
@@ -164,6 +165,88 @@ paths:
                   }
       tags:
         - Reporting content
+  "/users/{userId}/report":
+    post:
+      x-addedInMatrixVersion: "1.14"
+      summary: Report a user as inappropriate.
+      description: |-
+        Reports a user as inappropriate to the server, which may then notify
+        the appropriate people. How such information is delivered is left up to
+        implementations. The caller is not required to be joined to any rooms
+        that the reported user is joined to.
+
+        Clients may wish to [ignore](#ignoring-users) users after reporting them.
+
+        Clients could infer whether a reported user exists based on the 404 response.
+        Homeservers that wish to conceal this information MAY return 200 responses
+        regardless of the existence of the reported user.
+
+        Furthermore, it might be possible for clients to deduce whether a reported
+        user exists by timing the response. This is because only a report for an
+        existing user will require the homeserver to do further processing. To
+        combat this, homeservers MAY add a random delay when generating a response.
+      operationId: reportUser
+      parameters:
+        - in: path
+          name: userId
+          description: The user being reported.
+          required: true
+          example: "@someguy:example.com"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "this makes me sad"
+              }
+              properties:
+                reason:
+                  type: string
+                  description: The reason the room is being reported. May be blank.
+              required:
+                - reason
+        required: true
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: |
+            The user has been reported successfully or the server chose
+            to not disclose whether the users exists.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: |-
+            The user was not found on the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The user was not found."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Reporting content
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/client-server/room_initial_sync.yaml

@@ -96,7 +96,7 @@ paths:
                       - public
                     description: |-
                       Whether this room is visible to the `/publicRooms` API
-                      or not."
+                      or not.
                   account_data:
                     type: array
                     description: The private data that this user has attached to this room.

data/api/client-server/room_summary.yaml

@@ -0,0 +1,138 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Summary API
+  version: 1.0.0
+paths:
+  "/room_summary/{roomIdOrAlias}":
+    get:
+      x-addedInMatrixVersion: "1.15"
+      summary: Retrieves a summary for a room.
+      description: |-
+        Retrieves a summary for a room.
+
+        Clients should note that requests for rooms where the user's membership
+        is `invite` or `knock` might yield outdated, partial or even no data
+        since the server may not have access to the current state of the room.
+
+        Servers MAY allow unauthenticated access to this API if at least one of
+        the following conditions holds true:
+
+        - The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
+          `knock_restricted`.
+        - The room has a `world_readable` [history visibility](#room-history-visibility).
+
+        Servers should consider rate limiting requests that require a federation
+        request more heavily if the client is unauthenticated.
+      operationId: getRoomSummary
+      security:
+        - signedRequest: []
+      parameters:
+        - in: path
+          name: roomIdOrAlias
+          description: The room identifier or alias to summarise.
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            oneOf:
+              - type: string
+                format: mx-room-id
+                pattern: "^!"
+              - type: string
+                format: mx-room-alias
+                pattern: "^#"
+        - in: query
+          name: via
+          description: |-
+            The servers to attempt to request the summary from when
+            the local server cannot generate it (for instance, because
+            it has no local user in the room).
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+              format: mx-server-name
+      responses:
+        "200":
+          description: A summary of the room.
+          content:
+            application/json:
+              schema:
+                description: A summary of the room.
+                allOf:
+                  - $ref: ../client-server/definitions/room_summary.yaml
+                  - type: object
+                    properties:
+                      membership:
+                        description: |-
+                          The membership state of the user if the user is joined to the room. Absent
+                          if the API was called unauthenticated.
+                        enum:
+                          - invite
+                          - join
+                          - knock
+                          - leave
+                          - ban
+                        type: string
+              examples:
+                response:
+                  value: {
+                    room_id: "!ol19s:bleecker.street",
+                    avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
+                    guest_can_join: false,
+                    name: "CHEESE",
+                    num_joined_members: 37,
+                    topic: "Tasty tasty cheese",
+                    world_readable: true,
+                    join_rule: "public",
+                    room_type: "m.space",
+                    membership: "invite",
+                    encryption: "m.megolm.v1.aes-sha2",
+                    room_version: "9001",
+                  }
+        "404":
+          description: |-
+            The room could not be found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found."
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/rooms.yaml

@@ -105,13 +105,31 @@ paths:
           example: ""
           schema:
             type: string
+        - in: query
+          name: format
+          x-addedInMatrixVersion: "1.16"
+          description: |-
+            The format to use for the returned data. `content` (the default) will
+            return only the content of the state event. `event` will return the entire
+            event in the usual format suitable for clients, including fields like event
+            ID, sender and timestamp.
+          example: event
+          schema:
+            type: string
+            enum:
+            - content
+            - event
       responses:
         "200":
-          description: The content of the state event.
+          description: |-
+            The content of the state event, or the entire client-formatted event
+            if `?format=event` was used.
           content:
             application/json:
               schema:
-                type: object
+                oneOf:
+                  - type: object
+                  - $ref: "../../event-schemas/schema/core-event-schema/state_event.yaml"
               examples:
                 response:
                   value: {

data/api/client-server/space_hierarchy.yaml

@@ -88,18 +88,24 @@ paths:
                 properties:
                   rooms:
                     type: array
-                    description: The rooms for the current page, with the current filters.
+                    description: |-
+                       The rooms for the current page, with the current filters.
+
+                       The server should return any rooms where at least one of the following conditions is true:
+                       
+                       * The requesting user is currently a member (their [room membership](#room-membership) is `join`).
+                       * The requesting user already has permission to join, i.e. one of the following:
+                         * The user's room membership is `invite`.
+                         * The room's [join rules](#mroomjoin_rules) are set to `public`.
+                         * The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions.
+                       * The room is "knockable" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings).
+                       * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
                     items:
                       allOf:
-                        - $ref: definitions/public_rooms_chunk.yaml
+                        - $ref: definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyRoomsChunk
                           properties:
-                            room_type:
-                              type: string
-                              description: The `type` of room (from
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
-                                if any.
                             children_state:
                               type: array
                               description: |-
@@ -119,6 +125,14 @@ paths:
                                         description: The `origin_server_ts` for the event.
                                     required:
                                       - origin_server_ts
+                            room_type:
+                              x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
+                            allowed_room_ids:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            encryption:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            room_version:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                           required:
                             - children_state
                   next_batch:

data/api/client-server/support.yaml

@@ -22,9 +22,12 @@ paths:
       description: |-
         Gets server admin contact and support page of the domain.
 
-        Like the [well-known discovery URI](/client-server-api/#well-known-uri),
+        {{% boxes/note %}}
-        this should be accessed with the hostname of the homeserver by making a
+        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
         GET request to `https://hostname/.well-known/matrix/support`.
+        {{% /boxes/note %}}
 
         Note that this endpoint is not necessarily handled by the homeserver.
         It may be served by another webserver, used for discovering support

data/api/client-server/sync.yaml

@@ -441,17 +441,57 @@ paths:
                           "state": {
                             "events": [
                               {
-                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
+                                  "displayname": "Example user",
+                                  "membership": "join"
+                                },
+                                "event_id": "$143273976499sgjks:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "state_key": "@example:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 45603,
+                                  "membership": "join"
+                                }
                               }
                             ]
                           },
                           "timeline": {
                             "events": [
                               {
-                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
+                                  "displayname": "Alice Margatroid",
+                                  "membership": "join",
+                                  "reason": "Looking for support"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@alice:example.org",
+                                "state_key": "@alice:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
                               },
                               {
-                                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                                "content": {
+                                  "body": "This is an example text message",
+                                  "format": "org.matrix.custom.html",
+                                  "formatted_body": "<b>This is an example text message</b>",
+                                  "msgtype": "m.text"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "type": "m.room.message",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
                               }
                             ],
                             "limited": true,

data/api/client-server/third_party_membership.yaml

@@ -57,9 +57,6 @@ paths:
         - A signature of the token, signed with the identity server's private key
 
         - The matrix user ID who invited them to the room
-
-        If a token is requested from the identity server, the homeserver will
-        append a `m.room.third_party_invite` event to the room.
       operationId: inviteBy3PID
       security:
         - accessTokenQuery: []
@@ -72,41 +69,13 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
             schema:
-              type: object
+              $ref: definitions/invite_3pid.yaml
-              example: {
-                "id_server": "matrix.org",
-                "id_access_token": "abc123_OpaqueString",
-                "medium": "email",
-                "address": "cheeky@monkey.com"
-              }
-              properties:
-                id_server:
-                  type: string
-                  description: The hostname+port of the identity server which should be used for
-                    third-party identifier lookups.
-                id_access_token:
-                  type: string
-                  description: |-
-                    An access token previously registered with the identity server. Servers
-                    can treat this as optional to distinguish between r0.5-compatible clients
-                    and this specification version.
-                medium:
-                  type: string
-                  description: |-
-                    The kind of address being passed in the address field, for example
-                    `email` (see [the list of recognised values](/appendices/#3pid-types)).
-                address:
-                  type: string
-                  description: The invitee's third-party identifier.
-              required:
-                - id_server
-                - id_access_token
-                - medium
-                - address
         required: true
       responses:
         "200":
@@ -120,7 +89,9 @@ paths:
                   value: {}
         "403":
           description: |-
-            You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to invite the user to the room. A
+            meaningful `errcode` and description error text will be returned.
+            Example reasons for rejections are:
 
             - The invitee has been banned from the room.
             - The invitee is already a member of the room.

data/api/client-server/users.yaml

@@ -20,10 +20,17 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        Performs a search for users. The homeserver may
+        Performs a search for users. The homeserver may determine which
-        determine which subset of users are searched, however the homeserver
+        subset of users are searched. However, the homeserver MUST at a
-        MUST at a minimum consider the users the requesting user shares a
+        minimum consider users who are visible to the requester based
-        room with and those who reside in public rooms (known to the homeserver).
+        on their membership in rooms known to the homeserver. This means:
+
+        -   users that share a room with the requesting user
+        -   users who are joined to rooms known to the homeserver that have a
+            `public` [join rule](#mroomjoin_rules)
+        -   users who are joined to rooms known to the homeserver that have a
+            `world_readable` [history visibility](#room-history-visibility)
+        
         The search MUST consider local users to the homeserver, and SHOULD
         query remote users as part of the search.
 

data/api/client-server/wellknown.yaml

@@ -26,6 +26,12 @@ paths:
         suitably namespaced for each application and reduces the risk of
         clashes.
 
+        {{% boxes/note %}}
+        This endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/client`.
+        {{% /boxes/note %}}
+
         Note that this endpoint is not necessarily handled by the homeserver,
         but by another webserver, to be used for discovering the homeserver URL.
       operationId: getWellknown

data/api/identity/v2_pubkey.yaml

@@ -43,7 +43,8 @@ paths:
                 properties:
                   public_key:
                     type: string
-                    description: Unpadded Base64 encoded public key.
+                    description: |-
+                      [Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
                 required:
                   - public_key
               examples:
@@ -74,7 +75,8 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: The unpadded base64-encoded public key to check.
+          description: |-
+            The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
           example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
           schema:
             type: string
@@ -105,7 +107,14 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: The unpadded base64-encoded public key to check.
+          description: |-
+            The [unpadded Base64](/appendices/#unpadded-base64)-encoded public
+            key to check.
+
+            This MUST be the exact same encoded string returned in the response
+            of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
+            endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+            event, so it may use the standard or URL-safe alphabets.
           example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
           schema:
             type: string

data/api/identity/v2_store_invite.yaml

@@ -42,7 +42,7 @@ paths:
         (if present) from the request here.
 
         Also, the generated ephemeral public key will be listed as valid on
-        requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
+        requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
 
         Currently, invites may only be issued for 3pids of the `email` medium.
 
@@ -70,10 +70,14 @@ paths:
                 room_id:
                   type: string
                   description: The Matrix room ID to which the user is invited
+                  format: mx-room-id
+                  pattern: "^!"
                   example: "!something:example.org"
                 sender:
                   type: string
                   description: The Matrix user ID of the inviting user
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@bob:example.com"
                 room_alias:
                   type: string
@@ -81,12 +85,16 @@ paths:
                     The Matrix room alias for the room to which the user is
                     invited. This should be retrieved from the `m.room.canonical_alias`
                     state event.
+                  format: mx-room-alias
+                  pattern: "^#"
                   example: "#somewhere:example.org"
                 room_avatar_url:
                   type: string
                   description: |-
                     The Content URI for the room to which the user is invited. This should
                     be retrieved from the `m.room.avatar` state event.
+                  format: mx-mxc-uri
+                  pattern: "^mxc:\\/\\/"
                   example: mxc://example.org/s0meM3dia
                 room_join_rules:
                   type: string
@@ -108,6 +116,8 @@ paths:
                   type: string
                   description: The Content URI for the avatar of the user ID initiating the
                     invite.
+                  format: mx-mxc-uri
+                  pattern: "^mxc:\\/\\/"
                   example: mxc://example.org/an0th3rM3dia
                 room_type:
                   type: string
@@ -146,7 +156,7 @@ paths:
                         public_key:
                           type: string
                           description: |
-                            The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
+                            The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
                         key_validity_url:
                           type: string
                           description: |

data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml

@@ -0,0 +1,45 @@
+# 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
+description: |-
+  The auth_events and prev_events fields of PDUs for room version 4
+  and beyond.
+properties:
+  auth_events:
+    type: array
+    items:
+      type: string
+      description: Event ID.
+    description: |-
+      Event IDs for the authorization events that would
+      allow this event to be in the room.
+
+      Must contain less than or equal to 10 events. Note that if the relevant
+      auth event selection rules are used, this restriction should never be
+      encountered.
+    example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+  prev_events:
+    type: array
+    items:
+      type: string
+      description: Event ID.
+    description: |-
+      Event IDs for the most recent events in the room
+      that the homeserver was aware of when it made this event.
+
+      Must contain less than or equal to 20 events.
+    example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+required:
+  - auth_events
+  - prev_events

data/api/server-server/definitions/components/pdu_base.yaml

@@ -12,10 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-title: Unsigned Persistent Data Unit
+description: Common fields for all PDU versions
-description: An unsigned persistent data unit (event)
-example:
-  $ref: "../examples/unsigned_pdu_base.json"
 properties:
   room_id:
     type: string
@@ -44,49 +41,22 @@ properties:
     type: object
     description: The content of the event.
     example: {"key": "value"}
-  prev_events:
+  hashes:
-    type: array
+    $ref: "event_hash.yaml"
+  signatures:
+    type: object
     description: |-
-      Event IDs and reference hashes for the most recent events in the room
+      Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-      that the homeserver was aware of when it made this event.
+    example: {
-
+      "example.com": {
-      Must contain less than or equal to 20 events.
+        "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-    items:
+      }
-      type: array
+    }
-      maxItems: 2
+    additionalProperties:
-      minItems: 2
+      type: object
-      items:
+      title: Server Signatures
-        anyOf:
+      additionalProperties:
-          - type: string
+        type: string
-            title: Event ID
-            example: "$abc123:matrix.org"
-          - $ref: "event_hash.yaml"
-  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: |-
-      Event IDs and reference hashes for the authorization events that would
-      allow this event to be in the room.
-
-      Must contain less than or equal to 10 events. Note that if the relevant
-      auth event selection rules are used, this restriction should never be
-      encountered.
-    items:
-      type: array
-      maxItems: 2
-      minItems: 2
-      items:
-        anyOf:
-          - type: string
-            title: Event ID
-            example: "$abc123:matrix.org"
-          - $ref: "event_hash.yaml"
   unsigned:
     type: object
     title: UnsignedData
@@ -99,12 +69,11 @@ properties:
         description: The number of milliseconds that have passed since this message was sent.
         example: 4612
 required:
-  - event_id
   - room_id
   - sender
   - origin_server_ts
   - type
   - content
-  - prev_events
   - depth
-  - auth_events
+  - hashes
+  - signatures

data/api/server-server/definitions/pdu_v1.yaml

@@ -0,0 +1,77 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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 1 and 2.
+example:
+  $ref: "../examples/pdu_v1.json"
+allOf:
+  - $ref: "components/pdu_base.yaml"
+  - type: object
+    properties:
+      event_id:
+        type: string
+        description: The event ID for the PDU.
+        example: "$a4ecee13e2accdadf56c1025:example.com"
+      redacts:
+        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: |-
+          Event IDs and reference hashes for the authorization events that would
+          allow this event to be in the room.
+
+          Must contain less than or equal to 10 events. Note that if the relevant
+          auth event selection rules are used, this restriction should never be
+          encountered.
+        items:
+          type: array
+          maxItems: 2
+          minItems: 2
+          items:
+            anyOf:
+              - type: string
+                title: Event ID
+                example: "$abc123:matrix.org"
+              - $ref: "components/event_hash.yaml"
+      prev_events:
+        type: array
+        description: |-
+          Event IDs and reference hashes for the most recent events in the room
+          that the homeserver was aware of when it made this event.
+
+          Must contain less than or equal to 20 events.
+        items:
+          type: array
+          maxItems: 2
+          minItems: 2
+          items:
+            anyOf:
+              - type: string
+                title: Event ID
+                example: "$abc123:matrix.org"
+              - $ref: "components/event_hash.yaml"
+    required:
+      - event_id
+      - auth_events
+      - prev_events

data/api/server-server/definitions/pdu_v11.yaml

@@ -17,53 +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. Copy the auth_events/prev_events
+  # v11 is the v6 event, but without redacts.
-  # from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml.
+  - $ref: "components/pdu_base.yaml"
-  - $ref: "unsigned_pdu_base.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"
   - type: object
     properties:
-      auth_events:
+      # v6 enforces Canonical JSON and therefore needs a depth limit change
-        type: array
+      depth:
-        items:
+        type: integer
-          type: string
-          description: Event ID.
         description: |-
-          Event IDs for the authorization events that would
+          The maximum depth of the `prev_events`, plus one. Must be less than the
-          allow this event to be in the room.
+          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.
-          Must contain less than or equal to 10 events. Note that if the relevant
+        example: 12
-          auth event selection rules are used, this restriction should never be
-          encountered.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      prev_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the most recent events in the room
-          that the homeserver was aware of when it made this event.
-
-          Must contain less than or equal to 20 events.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      hashes:
-        $ref: "event_hash.yaml"
-      signatures:
-        type: object
-        description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "example.com": {
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
-    required:
-      - auth_events
-      - prev_events
-      - hashes
-      - signatures

data/api/server-server/definitions/pdu_v3.yaml

@@ -13,17 +13,24 @@
 # limitations under the License.
 type: object
 title: Persistent Data Unit
-description: A persistent data unit (event) for room version 3 and beyond.
+description: A persistent data unit (event) for room version 3.
 example:
   $ref: "../examples/pdu_v3.json"
 allOf:
-  - $ref: "unsigned_pdu_base.yaml"
+  - $ref: "components/pdu_base.yaml"
   - type: object
     properties:
       redacts:
         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:
@@ -48,24 +55,6 @@ allOf:
 
           Must contain less than or equal to 20 events.
         example: ["$base64EncodedHash", "$AnotherEvent"]
-      hashes:
-        $ref: "event_hash.yaml"
-      signatures:
-        type: object
-        description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "example.com": {
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
     required:
       - auth_events
       - prev_events
-      - hashes
-      - signatures

data/api/server-server/definitions/pdu_v4.yaml

@@ -13,41 +13,23 @@
 # limitations under the License.
 type: object
 title: Persistent Data Unit
-description: A persistent data unit (event) for room version 4 and beyond.
+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: "pdu_v3.yaml"
+  - $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"
-      auth_events:
+      depth:
-        type: array
+        type: integer
-        items:
-          type: string
-          description: Event ID.
         description: |-
-          Event IDs for the authorization events that would
+          The maximum depth of the `prev_events`, plus one. Must be less than the
-          allow this event to be in the room.
+          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.
-          Must contain less than or equal to 10 events. Note that if the relevant
+        example: 12
-          auth event selection rules are used, this restriction should never be
-          encountered.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      prev_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the most recent events in the room
-          that the homeserver was aware of when it made this event.
-
-          Must contain less than or equal to 20 events.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-    required:
-      - auth_events
-      - prev_events

data/api/server-server/definitions/pdu_v6.yaml

@@ -1,4 +1,4 @@
-# Copyright 2018 New Vector Ltd
+# 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.
@@ -13,33 +13,24 @@
 # limitations under the License.
 type: object
 title: Persistent Data Unit
-description: A persistent data unit (event) for room versions 1 and 2.
+description: |-
+  A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
 example:
-  $ref: "../examples/pdu.json"
+  $ref: "../examples/pdu_v4.json"
 allOf:
-  - $ref: "unsigned_pdu.yaml"
+  - $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: "$def456:matrix.org"
+        example: "$def_456-oldevent"
-      hashes:
+      # v6 enforces Canonical JSON and therefore needs a depth limit change
-        $ref: "event_hash.yaml"
+      depth:
-      signatures:
+        type: integer
-        type: object
         description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
+          The maximum depth of the `prev_events`, plus one. Must be less than the
-        example: {
+          maximum value for an integer (2^53 - 1). If the room's depth is already at
-          "example.com": {
+          the limit, the depth must be set to the limit.
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
+        example: 12
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
-    required:
-      - hashes
-      - signatures

data/api/server-server/definitions/unsigned_pdu.yaml

@@ -1,28 +0,0 @@
-# Copyright 2018-2019 New Vector Ltd
-#
-# 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: Unsigned Persistent Data Unit
-description: An unsigned persistent data unit (event)
-example:
-  $ref: "../examples/unsigned_pdu.json"
-allOf:
-  - $ref: "unsigned_pdu_base.yaml"
-  - type: object
-    properties:
-      event_id:
-        type: string
-        description: The event ID for the PDU.
-        example: "$a4ecee13e2accdadf56c1025:example.com"
-    required:
-      - event_id