Break long ling

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

.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"
@@ -172,7 +173,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 +284,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/application_service/newsfragments/2130.feature

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

changelogs/client_server/newsfragments/2068.clarification

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

changelogs/client_server/newsfragments/2077.clarification

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

changelogs/client_server/newsfragments/2083.clarification

@@ -0,0 +1,2 @@
+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/2095.feature

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

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

changelogs/client_server/newsfragments/2102.clarification

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

changelogs/client_server/newsfragments/2104.clarification

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

changelogs/client_server/newsfragments/2106.clarification

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

changelogs/client_server/newsfragments/2107.clarification

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

changelogs/client_server/newsfragments/2108.clarification

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

changelogs/client_server/newsfragments/2109.clarification

@@ -0,0 +1 @@
+Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2121.clarification

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

changelogs/client_server/newsfragments/2122.feature

@@ -0,0 +1 @@
+Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2125.feature

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

changelogs/client_server/newsfragments/2140.clarification

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

changelogs/client_server/newsfragments/2144.clarification

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

changelogs/identity_service/newsfragments/2083.clarification

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

changelogs/internal/newsfragments/2081.clarification

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

changelogs/internal/newsfragments/2088.clarification

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

changelogs/internal/newsfragments/2115.clarification

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

changelogs/internal/newsfragments/2123.clarification

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

changelogs/internal/newsfragments/2137.clarification

@@ -0,0 +1 @@
+Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2067.clarification

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

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

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

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

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

changelogs/server_server/newsfragments/2125.feature

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

changelogs/server_server/newsfragments/2128.clarification

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

changelogs/server_server/newsfragments/2140.clarification

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

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]

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/client-server-api/_index.md

@@ -371,15 +371,23 @@ 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 URI
+### Well-known URIs
+
+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 `.well-known` method uses a JSON file at a predetermined location to
+The flow for auto-discovery is as follows:
-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.
@@ -415,10 +423,17 @@ specify parameter values. The flow for this method is as follows:
 
 {{% http-api spec="client-server" api="wellknown" %}}
 
-{{% http-api spec="client-server" api="versions" %}}
-
 {{% 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" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting
@@ -2831,10 +2846,42 @@ re-invited.
 
 {{% http-api spec="client-server" api="banning" %}}
 
-### Listing rooms
+### Published room directory
+
+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" %}}
 
+### Room Summaries
+
+{{% http-api spec="client-server" api="room_summary" %}}
+
 ## User Data
 
 ### User Directory
@@ -2847,10 +2894,15 @@ re-invited.
 
 #### Server behaviour
 
-Homeservers MUST at a minimum allow profile look-up for:
+Homeservers MUST at a minimum allow profile look-up for users who are
+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 that reside in public rooms known to the homeserver
+-   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)
 
 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 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.
 
@@ -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/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/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/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/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/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
@@ -543,8 +544,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 `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/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/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: |-

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 type: object
-title: "PublicRoomsChunk"
+title: "PublishedRoomsChunk"
 properties:
   canonical_alias:
     type: string
@@ -33,7 +33,9 @@ properties:
     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

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,49 @@
+# 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.
+        x-addedInMatrixVersion: "1.4"
+      allowed_room_ids:
+        type: array
+        items:
+          type: string
+        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
+
+required:
+  - room_id
+  - num_joined_members
+  - world_readable
+  - guest_can_join

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/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:
+            type: string
+        - 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
+      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:
+                      room_type:
+                        x-addedInMatrixVersion: # Overrides room_summary.yaml
+                      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
+                required:
+                  - guest_can_join
+                  - num_joined_members
+                  - room_id
+                  - world_readable
+              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/space_hierarchy.yaml

@@ -102,15 +102,10 @@ paths:
                        * 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: |-
@@ -130,6 +125,12 @@ paths:
                                         description: The `origin_server_ts` for the event.
                                     required:
                                       - origin_server_ts
+                            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,6 +69,8 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -90,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/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,6 +32,10 @@ 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,6 +36,10 @@ 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,16 +13,20 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Federation Public Rooms API
+  title: Matrix Federation Published Room Directory API
   version: 1.0.0
 paths:
   /publicRooms:
     get:
-      summary: Get all the public rooms for a homeserver
+      summary: Lists the server's published room directory
       description: |-
-        Gets all the public rooms for the homeserver. This should not return
+        Lists the server's published room directory.
-        rooms that are listed on another homeserver's directory, just those
+
-        listed on the receiving homeserver's directory.
+        This API returns paginated responses. The rooms are ordered by the number
+        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: []
@@ -62,21 +66,18 @@ paths:
             type: string
       responses:
         "200":
-          description: The public room list for the homeserver.
+          description: A list of the published rooms on the server.
           content:
             application/json:
               schema:
                 $ref: ../client-server/definitions/public_rooms_response.yaml
     post:
-      summary: Gets the public rooms on the server with optional filter.
+      summary: Lists the server's published room directory with an optional filter
       description: |-
-        Lists the public rooms on the server, with optional filter.
+        Lists the 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.
-
-        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: []
@@ -147,69 +148,11 @@ 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:
-                type: object
+                $ref: ../client-server/definitions/public_rooms_response.yaml
-                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:

data/api/server-server/space_hierarchy.yaml

@@ -61,22 +61,10 @@ paths:
                   room:
                     description: A summary of the room requested.
                     allOf:
-                      - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                      - $ref: ../client-server/definitions/room_summary.yaml
                       - type: object
                         title: SpaceHierarchyParentRoom
                         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
-                            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.
                           children_state:
                             type: array
                             description: |-
@@ -96,6 +84,10 @@ paths:
                                       description: The `origin_server_ts` for the event.
                                   required:
                                     - origin_server_ts
+                          encryption:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                          room_version:
+                            x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
                         required:
                           - children_state
                   children:
@@ -105,22 +97,14 @@ paths:
                       be excluded.
                     items:
                       allOf:
-                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                        - $ref: ../client-server/definitions/room_summary.yaml
                         - type: object
                           title: SpaceHierarchyChildRoomsChunk
                           properties:
-                            room_type:
+                            encryption:
-                              type: string
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                              description: The `type` of room (from
+                            room_version:
-                                [`m.room.create`](/client-server-api/#mroomcreate)),
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
-                                if any.
-                            allowed_room_ids:
-                              type: array
-                              items:
-                                type: string
-                              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.
                   inaccessible_children:
                     type: array
                     items:

data/api/server-server/third_party_invite.yaml

@@ -35,6 +35,8 @@ paths:
           example: "!abc123:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -50,16 +52,22 @@ paths:
                   description: |-
                     The room ID the event is for. Must match the ID given in
                     the path.
+                    format: mx-room-id
+                    pattern: "^!"
                   example: "!abc123:matrix.org"
                 sender:
                   type: string
                   description: |-
                     The user ID of the user who sent the original `m.room.third_party_invite`
                     event.
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@joe:matrix.org"
                 state_key:
                   type: string
                   description: The user ID of the invited user
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@someone:example.org"
                 content:
                   type: object
@@ -82,45 +90,7 @@ paths:
                             third-party identifier.
                           example: alice
                         signed:
-                          type: object
+                          $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
-                          description: |-
-                            A block of content which has been signed, which servers can use to
-                            verify the event.
-                          title: Invite Signatures
-                          properties:
-                            signatures:
-                              type: object
-                              title: Signatures
-                              additionalProperties:
-                                type: object
-                                additionalProperties:
-                                  type: string
-                              description: |-
-                                The server signatures for this event.
-
-                                The signature is calculated using the process
-                                described at [Signing JSON](/appendices/#signing-json).
-                              example:
-                                magic.forest:
-                                  ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
-                            mxid:
-                              type: string
-                              description: The invited matrix user ID
-                              example: "@alice:localhost"
-                            token:
-                              type: string
-                              description: The token used to verify the event
-                              example: abc123
-                          required:
-                            - signatures
-                            - mxid
-                            - token
-                          example:
-                            mxid: "@alice:localhost"
-                            token: abc123
-                            signatures:
-                              magic.forest:
-                                ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg
                       required:
                         - display_name
                         - signed
@@ -215,6 +185,8 @@ paths:
                 mxid:
                   type: string
                   description: The user that is now bound to the third-party identifier.
+                  format: mx-user-id
+                  pattern: "^@"
                   example: "@alice:matrix.org"
                 invites:
                   type: array
@@ -237,59 +209,23 @@ paths:
                       mxid:
                         type: string
                         description: The now-bound user ID that received the invite.
+                        format: mx-user-id
+                        pattern: "^@"
                         example: "@alice:matrix.org"
                       room_id:
                         type: string
                         description: The room ID the invite is valid for.
+                        format: mx-room-id
+                        pattern: "^!"
                         example: "!somewhere:example.org"
                       sender:
                         type: string
                         description: The user ID that sent the invite.
+                        format: mx-user-id
+                        pattern: "^@"
                         example: "@bob:matrix.org"
-                      # TODO (TravisR): Make this reusable when doing IS spec changes
-                      #   also make sure it isn't lying about anything, like the key version
                       signed:
-                        type: object
+                        $ref: ../../event-schemas/schema/components/signed_third_party_invite.yaml
-                        title: Identity Server Signatures
-                        description: |-
-                          Signature from the identity server using a long-term private
-                          key.
-                        properties:
-                          mxid:
-                            type: string
-                            description: |-
-                              The user ID that has been bound to the third-party
-                              identifier.
-                            example: "@alice:matrix.org"
-                          token:
-                            type: string
-                            # TODO: What is this actually?
-                            description: A token.
-                            example: Hello World
-                          signatures:
-                            type: object
-                            title: Identity Server Signature
-                            description: |-
-                              The signature from the identity server. The `string` key
-                              is the identity server's domain name, such as vector.im
-                            additionalProperties:
-                              type: object
-                              title: Identity Server Domain Signature
-                              description: The signature for the identity server.
-                              properties:
-                                ed25519:0:
-                                  type: string
-                                  description: The signature.
-                                  example: SomeSignatureGoesHere
-                              required:
-                                - ed25519:0
-                            example:
-                              vector.im:
-                                ed25519:0: SomeSignatureGoesHere
-                        required:
-                          - mxid
-                          - token
-                          - signatures
                     required:
                       - medium
                       - address

data/api/server-server/wellknown.yaml

@@ -24,6 +24,12 @@ paths:
         Gets information about the delegated server for server-server communication
         between Matrix homeservers. Servers should follow 30x redirects, carefully
         avoiding redirect loops, and use normal X.509 certificate validation.
+
+        {{% 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/server`.
+        {{% /boxes/note %}}
       operationId: getWellKnown
       responses:
         "200":

data/event-schemas/examples/m.room.member.yaml

@@ -1,6 +1,7 @@
 {
   "$ref": "core/state_event.json",
   "state_key": "@alice:example.org",
+  "sender": "@alice:example.org",
   "type": "m.room.member",
   "content": {
     "membership": "join",

data/event-schemas/examples/m.room.topic.yaml

@@ -3,6 +3,14 @@
   "type": "m.room.topic",
   "state_key": "",
   "content": {
-    "topic": "A room topic"
+    "m.topic": {
+      "m.text": [ {
+        "mimetype": "text/html",
+        "body": "An <em>interesting</em> room topic"
+      }, {
+        "body": "An interesting room topic"
+      }]
+    },
+    "topic": "An interesting room topic"
   }
 }

data/event-schemas/schema/components/m_text_content_block.yaml

@@ -0,0 +1,28 @@
+type: array
+description: |-
+  An ordered array of textual representations in different mimetypes.
+
+  Senders SHOULD specify at least one representation and SHOULD always
+  include a plaintext representation.
+  
+  Receivers SHOULD use the first representation in the array that
+  they understand.
+title: TextContentBlock
+items:
+  type: object
+  title: TextualRepresentation
+  properties:
+    mimetype:
+      type: string
+      description: The mimetype. Defaults to `text/plain` if omitted.
+      example: "text/html"
+    body:
+      type: string
+      description: |-
+        The string content.
+
+        Clients SHOULD validate and sanitize the content as they do
+        for rich content associated with [`msgtype`](/client-server-api/#mroommessage-msgtypes)
+        of [`m.room.message`](/client-server-api/#mroommessage).
+  required:
+  - body

data/event-schemas/schema/components/signed_third_party_invite.yaml

@@ -0,0 +1,45 @@
+title: SignedThirdPartyInvite
+description: |-
+  A block of content which has been signed by the identity server, which
+  homeservers can use to verify the event. Clients should ignore this.
+type: object
+properties:
+  mxid:
+    description: |-
+      The user ID that has been bound to the third-party identifier.
+    type: string
+    format: mx-user-id
+    pattern: "^@"
+    example: "@alice:example.org"
+  signatures:
+    title: IdentityServerSignatures
+    description: |-
+      The identity server signatures for this block. This is a map of identity
+      server name to signing key identifier to base64-encoded signature.
+
+      The signatures are calculated using the process described at
+      [Signing JSON](/appendices/#signing-json).
+    type: object
+    additionalProperties:
+      type: object
+      additionalProperties:
+        type: string
+    example: {
+      "magic.forest": {
+        "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
+      }
+    }
+  token:
+    description: |-
+      The token generated by the identity server at the
+      [`/store_invite`](/identity-service-api/#post_matrixidentityv2store-invite)
+      endpoint.
+
+      It matches the `state_key` of the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+      event.
+    type: string
+    example: "abc123"
+required:
+  - mxid
+  - signatures
+  - token

data/event-schemas/schema/m.room.member.yaml

@@ -2,17 +2,27 @@
 allOf:
   - $ref: core-event-schema/state_event.yaml
 description: |-
-  Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
+  Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
+  (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
+  state directly as there are a restricted set of valid transformations. For example, user A cannot
+  force user B to join a room, and trying to force this state change directly will fail.
 
   The following membership states are specified:
 
-  - `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
+  - `invite` - The user has been invited to join a room, but has not yet joined it. They may not
-  - `join` - The user has joined the room (possibly after accepting an invite), and may participate in it.
+    participate in the room until they join.
-  - `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
+  - `join` - The user has joined the room (possibly after accepting an invite), and may participate
-  - `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`).
+    in it.
-  - `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join.
+  - `leave` - The user was once joined to the room, but has since left (possibly by choice, or
+    possibly by being kicked).
+  - `ban` - The user has been banned from the room, and is no longer allowed to join it until they
+    are un-banned from the room (by having their membership state set to a value other than `ban`).
+  - `knock` - The user has knocked on the room, requesting permission to participate. They may not
+    participate in the room until they join.
 
-  The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise.
+  The `third_party_invite` property will be set if this invite is an `invite` event and is the
+  successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
+  and absent otherwise.
 
   This event may also include an `invite_room_state` key inside the event's `unsigned` data.
   If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
@@ -57,63 +67,54 @@ properties:
           - ban
         type: string
       is_direct:
-        description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
+        description: |-
+          Flag indicating if the room containing this event was created with the intention of being
+          a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
         type: boolean
       join_authorised_via_users_server:
         x-addedInMatrixVersion: "1.2"
         type: string
         description: |-
-          Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level)
+          Usually found on `join` events, this field is used to denote which homeserver (through
-          authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
+          representation of a user with sufficient power level) authorised the user's join. More
+          information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
 
-          Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this
+          Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
-          field in further events: in particular, the event must be signed by the server which
+          of including this field in further events: in particular, the event must be signed by the
-          owns the user ID in the field. When copying the membership event's `content`
+          server which owns the user ID in the field. When copying the membership event's `content`
-          (for profile updates and similar) it is therefore encouraged to exclude this
+          (for profile updates and similar) it is therefore encouraged to exclude this field in the
-          field in the copy, as otherwise the event might fail event authorization.
+          copy, as otherwise the event might fail event authorization.
       reason:
         x-addedInMatrixVersion: "1.1"
         type: string
         description: |-
-          Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
+          Optional user-supplied text for why their membership has changed. For kicks and bans,
-          For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such
+          this is typically the reason for the kick or ban. For other membership changes, this is a
-          as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day.
+          way for the user to communicate their intent without having to send a message to the
+          room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
+          but can't make it that day.
 
-          Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the
+          Clients are not recommended to show this reason to users when receiving an invite due to
-          reason behind a button or other component is recommended.
+          the potential for spam and abuse. Hiding the reason behind a button or other component is
+          recommended.
       third_party_invite:
+        title: ThirdPartyInvite
+        description: |-
+          A third-party invite, if this `m.room.member` is the successor to an
+          [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+          event.
+        type: object
         properties:
           display_name:
-            description: A name which can be displayed to represent the user instead of their third-party identifier
+            description: |-
+              A name which can be displayed to represent the user instead of their
+              third-party identifier
             type: string
           signed:
-            description: 'A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.'
+            $ref: components/signed_third_party_invite.yaml
-            properties:
-              mxid:
-                description: The invited matrix user ID. Must be equal to the user_id property of the event.
-                type: string
-              signatures:
-                description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
-                title: Signatures
-                type: object
-                additionalProperties:
-                  type: object
-                  additionalProperties:
-                    type: string
-              token:
-                description: The token property of the containing third_party_invite object.
-                type: string
-            required:
-              - mxid
-              - signatures
-              - token
-            title: signed
-            type: object
         required:
           - display_name
           - signed
-        title: Invite
-        type: object
     required:
       - membership
     title: EventContent

data/event-schemas/schema/m.room.third_party_invite.yaml

@@ -1,28 +1,56 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: "Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
+description: |-
+  Acts as an `m.room.member` invite event, where there isn't a target user_id to
+  invite. This event contains a token and a public key whose private key must be
+  used to sign the token. Any user who can present that signature may use this
+  invitation to join the target room.
 properties:
   content:
     properties:
       display_name:
-        description: "A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID."
+        description: |-
+          A user-readable string which represents the user who has been invited.
+          This should not contain the user's third-party ID, as otherwise when
+          the invite is accepted it would leak the association between the
+          matrix ID and the third-party ID.
         type: string
       key_validity_url:
-        description: "A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
+        description: |-
+          A URL which can be fetched, with querystring public_key=public_key, to
+          validate whether the key has been revoked. The URL must return a JSON
+          object containing a boolean property named 'valid'.
         type: string
+        format: uri
       public_key:
-        description: A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility.
+        description: |-
+          An Ed25519 key with which the token must be signed (though a signature
+          from any entry in `public_keys` is also sufficient).
+
+          The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
+          using the standard or URL-safe alphabets.
+
+          This exists for backwards compatibility.
         type: string
       public_keys:
         description: Keys with which the token may be signed.
         items:
           properties:
             key_validity_url:
-              description: "An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely."
+              description: |-
+                An optional URL which can be fetched, with querystring
+                `public_key=<public_key>`, to validate whether the key has been
+                revoked. The URL must return a JSON object containing a boolean
+                property named `valid`. If this URL is absent, the key must be
+                considered valid indefinitely.
               type: string
             public_key:
-              description: A base-64 encoded ed25519 key with which token may be signed.
+              description: |-
+                An Ed25519 key with which the token may be signed.
+
+                The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
+                using the standard or URL-safe alphabets.
               type: string
           required:
             - public_key
@@ -35,11 +63,15 @@ properties:
       - public_key
     type: object
   state_key:
-    description: 'The token, of which a signature must be produced in order to join the room.'
+    description: |-
+      The token, of which a signature must be produced in order to join the
+      room.
     type: string
   type:
     enum:
       - m.room.third_party_invite
     type: string
-title: 'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.'
+title: |-
+  An invitation to a room issued to a third-party identifier, rather than a
+  matrix user ID.
 type: object

data/event-schemas/schema/m.room.topic.yaml

@@ -1,13 +1,41 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: 'A topic is a short message detailing what is currently being discussed in the room.  It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
+description: |-
+    A topic is a short message detailing what is currently being discussed
+    in the room.  It can also be used as a way to display extra information
+    about the room, which may not be suitable for the room name. The room
+    topic can also be set when creating a room using
+    [`/createRoom`](client-server-api/#post_matrixclientv3createroom), either
+    with the `topic` key or by specifying a full event in `initial_state`.
+  
+    If the `topic` property is absent, null, or empty then the topic is unset. In other words,
+    an empty `topic` property effectively resets the room to having no topic.
+
+    In order to prevent formatting abuse in room topics, clients SHOULD
+    limit the length of topics during both entry and display, for instance,
+    by capping the number of displayed lines. Additionally, clients SHOULD
+    ignore things like headings and enumerations (or format them as regular
+    text).
 properties:
   content:
     properties:
       topic:
-        description: The topic text.
+        description: |-
+          The topic in plain text.
+
+          This SHOULD duplicate the content of the `text/plain`
+          representation in `m.topic` if any exists.
         type: string
+      m.topic:
+        type: object
+        title: TopicContentBlock
+        x-addedInMatrixVersion: "1.15"
+        description: |-
+          Textual representation of the room topic in different mimetypes.
+        properties:
+          m.text:
+            $ref: components/m_text_content_block.yaml
     required:
       - topic
     type: object

data/string-formats.yaml

@@ -51,6 +51,11 @@ mx-room-id:
   url: appendices#room-ids
   # regex: "^!"
 
+mx-room-alias:
+  title: Room Alias
+  url: appendices#room-aliases
+  # regex: "^#"
+
 mx-server-name:
   title: Server Name
   url: appendices#server-name

scripts/dump-openapi.py

@@ -32,6 +32,35 @@ import yaml
 scripts_dir = os.path.dirname(os.path.abspath(__file__))
 api_dir = os.path.join(os.path.dirname(scripts_dir), "data", "api")
 
+# Finds a Hugo shortcode in a string.
+#
+# A shortcode is defined as (newlines and whitespaces for presentation purpose):
+#
+# {{%
+#     <zero or more whitespaces>
+#     <name of shortcode>
+#     (optional <one or more whitespaces><list of parameters>)
+#     <zero or more whitespaces>
+# %}}
+#
+# With:
+#
+# * <name of shortcode>: any word character and `-` and `/`. `re.ASCII` is used to only match
+#   ASCII characters in the name.
+# * <list of parameters>: any character except `}`, must not start or end with a
+#   whitespace.
+shortcode_regex = re.compile(r"""\{\{\%                                   # {{%
+                                 \s*                                      # zero or more whitespaces
+                                 (?P<name>[\w/-]+)                        # name of shortcode
+                                 (?:\s+(?P<params>[^\s\}][^\}]+[^\s\}]))? # optional list of parameters
+                                 \s*                                      # zero or more whitespaces
+                                 \%\}\}                                   # %}}""", re.ASCII | re.VERBOSE)
+
+# Parses the parameters of a Hugo shortcode.
+#
+# For simplicity, this currently only supports the `key="value"` format.
+shortcode_params_regex = re.compile(r"(?P<key>\w+)=\"(?P<value>[^\"]+)\"", re.ASCII)
+
 def prefix_absolute_path_references(text, base_url):
     """Adds base_url to absolute-path references.
 
@@ -44,17 +73,90 @@ def prefix_absolute_path_references(text, base_url):
     """
     return text.replace("](/", "]({}/".format(base_url))
 
-def edit_links(node, base_url):
+def replace_match(match, replacement):
-    """Finds description nodes and makes any links in them absolute."""
+    """Replaces the regex match by the replacement in the text."""
+    return match.string[:match.start()] + replacement + match.string[match.end():]
+
+def replace_shortcode(shortcode):
+    """Replaces the shortcode by a Markdown fallback in the text.
+
+    The supported shortcodes are:
+
+    * boxes/note, boxes/rationale, boxes/warning
+    * added-in, changed-in
+    
+    All closing tags (`{{ /shortcode }}`) are replaced with the empty string.
+    """
+
+    if shortcode['name'].startswith("/"):
+        # This is the end of the shortcode, just remove it.
+        return replace_match(shortcode, "")
+
+    # Parse the parameters of the shortcode
+    params = {}
+    if shortcode['params']:
+        for param in shortcode_params_regex.finditer(shortcode['params']):
+            if param['key']:
+                params[param['key']] = param['value']
+
+    match shortcode['name']:
+        case "boxes/note":
+            return replace_match(shortcode, "**NOTE:** ")
+        case "boxes/rationale":
+            return replace_match(shortcode, "**RATIONALE:** ")
+        case "boxes/warning":
+            return replace_match(shortcode, "**WARNING:** ")
+        case "added-in":
+            version = params['v']
+            if not version:
+                raise ValueError("Missing parameter `v` for `added-in` shortcode")
+
+            return replace_match(shortcode, f"**[Added in `v{version}`]** ")
+        case "changed-in":
+            version = params['v']
+            if not version:
+                raise ValueError("Missing parameter `v` for `changed-in` shortcode")
+
+            return replace_match(shortcode, f"**[Changed in `v{version}`]** ")
+        case _:
+            raise ValueError("Unknown shortcode", shortcode['name'])
+
+
+def find_and_replace_shortcodes(text):
+    """Finds Hugo shortcodes and replaces them by a Markdown fallback.
+
+    The supported shortcodes are:
+
+    * boxes/note, boxes/rationale, boxes/warning
+    * added-in, changed-in
+    """
+    # We use a `while` loop with `search` instead of a `for` loop with
+    # `finditer`, because as soon as we start replacing text, the
+    # indices of the match are invalid.
+    while shortcode := shortcode_regex.search(text):
+        text = replace_shortcode(shortcode)
+
+    return text
+
+def edit_descriptions(node, base_url):
+    """Finds description nodes and apply fixes to them.
+
+    The fixes that are applied are:
+
+    * Make links absolute
+    * Replace Hugo shortcodes
+    """
     if isinstance(node, dict):
         for key in node:
             if isinstance(node[key], str):
                 node[key] = prefix_absolute_path_references(node[key], base_url)
+                node[key] = find_and_replace_shortcodes(node[key])
             else:
-                edit_links(node[key], base_url)
+                edit_descriptions(node[key], base_url)
     elif isinstance(node, list):
         for item in node:
-            edit_links(item, base_url)
+            edit_descriptions(item, base_url)
+
 
 parser = argparse.ArgumentParser(
     "dump-openapi.py - assemble the OpenAPI specs into a single JSON file"
@@ -164,7 +266,7 @@ for filename in os.listdir(selected_api_dir):
 if untagged != 0:
     print("{} untagged operations, you may want to look into fixing that.".format(untagged))
 
-edit_links(output, base_url)
+edit_descriptions(output, base_url)
 
 print("Generating %s" % output_file)
 

static/.well-known/funding-manifest-urls

@@ -0,0 +1 @@
+https://matrix.org/funding.json