.github/workflows/main.yml

@@ -2,7 +2,6 @@ name: "Spec"
 
 env:
   HUGO_VERSION: 0.139.0
-  PYTHON_VERSION: 3.13
 
 on:
   push:
@@ -41,7 +40,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: '3.9'
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -60,7 +59,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: '3.9'
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -79,7 +78,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: '3.9'
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -121,7 +120,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: '3.9'
           cache: 'pip'
           cache-dependency-path: scripts/requirements.txt
       - name: "➕ Install dependencies"
@@ -173,7 +172,7 @@ jobs:
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: '3.9'
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
@@ -284,11 +283,10 @@ 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: |
-          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
+          echo -e '[params.version]\nstatus="historical"' > historical.toml
+          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,19 +316,13 @@ Custom SCSS for the Matrix spec
   h2 {
     font-weight: $font-weight-bold;
     font-size: 1.3rem;
-    margin: 1.5rem 0 1rem 0;
+    margin: 3rem 0 .5rem 0;
   }
 
   h3 {
     font-weight: $font-weight-bold;
     font-size: 1.1rem;
-    margin: 1.5rem 0 1rem 0;
+    margin: 1.5rem 0 .75rem 0;
-
-  }
-
-  /* Reduce top margin of h3 if previous sibling is a h2 */
-  h2 + h3 {
-    margin-top: 1rem;
   }
 
   hr {
@@ -373,6 +367,11 @@ 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;
@@ -444,17 +443,6 @@ 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

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

changelogs/application_service/newsfragments/2130.feature

@@ -1 +0,0 @@
-Correct null value handling for the AS Registration's `url` property.

changelogs/client_server/newsfragments/2036.clarification

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

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

changelogs/client_server/newsfragments/2046.clarification

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

changelogs/client_server/newsfragments/2051.clarification

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

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

changelogs/client_server/newsfragments/2059.removal

@@ -0,0 +1 @@
+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/2064.clarification

@@ -0,0 +1 @@
+Clarify which rooms are returned from `/hierarchy`.

changelogs/client_server/newsfragments/2068.clarification

@@ -1 +0,0 @@
-Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

changelogs/client_server/newsfragments/2072.clarification

@@ -0,0 +1 @@
+Clients can choose which history visibility options they offer to users when creating rooms.

changelogs/client_server/newsfragments/2077.clarification

@@ -1 +0,0 @@
-Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

changelogs/client_server/newsfragments/2080.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/client_server/newsfragments/2091.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2095.feature

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

changelogs/client_server/newsfragments/2101.clarification

@@ -1 +0,0 @@
-"Public" rooms in profile look-ups are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2102.clarification

@@ -1 +0,0 @@
-"Public" rooms in user directory queries are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2106.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to call invites are defined through their join rule.

changelogs/client_server/newsfragments/2107.clarification

@@ -1 +0,0 @@
-"Public" rooms have no specific meaning with respect to moderation policy lists.

changelogs/client_server/newsfragments/2108.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to presence are defined through their join rule.

changelogs/client_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2144.clarification

@@ -1 +0,0 @@
-Fix typo: as->has.

changelogs/identity_service/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify that public keys can be encoded using standard or URL-safe base64.

changelogs/internal/newsfragments/2033.clarification

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

changelogs/internal/newsfragments/2041.clarification

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

changelogs/internal/newsfragments/2042.clarification

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

changelogs/internal/newsfragments/2045.clarification

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

changelogs/internal/newsfragments/2049.clarification

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

changelogs/internal/newsfragments/2061.clarification

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

changelogs/internal/newsfragments/2069.clarification

@@ -0,0 +1 @@
+Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials.

changelogs/internal/newsfragments/2073.clarification

@@ -0,0 +1 @@
+Deduplicate the definition of `RoomKeysUpdateResponse`.

changelogs/internal/newsfragments/2074.clarification

@@ -0,0 +1 @@
+Deduplicate the definitions of `Invite3pid`.

changelogs/internal/newsfragments/2076.clarification

@@ -0,0 +1 @@
+Support more locations for examples in OpenAPI definitions and JSON schemas.

changelogs/internal/newsfragments/2078.clarification

@@ -0,0 +1 @@
+Add link to the git commit for the unstable changelog.

changelogs/internal/newsfragments/2081.clarification

@@ -1 +0,0 @@
-Adjust margins in rendered endpoints.

changelogs/internal/newsfragments/2088.clarification

@@ -1 +0,0 @@
-Replace Hugo shortcodes in OpenAPI output.

changelogs/internal/newsfragments/2115.clarification

@@ -1 +0,0 @@
-Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2123.clarification

@@ -1 +0,0 @@
-Fix the historical info box when generating the historical spec in CI.

changelogs/room_versions/newsfragments/2065.clarification

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

changelogs/room_versions/newsfragments/2066.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

changelogs/room_versions/newsfragments/2070.clarification

@@ -0,0 +1 @@
+Refactor PDU definitions to reduce duplication.

changelogs/server_server/newsfragments/2050.clarification

@@ -0,0 +1 @@
+Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.

changelogs/server_server/newsfragments/2063.clarification

@@ -0,0 +1 @@
+Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`.

changelogs/server_server/newsfragments/2067.clarification

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

changelogs/server_server/newsfragments/2076.clarification

@@ -0,0 +1 @@
+Remove an erroneous `room_id` field in a few examples.

changelogs/server_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/server_server/newsfragments/2095.feature

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

changelogs/server_server/newsfragments/2100.clarification

@@ -1 +0,0 @@
-Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.

changelogs/server_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/server_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 # major = "1"
-# minor = "14"
+# minor = "13"
 
 # 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`.
 
-#### Published room directories
+#### Application service room directories
 
-Application services can maintain their own published room directories for
+Application services can maintain their own room directories for their
-their defined third-party protocols. These directories may be accessed by
+defined third-party protocols. These room directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 

content/changelog/v1.14.md

@@ -1,93 +0,0 @@
----
-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/client-server-api/_index.md

@@ -371,23 +371,15 @@ valid data was obtained, but no server is available to serve the client.
 No further guess should be attempted and the user should make a
 conscientious decision what to do next.
 
-### Well-known URIs
+### Well-known URI
-
-Matrix facilitates automatic discovery for the Client-Server API base URL and more via the
-[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) "Well-Known URI" method.
-This method uses JSON files at a predetermined location on the root path `/.well-known/` to
-specify parameter values.
 
 {{% boxes/note %}}
-Diverging from the rest of the endpoints in the Client-Server spec, these files can not be provided
-on the base URL that the Client-Server API is reachable on, as it is yet to be discovered.
-Instead, they can be reached via HTTPS on the [server name](/appendices/#server-name)'s hostname as domain.
-
 Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
 as per the [CORS](#web-browser-clients) section in this specification.
 {{% /boxes/note %}}
 
-The flow for auto-discovery is as follows:
+The `.well-known` method uses a JSON file at a predetermined location to
+specify parameter values. The flow for this method is as follows:
 
 1.  Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
     Matrix ID at the first colon.
@@ -423,17 +415,10 @@ The flow for auto-discovery is as follows:
 
 {{% http-api spec="client-server" api="wellknown" %}}
 
-{{% http-api spec="client-server" api="support" %}}
-
-### API Versions
-
-Upon connecting, the Matrix client and server need to negotiate which version of the specification
-they commonly support, as the API evolves over time. The server advertises its supported versions
-and optionally unstable features to the client, which can then go on to make requests to the
-endpoints it supports.
-
 {{% http-api spec="client-server" api="versions" %}}
 
+{{% http-api spec="client-server" api="support" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting
@@ -2846,35 +2831,7 @@ re-invited.
 
 {{% http-api spec="client-server" api="banning" %}}
 
-### Published room directory
+### Listing rooms
-
-Homeservers MAY publish a room directory to allow users to discover rooms. A room
-can have one of two visibility settings in the directory:
-
--   `public`: The room will be shown in the published room directory.
--   `private`: The room will be hidden from the published room directory.
-
-Clients can define a room's initial visibility in the directory via the `visibility`
-parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room
-creation, clients can query and change a room's visibility in the directory through
-the endpoints listed below, provided that the server permits this.
-
-{{% boxes/warning %}}
-The visibility setting merely defines whether a room is included in the published
-room directory or not. It doesn't make any guarantees about the room's
-[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility).
-
-In particular, a visibility setting of `public` should not be confused with a `public`
-join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published
-in the directory, too.
-
-Similarly, a visibility setting of `public` does not necessarily imply a `world_readable`
-history visibility.
-
-To increase performance or by preference, servers MAY apply additional filters when listing the
-directory, for instance, by automatically excluding rooms with `invite` join rules
-that are not `world_readable` regardless of their visibility.
-{{% /boxes/warning %}}
 
 {{% http-api spec="client-server" api="list_public_rooms" %}}
 
@@ -2890,15 +2847,10 @@ that are not `world_readable` regardless of their visibility.
 
 #### Server behaviour
 
-Homeservers MUST at a minimum allow profile look-up for users who are
+Homeservers MUST at a minimum allow profile look-up for:
-visible to the requester based 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
+-   users that reside in public rooms known to the homeserver
-    `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)
 
 In all other cases, homeservers MAY deny profile look-up by responding with
 403 and an error code of `M_FORBIDDEN`.

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 has already been accepted; instead, when Bob's other devices
+that the request as 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.
 

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

@@ -18,9 +18,8 @@ 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 in terms of
+restrictions on how the rooms can be configured (they could be public,
-[join rules](#mroomjoin_rules), [history visibility](#room-history-visibility),
+private, encrypted, etc).
-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,7 +68,5 @@ will cause the server to automatically set their presence to `online`.
 
 #### Security considerations
 
-Presence information is published to all users who share a room with the
+Presence information is shared with all users who share a room with the
-target user. If the target user is a member of a room with a `public`
+target user. In large public rooms this could be undesirable.
-[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,9 +29,3 @@ 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,10 +26,9 @@ on certain keys of certain event types.
 
 The supported keys to search over are:
 
--   `content.body` in [`m.room.message`](/client-server-api/#mroommessage)
+-   `content.body` in `m.room.message`
--   `content.name` in [`m.room.name`](/client-server-api/#mroomname)
+-   `content.name` in `m.room.name`
--   In [`m.room.topic`](/client-server-api/#mroomtopic), `content.topic`
+-   `content.topic` in `m.room.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 no default
+multiple keys should use the default key if one is specified. If not 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

@@ -18,10 +18,10 @@ 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`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
+govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
-and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
+and [`m.room.join_rules`](#mroomjoin_rules). Canonical aliases and invites, including
 third-party invites, still work just as they do in normal rooms as well. Furthermore,
-spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
+spaces can also be published in the [room directory](#room-directory) to make them
 discoverable.
 
 All other aspects of regular rooms are additionally carried over, such as the

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`](#thirdparty_post_matrixclientv3roomsroomidinvite)
+not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the
-with the details of the third-party identifier.
+third-party identifier.
 
 The homeserver asks the identity server whether a Matrix user ID is
 known for that identifier:
@@ -37,12 +37,10 @@ A client asks a server to invite a user by their third-party identifier.
 
 #### Server behaviour
 
-Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
+Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
-the server is expected to look up the third-party identifier with the provided
+third-party identifier with the provided identity server. If the lookup
-identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
+yields a result for a Matrix User ID then the normal invite process can
-If the lookup yields a result for a Matrix User ID then the normal [invite
+be initiated. This process ends up looking like this:
-process](/server-server-api/#inviting-to-a-room) can be initiated. This process
-ends up looking like this:
 
 ```
     +---------+                         +-------------+                                    +-----------------+
@@ -68,11 +66,10 @@ ends up looking like this:
         |                                     |                                                    |
 ```
 
-However, if the lookup does not yield a bound User ID, the homeserver must store
+However, if the lookup does not yield a bound User ID, the homeserver
-the invite on the identity server with a call to
+must store the invite on the identity server and emit a valid
-[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
+`m.room.third_party_invite` event to the room. This process ends up
-and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
+looking like this:
-to the room. This process ends up looking like this:
 
 ```
     +---------+                         +-------------+                                               +-----------------+
@@ -104,19 +101,16 @@ to the room. This process ends up looking like this:
         |                                     |                                                               |
 ```
 
-The third-party user will then need to verify their identity, which results in a
+All homeservers MUST verify the signature in the event's
-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).
-
-All homeservers MUST verify the signature in the `m.room.member` event's
 `content.third_party_invite.signed` object.
 
+The third-party user will then need to verify their identity, which
+results in a call 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` 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
 in the room (which is chosen as per the standard server-server
@@ -199,8 +193,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's
+done by making a request to the [identity server
-[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
+/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/voip_events.md

@@ -202,13 +202,11 @@ 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
+Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either
-where the `invitee` field is either absent or equal to their user's Matrix ID.
+absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
-They should, however, evaluate whether or not to ring based on their user's trust
+user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
-relationship with the callers and/or where the call was placed. As a starting
+suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
-point, it is RECOMMENDED that clients ignore call invites in rooms with a
+when clients do not ring for an incoming call invite, they still display the call invite in the room and
-[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/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 11** as
+room is running a stable version. Servers SHOULD use **room version 10** as
 the default room version when creating new rooms.
 
 The available room versions are:

content/rooms/fragments/v6-event-format.md

@@ -1,4 +0,0 @@
-
-Events in rooms of this version have the following structure:
-
-{{% definition path="api/server-server/definitions/pdu_v6" %}}

content/rooms/v10.md

@@ -281,7 +281,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v6-event-format" %}}
+{{% rver-fragment name="v4-event-format" %}}
 
 ### State resolution
 

content/rooms/v6.md

@@ -39,13 +39,6 @@ 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
@@ -236,6 +229,10 @@ 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

@@ -225,7 +225,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v6-event-format" %}}
+{{% rver-fragment name="v4-event-format" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v8.md

@@ -109,7 +109,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v6-event-format" %}}
+{{% rver-fragment name="v4-event-format" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v9.md

@@ -74,7 +74,7 @@ completeness.
 
 ### Event format
 
-{{% rver-fragment name="v6-event-format" %}}
+{{% rver-fragment name="v4-event-format" %}}
 
 #### Deprecated event content schemas
 

content/server-server-api.md

@@ -119,8 +119,7 @@ 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` (according to 
+    made to `https://<hostname>/.well-known/matrix/server`, expecting
-    [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
@@ -544,8 +543,8 @@ the following subset of the room state:
       `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 `membership` is `join`, `content.join_authorised_via_users_server`
+    - If `content.join_authorised_via_users_server` is present,
-      is present, and the [room version supports restricted rooms](/rooms/#feature-matrix),
+      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`.
 
@@ -971,8 +970,9 @@ the event to other servers in the room.
 ## Third-party invites
 
 {{% boxes/note %}}
-More information about third-party invites is available in the Client-Server API
+More information about third-party invites is available in the
-under the [Third-party invites](/client-server-api/#third-party-invites) module.
+[Client-Server API](/client-server-api) under
+the Third-party Invites module.
 {{% /boxes/note %}}
 
 When a user wants to invite another user in a room but doesn't know the
@@ -985,41 +985,38 @@ 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](/identity-service-api/#post_matrixidentityv2lookup) on the identity
+request on the identity server will return it. The invite is then
-server will return it. The invite is then processed by the inviting homeserver
+processed by the inviting homeserver as a standard `m.room.member`
-as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
+invite event. This is the simplest case.
-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](/identity-service-api/#invitation-storage)
+homeserver will request the identity server to store an invite for this
-for this identifier and to deliver it to whoever binds it to its Matrix ID. It
+identifier and to deliver it to whoever binds it to its Matrix ID. It
-will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+will also send an `m.room.third_party_invite` event in the room to
-event in the room to specify a display name, a token and public keys the
+specify a display name, a token and public keys the identity server
-identity server provided as a response to the invite storage request.
+provided as a response to the invite storage request.
 
-When a third-party identifier with pending invites gets bound to a Matrix ID,
+When a third-party identifier with pending invites gets bound to a
-the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
+Matrix ID, the identity server will send a POST request to the ID's
-endpoint of the the ID's homeserver as described in the [Invitation
+homeserver as described in the [Invitation
-Storage](/identity-service-api#invitation-storage) section of the Identity
+Storage](/identity-service-api#invitation-storage)
-Service API.
+section of the Identity Service API.
 
 The following process applies for each invite sent by the identity
 server:
 
-The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
+The invited homeserver will create an `m.room.member` invite event
-invite event containing a special `third_party_invite` section containing the
+containing a special `third_party_invite` section containing the token
-token and a `signed` object, both provided by the identity server.
+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 inviting homeserver to auth the event
+from, it will need to request the room's 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" %}}
 
@@ -1048,10 +1045,11 @@ 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.
 
-## Published Room Directory
+## Public Room Directory
 
-To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory), 
+To complement the [Client-Server
-homeservers need a way to query the published rooms of another server.
+API](/client-server-api)'s room directory,
+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.
 
@@ -1339,7 +1337,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`, `signatures`, and `hashes` properties are
+First, any existing `unsigned`, `signature`, and `hashes` members 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/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: ["null", "string"]
+    type: 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/appservice_room_directory.yaml

@@ -13,21 +13,18 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Application Service Published Room Directory API
+  title: Matrix Client-Server Application Service Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: |-
+      summary: Updates a room's visibility in the application service's room directory.
-        Updates a room's visibility in the application service's published room
-        directory.
       description: |-
-        Updates the visibility of a given room in the application service's
+        Updates the visibility of a given room on the application service's room
-        published room directory.
+        directory.
 
-        This API is similar to the
+        This API is similar to the room directory visibility API used by clients
-        [visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
+        to update the homeserver's more general room directory.
-        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,9 +87,12 @@ paths:
                     - public
                     - private
                   description: |-
-                    The room's visibility in the server's
+                    A `public` visibility indicates that the room will be shown
-                    [published room directory](/client-server-api#published-room-directory).
+                    in the published room list. A `private` visibility will hide
-                    Defaults to `private`.
+                    the room from the published room list. Rooms default to
+                    `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: |-
@@ -106,17 +109,15 @@ paths:
                 name:
                   type: string
                   description: |-
-                    If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
+                    If this is included, an `m.room.name` event will be sent
-                    will be sent into the room to indicate the name for the room.
+                    into the room to indicate the name of the room. See Room
-                    This overwrites any [`m.room.name`](/client-server-api/#mroomname)
+                    Events for more information on `m.room.name`.
-                    event in `initial_state`.
                 topic:
                   type: string
                   description: |-
-                    If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
+                    If this is included, an `m.room.topic` event will be sent
-                    event with a `text/plain` mimetype will be sent into the room
+                    into the room to indicate the topic for the room. See Room
-                    to indicate the topic for the room. This overwrites any
+                    Events for more information on `m.room.topic`.
-                    [`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
                 invite:
                   type: array
                   description: |-

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 type: object
-title: "PublishedRoomsChunk"
+title: "PublicRoomsChunk"
 properties:
   canonical_alias:
     type: string
@@ -33,9 +33,7 @@ properties:
     example: "!abcdefg:example.org"
   topic:
     type: string
-    description: |-
+    description: The topic of the room, if any.
-      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

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

@@ -13,15 +13,28 @@
 # limitations under the License.
 
 type: object
-description: A list of the published rooms on the server.
+description: A list of the rooms on the server.
 required: ["chunk"]
 properties:
   chunk:
     type: array
     description: |-
-      A paginated chunk of published rooms.
+      A paginated chunk of public rooms.
     items:
-      $ref: "public_rooms_chunk.yaml"
+      allOf:
+        - $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: |-
@@ -37,7 +50,7 @@ properties:
   total_room_count_estimate:
     type: integer
     description: |-
-        An estimate on the total number of published rooms, if the
+        An estimate on the total number of public rooms, if the
         server has an estimate.
 example: {
   "chunk": [

data/api/client-server/list_public_rooms.yaml

@@ -13,15 +13,14 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Published Room Directory API
+  title: Matrix Client-Server Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/room/{roomId}":
     get:
       summary: Gets the visibility of a room in the directory
-      description: |-
+      description: Gets the visibility of a given room on the server's public room
-        Gets the visibility of a given room in the server's
+        directory.
-        published room directory.
       operationId: getRoomVisibilityOnDirectory
       parameters:
         - in: path
@@ -33,7 +32,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:
@@ -51,7 +50,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:
@@ -65,13 +64,14 @@ paths:
       tags:
         - Room discovery
     put:
-      summary: Sets the visibility of a room in the directory
+      summary: Sets the visibility of a room in the room directory
       description: |-
-        Sets the visibility of a given room in the server's published room directory.
+        Sets the visibility of a given room in the server's public room
+        directory.
 
-        Servers MAY implement additional access control checks, for instance,
+        Servers may choose to implement additional access control checks
-        to ensure that a room's visibility can only be changed by the room creator
+        here, for instance that room visibility can only be changed by
-        or a server administrator.
+        the room creator 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 in the published room directory.
+        description: The new visibility for the room on the 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 a server's published room directory
+      summary: Lists the public rooms on the server.
       description: |-
-        Lists a server's published room directory.
+        Lists the public rooms on the server.
 
         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 published room directory from. Defaults
+            The server to fetch the public room lists from. Defaults to the
-            to the local server. Case sensitive.
+            local server. Case sensitive.
           schema:
             type: string
       responses:
         "200":
-          description: A list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:
@@ -168,9 +168,9 @@ paths:
       tags:
         - Room discovery
     post:
-      summary: Lists a server's published room directory with an optional filter
+      summary: Lists the public rooms on the server with optional filter.
       description: |-
-        Lists a server's published room directory with an optional filter.
+        Lists the public rooms on the server, with 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 published room directory from. Defaults
+            The server to fetch the public room lists from. Defaults to the
-            to the local server. Case sensitive.
+            local server. Case sensitive.
           schema:
             type: string
       requestBody:
@@ -253,7 +253,7 @@ paths:
         required: true
       responses:
         "200":
-          description: A filtered list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:

data/api/client-server/report_content.yaml

@@ -45,9 +45,7 @@ paths:
               properties:
                 reason:
                   type: string
-                  description: The reason the room is being reported. May be blank.
+                  description: The reason the room is being reported.
-              required:
-                - reason
         required: true
       security:
         - accessTokenQuery: []
@@ -90,11 +88,12 @@ 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.
-
+        
-        Furthermore, it might be possible for clients to deduce whether a reported
+        It might be possible for clients to deduce whether an event exists by
-        event exists by timing the response. This is because only a report for an
+        timing the response, as only a report for an event that does exist
-        existing event will require the homeserver to do further processing. To
+        will require the homeserver to check whether a user is joined to
-        combat this, homeservers MAY add a random delay when generating a response.
+        the room. To combat this, homeserver implementations should add
+        a random delay when generating a response.
       operationId: reportEvent
       parameters:
         - in: path
@@ -165,88 +164,6 @@ 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/support.yaml

@@ -22,12 +22,9 @@ paths:
       description: |-
         Gets server admin contact and support page of the domain.
 
-        {{% boxes/note %}}
+        Like the [well-known discovery URI](/client-server-api/#well-known-uri),
-        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this should be accessed with the hostname of the homeserver by making a
-        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,57 +441,17 @@ paths:
                           "state": {
                             "events": [
                               {
-                                "content": {
+                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
-                                  "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": [
                               {
-                                "content": {
+                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
-                                  "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"
-                                }
                               },
                               {
-                                "content": {
+                                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                                  "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,6 +57,9 @@ 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: []
@@ -69,8 +72,6 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
-            format: mx-room-id
-            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -89,9 +90,7 @@ paths:
                   value: {}
         "403":
           description: |-
-            You do not have permission to invite the user to the room. A
+            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:
-            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,17 +20,10 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        Performs a search for users. The homeserver may determine which
+        Performs a search for users. The homeserver may
-        subset of users are searched. However, the homeserver MUST at a
+        determine which subset of users are searched, however the homeserver
-        minimum consider users who are visible to the requester based
+        MUST at a minimum consider the users the requesting user shares a
-        on their membership in rooms known to the homeserver. This means:
+        room with and those who reside in public rooms (known to the homeserver).
-
-        -   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,12 +26,6 @@ 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,8 +43,7 @@ paths:
                 properties:
                   public_key:
                     type: string
-                    description: |-
+                    description: Unpadded Base64 encoded public key.
-                      [Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
                 required:
                   - public_key
               examples:
@@ -75,8 +74,7 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: |-
+          description: The unpadded base64-encoded public key to check.
-            The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
           example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
           schema:
             type: string
@@ -107,14 +105,7 @@ paths:
         - in: query
           name: public_key
           required: true
-          description: |-
+          description: The unpadded base64-encoded public key to check.
-            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`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
+        requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
 
         Currently, invites may only be issued for 3pids of the `email` medium.
 
@@ -70,14 +70,10 @@ 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
@@ -85,16 +81,12 @@ 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
@@ -116,8 +108,6 @@ 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
@@ -156,7 +146,7 @@ paths:
                         public_key:
                           type: string
                           description: |
-                            The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
+                            The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
                         key_validity_url:
                           type: string
                           description: |

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

@@ -41,6 +41,13 @@ properties:
     type: object
     description: The content of the event.
     example: {"key": "value"}
+  depth:
+    type: integer
+    description: |-
+      The maximum depth of the `prev_events`, plus one. Must be less than the
+      maximum value for an integer (2^63 - 1). If the room's depth is already at
+      the limit, the depth must be set to the limit.
+    example: 12
   hashes:
     $ref: "event_hash.yaml"
   signatures:

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

@@ -28,13 +28,6 @@ allOf:
         type: string
         description: For redaction events, the ID of the event being redacted.
         example: "$def456:matrix.org"
-      depth:
-        type: integer
-        description: |-
-          The maximum depth of the `prev_events`, plus one. Must be less than the
-          maximum value for an integer (2^63 - 1). If the room's depth is already at
-          the limit, the depth must be set to the limit.
-        example: 12
       auth_events:
         type: array
         description: |-

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

@@ -17,16 +17,6 @@ description: A persistent data unit (event) for room version 11 and beyond.
 example:
   $ref: "../examples/pdu_v11.json"
 allOf:
-  # v11 is the v6 event, but without redacts.
+  # v11 is the v4 event, but without redacts.
   - $ref: "components/pdu_base.yaml"
-  - $ref: "components/auth_events_prev_events_v4.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"
-  - type: object
-    properties:
-      # v6 enforces Canonical JSON and therefore needs a depth limit change
-      depth:
-        type: integer
-        description: |-
-          The maximum depth of the `prev_events`, plus one. Must be less than the
-          maximum value for an integer (2^53 - 1). If the room's depth is already at
-          the limit, the depth must be set to the limit.
-        example: 12

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

@@ -24,13 +24,6 @@ allOf:
         type: string
         description: For redaction events, the ID of the event being redacted.
         example: "$def/456+oldevent"
-      depth:
-        type: integer
-        description: |-
-          The maximum depth of the `prev_events`, plus one. Must be less than the
-          maximum value for an integer (2^63 - 1). If the room's depth is already at
-          the limit, the depth must be set to the limit.
-        example: 12
       auth_events:
         type: array
         items:

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

@@ -26,10 +26,3 @@ allOf:
         type: string
         description: For redaction events, the ID of the event being redacted.
         example: "$def_456-oldevent"
-      depth:
-        type: integer
-        description: |-
-          The maximum depth of the `prev_events`, plus one. Must be less than the
-          maximum value for an integer (2^63 - 1). If the room's depth is already at
-          the limit, the depth must be set to the limit.
-        example: 12

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

@@ -1,36 +0,0 @@
-# Copyright 2025 The Matrix.org Foundation C.I.C.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-type: object
-title: Persistent Data Unit
-description: |-
-  A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
-example:
-  $ref: "../examples/pdu_v4.json"
-allOf:
-  - $ref: "components/pdu_base.yaml"
-  - $ref: "components/auth_events_prev_events_v4.yaml"
-  - type: object
-    properties:
-      redacts:
-        type: string
-        description: For redaction events, the ID of the event being redacted.
-        example: "$def_456-oldevent"
-      # v6 enforces Canonical JSON and therefore needs a depth limit change
-      depth:
-        type: integer
-        description: |-
-          The maximum depth of the `prev_events`, plus one. Must be less than the
-          maximum value for an integer (2^53 - 1). If the room's depth is already at
-          the limit, the depth must be set to the limit.
-        example: 12

data/api/server-server/invites-v1.yaml

@@ -20,7 +20,7 @@ paths:
     put:
       summary: Invites a remote user to a room
       description: |-
-        Invites a remote user to a room. Once the event has been signed by both the inviting
+        Invites a remote user to a room. Once the event has been  signed by both the inviting
         homeserver and the invited homeserver, it can be sent to all of the servers in the
         room by the inviting homeserver.
 
@@ -32,10 +32,6 @@ paths:
         [room version specification](/rooms) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
-
-        Also note that if the remote homeserver is already in the room, it will receive the
-        invite event twice; once through this endpoint, and again through a [federation
-        transaction](/server-server-api/#transactions).
       operationId: sendInviteV1
       security:
         - signedRequest: []

data/api/server-server/invites-v2.yaml

@@ -24,7 +24,7 @@ paths:
         This API is nearly identical to the v1 API with the exception of the request
         body being different, and the response format fixed.
 
-        Invites a remote user to a room. Once the event has been signed by both the inviting
+        Invites a remote user to a room. Once the event has been  signed by both the inviting
         homeserver and the invited homeserver, it can be sent to all of the servers in the
         room by the inviting homeserver.
 
@@ -36,10 +36,6 @@ paths:
         [room version specification](/rooms) for precise event formats. **The request and response
         bodies here describe the common event fields in more detail and may be missing other
         required fields for a PDU.**
-
-        Also note that if the remote homeserver is already in the room, it will receive the
-        invite event twice; once through this endpoint, and again through a [federation
-        transaction](/server-server-api/#transactions).
       operationId: sendInviteV2
       security:
         - signedRequest: []

data/api/server-server/public_rooms.yaml

@@ -13,20 +13,16 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Federation Published Room Directory API
+  title: Matrix Federation Public Rooms API
   version: 1.0.0
 paths:
   /publicRooms:
     get:
-      summary: Lists the server's published room directory
+      summary: Get all the public rooms for a homeserver
       description: |-
-        Lists the server's published room directory.
+        Gets all the public rooms for the homeserver. This should not return
-
+        rooms that are listed on another homeserver's directory, just those
-        This API returns paginated responses. The rooms are ordered by the number
+        listed on the receiving homeserver's directory.
-        of joined members, with the largest rooms first.
-
-        This SHOULD not return rooms that are listed on another homeserver's directory,
-        just those listed on the receiving homeserver's directory.
       operationId: getPublicRooms
       security:
         - signedRequest: []
@@ -66,18 +62,21 @@ paths:
             type: string
       responses:
         "200":
-          description: A list of the published rooms on the server.
+          description: The public room list for the homeserver.
           content:
             application/json:
               schema:
                 $ref: ../client-server/definitions/public_rooms_response.yaml
     post:
-      summary: Lists the server's published room directory with an optional filter
+      summary: Gets the public rooms on the server with optional filter.
       description: |-
-        Lists the server's published room directory with an optional filter.
+        Lists the public rooms on the server, with optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
+
+        Note that this endpoint receives and returns the same format that is seen
+        in the Client-Server API's `POST /publicRooms` endpoint.
       operationId: queryPublicRooms
       security:
         - signedRequest: []
@@ -148,11 +147,69 @@ paths:
         required: true
       responses:
         "200":
-          description: A filtered list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:
-                $ref: ../client-server/definitions/public_rooms_response.yaml
+                type: object
+                description: A list of the rooms on the server.
+                required:
+                  - chunk
+                properties:
+                  chunk:
+                    title: PublicRoomsChunks
+                    type: array
+                    description: A paginated chunk of public rooms.
+                    items:
+                      allOf:
+                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                        - type: object
+                          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.
+                  next_batch:
+                    type: string
+                    description: |-
+                      A pagination token for the response. The absence of this token
+                      means there are no more results to fetch and the client should
+                      stop paginating.
+                  prev_batch:
+                    type: string
+                    description: |-
+                      A pagination token that allows fetching previous results. The
+                      absence of this token means there are no results before this
+                      batch, i.e. this is the first batch.
+                  total_room_count_estimate:
+                    type: integer
+                    description: |-
+                      An estimate on the total number of public rooms, if the
+                      server has an estimate.
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
+                        "guest_can_join": false,
+                        "name": "CHEESE",
+                        "num_joined_members": 37,
+                        "room_id": "!ol19s:bleecker.street",
+                        "topic": "Tasty tasty cheese",
+                        "world_readable": true,
+                        "join_rule": "public",
+                        "room_type": "m.space"
+                      }
+                    ],
+                    "next_batch": "p190q",
+                    "prev_batch": "p1902",
+                    "total_room_count_estimate": 115
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables: