From e5aa5235fecef4a174b02417bb4ec71855adc355 Mon Sep 17 00:00:00 2001
From: Will Hunt <will@half-shot.uk>
Date: Wed, 20 Mar 2024 09:44:47 +0000
Subject: [PATCH 01/82] MSC4041 - Add Retry-After header notice. (#1737)

---
 .../client_server/newsfragments/1737.feature  |  1 +
 content/client-server-api/_index.md           | 43 ++++++++++---------
 2 files changed, 24 insertions(+), 20 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1737.feature

diff --git a/changelogs/client_server/newsfragments/1737.feature b/changelogs/client_server/newsfragments/1737.feature
new file mode 100644
index 00000000..e8d31dec
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1737.feature
@@ -0,0 +1 @@
+Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index bdfae65e..5889ec0f 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -106,7 +106,7 @@ No resource was found for this request.
 
 `M_LIMIT_EXCEEDED`
 Too many requests have been sent in a short period of time. Wait a while
-then try again.
+then try again. See [Rate limiting](#rate-limiting).
 
 `M_UNRECOGNIZED`
 The server did not understand the request. This is expected to be returned with
@@ -212,6 +212,28 @@ only read state (e.g.: `/sync`, get account data, etc).
 The user is unable to reject an invite to join the server notices room.
 See the [Server Notices](#server-notices) module for more information.
 
+#### Rate limiting
+
+Homeservers SHOULD implement rate limiting to reduce the risk of being
+overloaded. If a request is refused due to rate limiting, it should
+return a standard error response of the form:
+
+```json
+{
+  "errcode": "M_LIMIT_EXCEEDED",
+  "error": "string",
+  "retry_after_ms": integer (optional, deprecated)
+}
+```
+
+Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
+for any response with a 429 status code.
+
+The `retry_after_ms` property MAY be included to tell the client how long
+they have to wait in milliseconds before they can try again. This property is
+deprecated, in favour of the `Retry-After` header.
+
+{{< changed-in v="1.10" >}}: `retry_after_ms` property deprecated in favour of `Retry-After` header.
 ### Transaction identifiers
 
 The client-server API typically uses `HTTP PUT` to submit requests with
@@ -2536,25 +2558,6 @@ users, they should include the display name and avatar URL fields in
 these events so that clients already have these details to hand, and do
 not have to perform extra round trips to query it.
 
-## Security
-
-### Rate limiting
-
-Homeservers SHOULD implement rate limiting to reduce the risk of being
-overloaded. If a request is refused due to rate limiting, it should
-return a standard error response of the form:
-
-```json
-{
-  "errcode": "M_LIMIT_EXCEEDED",
-  "error": "string",
-  "retry_after_ms": integer (optional)
-}
-```
-
-The `retry_after_ms` key SHOULD be included to tell the client how long
-they have to wait in milliseconds before they can try again.
-
 ## Modules
 
 Modules are parts of the Client-Server API which are not universal to

From 6700f5ddd17e0418b598f0f85d7f9642a3070c0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Thu, 21 Mar 2024 12:03:07 +0100
Subject: [PATCH 02/82] Disable smooth scrolling (#1762)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It was not enabled before the docsy update and it messes with
the TOC highlighting during the transition.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 assets/scss/_variables_project.scss                  | 3 +++
 changelogs/internal/newsfragments/1762.clarification | 1 +
 2 files changed, 4 insertions(+)
 create mode 100644 changelogs/internal/newsfragments/1762.clarification

diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss
index 6eec3e7c..350e39cd 100644
--- a/assets/scss/_variables_project.scss
+++ b/assets/scss/_variables_project.scss
@@ -49,3 +49,6 @@ $td-enable-google-fonts: false;
  * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
  */
 $font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+// Disable smooth scrolling as it makes TOC highlighting jump during the transition.
+$enable-smooth-scroll: false;
diff --git a/changelogs/internal/newsfragments/1762.clarification b/changelogs/internal/newsfragments/1762.clarification
new file mode 100644
index 00000000..7d1c0526
--- /dev/null
+++ b/changelogs/internal/newsfragments/1762.clarification
@@ -0,0 +1 @@
+Update Docsy to v0.8.0.

From eb22fac5dc421eba7981840cadab2cf04e4e1a9f Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 21 Mar 2024 14:45:07 -0600
Subject: [PATCH 03/82] Break out non-JSON request/response content types as
 tables (#1756)

* Break out non-JSON request/response content types as tables

Currently we display this as a table like "image/png|image/jpeg" and description on a single line, but we're using a table. This breaks the join out to individual rows.

* changelog
---
 .../newsfragments/1756.clarification            |  1 +
 .../partials/openapi/render-content-type.html   | 17 ++++++++++-------
 layouts/partials/openapi/render-request.html    |  7 ++++---
 layouts/partials/openapi/render-responses.html  |  7 +++----
 4 files changed, 18 insertions(+), 14 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1756.clarification

diff --git a/changelogs/client_server/newsfragments/1756.clarification b/changelogs/client_server/newsfragments/1756.clarification
new file mode 100644
index 00000000..918e87c1
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1756.clarification
@@ -0,0 +1 @@
+Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses.
diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html
index da1a69bd..036522de 100644
--- a/layouts/partials/openapi/render-content-type.html
+++ b/layouts/partials/openapi/render-content-type.html
@@ -1,27 +1,30 @@
 {{/*
 
-  Render a table showing content type and description, given:
+  Render a table showing content types and their descriptions, given
+  two arrays with equal length:
 
-  * `content_type`: the content type as a string
+  * `content_types`: the content type strings
 
-  * `description`: the description as a string
+  * `descriptions`: the description strings
 
 */}}
 
-{{ $content_type := .content_type }}
-{{ $description := .description}}
+{{ $content_types := .content_types }}
+{{ $descriptions := .descriptions}}
 
-{{ if $content_type }}
+{{ if (gt (len $content_types) 0) }}
 
 <table class="content-type-table">
  <thead>
   <th class="col-name">Content-Type</th>
   <th class="col-description">Description</th>
  </thead>
+ {{ range $idx, $content_type := $content_types }}
  <tr>
   <td><code>{{ $content_type }}</code></td>
-  <td>{{ $description | markdownify -}}</td>
+  <td>{{ index $descriptions $idx | markdownify -}}</td>
  </tr>
+ {{ end }}
 </table>
 
 {{ end }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 5ef55c64..f41e062d 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -53,12 +53,13 @@
             {{/*
                 Show the content types and description.
             */}}
-            {{ $mimes := slice }}  
+            {{ $mimes := slice }}
+            {{ $descriptions := slice }}
             {{ range $mime, $body := $request_body.content }}
                 {{ $mimes = $mimes | append $mime }}
+                {{ $descriptions = $descriptions | append $request_body.description }}
             {{ end }}
-            {{ $content_type := delimit $mimes "|"}}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }}
+            {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }}
         {{ end }}
 
 <h3>Request body example</h3>
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 82c2f954..dba7fa8b 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -109,13 +109,12 @@
                 Show the content types and description.
             */}}
             {{ $mimes := slice }}
-            {{ $desc := "" }}
+            {{ $descriptions := slice }}
             {{ range $mime, $body := $response.content }}
                 {{ $mimes = $mimes | append $mime }}
-                {{ $desc = $body.schema.description }}
+                {{ $descriptions = $descriptions | append $body.schema.description }}
             {{ end }}
-            {{ $content_type := delimit $mimes "|"}}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }}
+            {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }}
         {{ end }}
     {{ end }}
 {{ end }}

From 7c19d24e3a52fd300f8ea53aae9eba92002657dc Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Thu, 21 Mar 2024 17:38:46 -0400
Subject: [PATCH 04/82] Do not allow setting m.push_rules account data
 directly. (#1763)

* Do not allow setting m.push_rules account data directly.

* Newsfragment

* Update 1763.clarification

Co-authored-by: Travis Ralston <travpc@gmail.com>

* add change notice

Co-authored-by: Travis Ralston <travpc@gmail.com>

* clarify read status

Co-authored-by: Travis Ralston <travpc@gmail.com>

* Fix link for push rules.

* Refer to the error response

---------

Co-authored-by: Travis Ralston <travpc@gmail.com>
---
 .../newsfragments/1763.clarification              |  1 +
 content/client-server-api/modules/account_data.md | 15 ++++++++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1763.clarification

diff --git a/changelogs/client_server/newsfragments/1763.clarification b/changelogs/client_server/newsfragments/1763.clarification
new file mode 100644
index 00000000..a4db76dd
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1763.clarification
@@ -0,0 +1 @@
+Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010).
diff --git a/content/client-server-api/modules/account_data.md b/content/client-server-api/modules/account_data.md
index 12233bcd..3068602d 100644
--- a/content/client-server-api/modules/account_data.md
+++ b/content/client-server-api/modules/account_data.md
@@ -26,6 +26,15 @@ These events can also be received in a `/events` response or in the
 
 #### Server Behaviour
 
-Servers MUST reject clients from setting account data for event types
-that the server manages. Currently, this only includes
-[m.fully\_read](#mfully_read).
+Servers MUST reject setting account data for event types
+that the server manages by using a 405 error response.
+Currently, this only includes [`m.fully_read`](#mfully_read)
+and [`m.push_rules`](#push-rules-events). This applies to
+both global and room-specific account data.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}} `m.push_rules` was added to the rejection
+list.
+{{% /boxes/note %}}
+
+Servers must allow clients to read the above event types as normal.

From f7452e2bad9b00aab0b12d6c67b865090ad5fa45 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 22 Mar 2024 09:47:03 -0600
Subject: [PATCH 05/82] Matrix 1.10

---
 .../newsfragments/1744.clarification          |   1 -
 .../newsfragments/1629.clarification          |   1 -
 .../newsfragments/1685.clarification          |   1 -
 .../newsfragments/1687.clarification          |   1 -
 .../newsfragments/1690.clarification          |   1 -
 .../newsfragments/1695.clarification          |   1 -
 .../newsfragments/1712.clarification          |   1 -
 .../newsfragments/1715.clarification          |   1 -
 .../newsfragments/1719.clarification          |   1 -
 .../newsfragments/1720.clarification          |   1 -
 .../client_server/newsfragments/1728.feature  |   1 -
 .../client_server/newsfragments/1730.feature  |   1 -
 .../client_server/newsfragments/1731.feature  |   1 -
 .../newsfragments/1732.clarification          |   1 -
 .../client_server/newsfragments/1733.feature  |   1 -
 .../newsfragments/1734.clarification          |   1 -
 .../client_server/newsfragments/1735.feature  |   1 -
 .../client_server/newsfragments/1737.feature  |   1 -
 .../newsfragments/1739.clarification          |   1 -
 .../newsfragments/1740.clarification          |   1 -
 .../newsfragments/1742.clarification          |   1 -
 .../client_server/newsfragments/1746.feature  |   1 -
 .../newsfragments/1748.clarification          |   1 -
 .../newsfragments/1756.clarification          |   1 -
 .../newsfragments/1763.clarification          |   1 -
 .../internal/newsfragments/1680.clarification |   1 -
 .../internal/newsfragments/1697.clarification |   1 -
 .../internal/newsfragments/1699.clarification |   1 -
 .../internal/newsfragments/1713.clarification |   1 -
 .../internal/newsfragments/1718.clarification |   1 -
 .../internal/newsfragments/1724.clarification |   1 -
 .../internal/newsfragments/1745.clarification |   1 -
 .../internal/newsfragments/1751.clarification |   1 -
 .../internal/newsfragments/1754.clarification |   1 -
 .../internal/newsfragments/1762.clarification |   1 -
 .../newsfragments/1717.clarification          |   1 -
 .../newsfragments/1721.clarification          |   1 -
 .../newsfragments/1740.clarification          |   1 -
 .../newsfragments/1741.clarification          |   1 -
 config.toml                                   |   8 +-
 content/changelog/v1.10.md                    | 102 ++++++++++++++++++
 41 files changed, 106 insertions(+), 43 deletions(-)
 delete mode 100644 changelogs/application_service/newsfragments/1744.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1629.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1685.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1687.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1690.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1695.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1712.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1715.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1719.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1720.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1728.feature
 delete mode 100644 changelogs/client_server/newsfragments/1730.feature
 delete mode 100644 changelogs/client_server/newsfragments/1731.feature
 delete mode 100644 changelogs/client_server/newsfragments/1732.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1733.feature
 delete mode 100644 changelogs/client_server/newsfragments/1734.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1735.feature
 delete mode 100644 changelogs/client_server/newsfragments/1737.feature
 delete mode 100644 changelogs/client_server/newsfragments/1739.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1740.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1742.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1746.feature
 delete mode 100644 changelogs/client_server/newsfragments/1748.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1756.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1763.clarification
 delete mode 100644 changelogs/internal/newsfragments/1680.clarification
 delete mode 100644 changelogs/internal/newsfragments/1697.clarification
 delete mode 100644 changelogs/internal/newsfragments/1699.clarification
 delete mode 100644 changelogs/internal/newsfragments/1713.clarification
 delete mode 100644 changelogs/internal/newsfragments/1718.clarification
 delete mode 100644 changelogs/internal/newsfragments/1724.clarification
 delete mode 100644 changelogs/internal/newsfragments/1745.clarification
 delete mode 100644 changelogs/internal/newsfragments/1751.clarification
 delete mode 100644 changelogs/internal/newsfragments/1754.clarification
 delete mode 100644 changelogs/internal/newsfragments/1762.clarification
 delete mode 100644 changelogs/room_versions/newsfragments/1717.clarification
 delete mode 100644 changelogs/server_server/newsfragments/1721.clarification
 delete mode 100644 changelogs/server_server/newsfragments/1740.clarification
 delete mode 100644 changelogs/server_server/newsfragments/1741.clarification
 create mode 100644 content/changelog/v1.10.md

diff --git a/changelogs/application_service/newsfragments/1744.clarification b/changelogs/application_service/newsfragments/1744.clarification
deleted file mode 100644
index 908c48ab..00000000
--- a/changelogs/application_service/newsfragments/1744.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`.
diff --git a/changelogs/client_server/newsfragments/1629.clarification b/changelogs/client_server/newsfragments/1629.clarification
deleted file mode 100644
index 81ed5aaa..00000000
--- a/changelogs/client_server/newsfragments/1629.clarification
+++ /dev/null
@@ -1 +0,0 @@
-The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1685.clarification b/changelogs/client_server/newsfragments/1685.clarification
deleted file mode 100644
index 8090d817..00000000
--- a/changelogs/client_server/newsfragments/1685.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that read receipts should be batched by thread as well as by room.
diff --git a/changelogs/client_server/newsfragments/1687.clarification b/changelogs/client_server/newsfragments/1687.clarification
deleted file mode 100644
index 09bacd28..00000000
--- a/changelogs/client_server/newsfragments/1687.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that threads can be created based on replies.
diff --git a/changelogs/client_server/newsfragments/1690.clarification b/changelogs/client_server/newsfragments/1690.clarification
deleted file mode 100644
index e24a08cf..00000000
--- a/changelogs/client_server/newsfragments/1690.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1695.clarification b/changelogs/client_server/newsfragments/1695.clarification
deleted file mode 100644
index 32d9bb51..00000000
--- a/changelogs/client_server/newsfragments/1695.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify the format of account data objects for secret storage.
diff --git a/changelogs/client_server/newsfragments/1712.clarification b/changelogs/client_server/newsfragments/1712.clarification
deleted file mode 100644
index 9e1523c5..00000000
--- a/changelogs/client_server/newsfragments/1712.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256.
diff --git a/changelogs/client_server/newsfragments/1715.clarification b/changelogs/client_server/newsfragments/1715.clarification
deleted file mode 100644
index a1d30432..00000000
--- a/changelogs/client_server/newsfragments/1715.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify one-time key and fallback key types in examples.
diff --git a/changelogs/client_server/newsfragments/1719.clarification b/changelogs/client_server/newsfragments/1719.clarification
deleted file mode 100644
index 031e1e41..00000000
--- a/changelogs/client_server/newsfragments/1719.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes.
diff --git a/changelogs/client_server/newsfragments/1720.clarification b/changelogs/client_server/newsfragments/1720.clarification
deleted file mode 100644
index e8c8a623..00000000
--- a/changelogs/client_server/newsfragments/1720.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify how to perform the ECDH exchange in step 12 of the SAS process.
diff --git a/changelogs/client_server/newsfragments/1728.feature b/changelogs/client_server/newsfragments/1728.feature
deleted file mode 100644
index 98d055fb..00000000
--- a/changelogs/client_server/newsfragments/1728.feature
+++ /dev/null
@@ -1 +0,0 @@
-Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026).
diff --git a/changelogs/client_server/newsfragments/1730.feature b/changelogs/client_server/newsfragments/1730.feature
deleted file mode 100644
index 673f7515..00000000
--- a/changelogs/client_server/newsfragments/1730.feature
+++ /dev/null
@@ -1 +0,0 @@
-Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025).
diff --git a/changelogs/client_server/newsfragments/1731.feature b/changelogs/client_server/newsfragments/1731.feature
deleted file mode 100644
index fa952762..00000000
--- a/changelogs/client_server/newsfragments/1731.feature
+++ /dev/null
@@ -1 +0,0 @@
-Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1732.clarification b/changelogs/client_server/newsfragments/1732.clarification
deleted file mode 100644
index 61e74c6c..00000000
--- a/changelogs/client_server/newsfragments/1732.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1733.feature b/changelogs/client_server/newsfragments/1733.feature
deleted file mode 100644
index a2740ea7..00000000
--- a/changelogs/client_server/newsfragments/1733.feature
+++ /dev/null
@@ -1 +0,0 @@
-Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1734.clarification b/changelogs/client_server/newsfragments/1734.clarification
deleted file mode 100644
index 32d9bb51..00000000
--- a/changelogs/client_server/newsfragments/1734.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify the format of account data objects for secret storage.
diff --git a/changelogs/client_server/newsfragments/1735.feature b/changelogs/client_server/newsfragments/1735.feature
deleted file mode 100644
index 1d764142..00000000
--- a/changelogs/client_server/newsfragments/1735.feature
+++ /dev/null
@@ -1 +0,0 @@
-Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1737.feature b/changelogs/client_server/newsfragments/1737.feature
deleted file mode 100644
index e8d31dec..00000000
--- a/changelogs/client_server/newsfragments/1737.feature
+++ /dev/null
@@ -1 +0,0 @@
-Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041).
diff --git a/changelogs/client_server/newsfragments/1739.clarification b/changelogs/client_server/newsfragments/1739.clarification
deleted file mode 100644
index da43cefb..00000000
--- a/changelogs/client_server/newsfragments/1739.clarification
+++ /dev/null
@@ -1 +0,0 @@
-The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1740.clarification b/changelogs/client_server/newsfragments/1740.clarification
deleted file mode 100644
index 1760ac9f..00000000
--- a/changelogs/client_server/newsfragments/1740.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1742.clarification b/changelogs/client_server/newsfragments/1742.clarification
deleted file mode 100644
index 84f21b9e..00000000
--- a/changelogs/client_server/newsfragments/1742.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1746.feature b/changelogs/client_server/newsfragments/1746.feature
deleted file mode 100644
index d81e46ec..00000000
--- a/changelogs/client_server/newsfragments/1746.feature
+++ /dev/null
@@ -1 +0,0 @@
-Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981).
diff --git a/changelogs/client_server/newsfragments/1748.clarification b/changelogs/client_server/newsfragments/1748.clarification
deleted file mode 100644
index 3ccb2333..00000000
--- a/changelogs/client_server/newsfragments/1748.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Fix various typos throughout the specification.
diff --git a/changelogs/client_server/newsfragments/1756.clarification b/changelogs/client_server/newsfragments/1756.clarification
deleted file mode 100644
index 918e87c1..00000000
--- a/changelogs/client_server/newsfragments/1756.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses.
diff --git a/changelogs/client_server/newsfragments/1763.clarification b/changelogs/client_server/newsfragments/1763.clarification
deleted file mode 100644
index a4db76dd..00000000
--- a/changelogs/client_server/newsfragments/1763.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010).
diff --git a/changelogs/internal/newsfragments/1680.clarification b/changelogs/internal/newsfragments/1680.clarification
deleted file mode 100644
index 16352364..00000000
--- a/changelogs/internal/newsfragments/1680.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Update the spec release process.
\ No newline at end of file
diff --git a/changelogs/internal/newsfragments/1697.clarification b/changelogs/internal/newsfragments/1697.clarification
deleted file mode 100644
index d238b2e9..00000000
--- a/changelogs/internal/newsfragments/1697.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Minor clarifications to the contributing guide.
diff --git a/changelogs/internal/newsfragments/1699.clarification b/changelogs/internal/newsfragments/1699.clarification
deleted file mode 100644
index 7d1c0526..00000000
--- a/changelogs/internal/newsfragments/1699.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Update Docsy to v0.8.0.
diff --git a/changelogs/internal/newsfragments/1713.clarification b/changelogs/internal/newsfragments/1713.clarification
deleted file mode 100644
index c1b999bf..00000000
--- a/changelogs/internal/newsfragments/1713.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Fix npm release script for `@matrix-org/spec`.
diff --git a/changelogs/internal/newsfragments/1718.clarification b/changelogs/internal/newsfragments/1718.clarification
deleted file mode 100644
index 75d5948b..00000000
--- a/changelogs/internal/newsfragments/1718.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Add some clarifications around implementation requirements for MSCs.
diff --git a/changelogs/internal/newsfragments/1724.clarification b/changelogs/internal/newsfragments/1724.clarification
deleted file mode 100644
index 12be0c5a..00000000
--- a/changelogs/internal/newsfragments/1724.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Update HTML templates to include links to object schema definitions.
diff --git a/changelogs/internal/newsfragments/1745.clarification b/changelogs/internal/newsfragments/1745.clarification
deleted file mode 100644
index acd85892..00000000
--- a/changelogs/internal/newsfragments/1745.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Factor out all the common parameters of the various `/relations` apis.
diff --git a/changelogs/internal/newsfragments/1751.clarification b/changelogs/internal/newsfragments/1751.clarification
deleted file mode 100644
index 50c50693..00000000
--- a/changelogs/internal/newsfragments/1751.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.
diff --git a/changelogs/internal/newsfragments/1754.clarification b/changelogs/internal/newsfragments/1754.clarification
deleted file mode 100644
index 50c50693..00000000
--- a/changelogs/internal/newsfragments/1754.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.
diff --git a/changelogs/internal/newsfragments/1762.clarification b/changelogs/internal/newsfragments/1762.clarification
deleted file mode 100644
index 7d1c0526..00000000
--- a/changelogs/internal/newsfragments/1762.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Update Docsy to v0.8.0.
diff --git a/changelogs/room_versions/newsfragments/1717.clarification b/changelogs/room_versions/newsfragments/1717.clarification
deleted file mode 100644
index 80bc9d55..00000000
--- a/changelogs/room_versions/newsfragments/1717.clarification
+++ /dev/null
@@ -1 +0,0 @@
-For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1721.clarification b/changelogs/server_server/newsfragments/1721.clarification
deleted file mode 100644
index a742501b..00000000
--- a/changelogs/server_server/newsfragments/1721.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies.
diff --git a/changelogs/server_server/newsfragments/1740.clarification b/changelogs/server_server/newsfragments/1740.clarification
deleted file mode 100644
index 1760ac9f..00000000
--- a/changelogs/server_server/newsfragments/1740.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1741.clarification b/changelogs/server_server/newsfragments/1741.clarification
deleted file mode 100644
index ec31cac1..00000000
--- a/changelogs/server_server/newsfragments/1741.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required.
\ No newline at end of file
diff --git a/config.toml b/config.toml
index 15a284b5..94ccfd49 100644
--- a/config.toml
+++ b/config.toml
@@ -59,14 +59,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice"
 [params.version]
 # must be one of "unstable", "current", "historical"
 # this is used to decide whether to show a banner pointing to the current release
-status = "unstable"
+status = "stable"
 # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
 current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
-# major = "1"
-# minor = "9"
-# release_date = "November 29, 2023"
+major = "1"
+minor = "10"
+release_date = "March 22, 2024"
 
 # User interface configuration
 [params.ui]
diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md
new file mode 100644
index 00000000..16b3217d
--- /dev/null
+++ b/content/changelog/v1.10.md
@@ -0,0 +1,102 @@
+---
+date: 2024-03-22T09:59:45-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.10  = Replaced by the version number (eg: v1.2)
+    March 22, 2024     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.10
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
+<tr><th>Release date</th><td>March 22, 2024</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### Client-Server API
+
+**Backwards Compatible Changes**
+
+- Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). ([#1728](https://github.com/matrix-org/matrix-spec/issues/1728))
+- Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). ([#1730](https://github.com/matrix-org/matrix-spec/issues/1730))
+- Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). ([#1731](https://github.com/matrix-org/matrix-spec/issues/1731))
+- Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). ([#1733](https://github.com/matrix-org/matrix-spec/issues/1733))
+- Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). ([#1735](https://github.com/matrix-org/matrix-spec/issues/1735))
+- Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041). ([#1737](https://github.com/matrix-org/matrix-spec/issues/1737))
+- Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981). ([#1746](https://github.com/matrix-org/matrix-spec/issues/1746))
+
+**Spec Clarifications**
+
+- The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. ([#1629](https://github.com/matrix-org/matrix-spec/issues/1629))
+- Clarify that read receipts should be batched by thread as well as by room. ([#1685](https://github.com/matrix-org/matrix-spec/issues/1685))
+- Clarify that threads can be created based on replies. ([#1687](https://github.com/matrix-org/matrix-spec/issues/1687))
+- Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. ([#1690](https://github.com/matrix-org/matrix-spec/issues/1690))
+- Clarify the format of account data objects for secret storage. ([#1695](https://github.com/matrix-org/matrix-spec/issues/1695), [#1734](https://github.com/matrix-org/matrix-spec/issues/1734))
+- Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. ([#1712](https://github.com/matrix-org/matrix-spec/issues/1712))
+- Clarify one-time key and fallback key types in examples. ([#1715](https://github.com/matrix-org/matrix-spec/issues/1715))
+- Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. ([#1719](https://github.com/matrix-org/matrix-spec/issues/1719))
+- Clarify how to perform the ECDH exchange in step 12 of the SAS process. ([#1720](https://github.com/matrix-org/matrix-spec/issues/1720))
+- Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). ([#1732](https://github.com/matrix-org/matrix-spec/issues/1732))
+- The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead. ([#1739](https://github.com/matrix-org/matrix-spec/issues/1739))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. ([#1742](https://github.com/matrix-org/matrix-spec/issues/1742))
+- Fix various typos throughout the specification. ([#1748](https://github.com/matrix-org/matrix-spec/issues/1748))
+- Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. ([#1756](https://github.com/matrix-org/matrix-spec/issues/1756))
+- Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
+
+
+### Server-Server API
+
+**Spec Clarifications**
+
+- Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. ([#1721](https://github.com/matrix-org/matrix-spec/issues/1721))
+- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
+- Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
+
+
+### Application Service API
+
+**Spec Clarifications**
+
+- Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
+
+
+### Identity Service API
+
+No significant changes.
+
+
+### Push Gateway API
+
+No significant changes.
+
+
+### Room Versions
+
+**Spec Clarifications**
+
+- For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
+
+
+### Appendices
+
+No significant changes.
+
+
+### Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Update the spec release process. ([#1680](https://github.com/matrix-org/matrix-spec/issues/1680))
+- Minor clarifications to the contributing guide. ([#1697](https://github.com/matrix-org/matrix-spec/issues/1697))
+- Update Docsy to v0.8.0. ([#1699](https://github.com/matrix-org/matrix-spec/issues/1699), [#1762](https://github.com/matrix-org/matrix-spec/issues/1762))
+- Fix npm release script for `@matrix-org/spec`. ([#1713](https://github.com/matrix-org/matrix-spec/issues/1713))
+- Add some clarifications around implementation requirements for MSCs. ([#1718](https://github.com/matrix-org/matrix-spec/issues/1718))
+- Update HTML templates to include links to object schema definitions. ([#1724](https://github.com/matrix-org/matrix-spec/issues/1724))
+- Factor out all the common parameters of the various `/relations` apis. ([#1745](https://github.com/matrix-org/matrix-spec/issues/1745))
+- Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. ([#1751](https://github.com/matrix-org/matrix-spec/issues/1751), [#1754](https://github.com/matrix-org/matrix-spec/issues/1754))

From 4e51970c55715525b2f405a78fe41422521ceb24 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 22 Mar 2024 10:06:23 -0600
Subject: [PATCH 06/82] Upgrade Hugo version on the historical spec

---
 .github/workflows/main.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 5fa57a4f..3288b42a 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -45,7 +45,7 @@ jobs:
       - name: "🔎 Run validator"
         run: |
           python scripts/check-event-schema-examples.py
-  
+
   check-openapi-examples:
     name: "🔎 Check OpenAPI definitions examples"
     runs-on: ubuntu-latest
@@ -268,7 +268,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
         with:
-          hugo-version: '0.93.3'
+          hugo-version: '0.113.0'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4

From bd122b35b007b62ee373f5a55a04db5a903ee2b6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Fri, 22 Mar 2024 10:12:10 -0600
Subject: [PATCH 07/82] Return to unstable

---
 config.toml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/config.toml b/config.toml
index 94ccfd49..7197c693 100644
--- a/config.toml
+++ b/config.toml
@@ -59,14 +59,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice"
 [params.version]
 # must be one of "unstable", "current", "historical"
 # this is used to decide whether to show a banner pointing to the current release
-status = "stable"
+status = "unstable"
 # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
 current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
-major = "1"
-minor = "10"
-release_date = "March 22, 2024"
+# major = "1"
+# minor = "10"
+# release_date = "March 22, 2024"
 
 # User interface configuration
 [params.ui]

From 083e6ef25da712eecc1b56a8e3a2fafaf48d130d Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Fri, 22 Mar 2024 18:27:42 +0000
Subject: [PATCH 08/82] Fix npm publishing being broken in CI (#1765)

* Fix `v` tag_name prefix sneaking into npm version

* Fix `yarn version` failing in CI due to no git global ident name

* Add changelog

* Rename 1765.misc to 1765.clarification
---
 .github/workflows/release.yaml                       | 3 ++-
 changelogs/internal/newsfragments/1765.clarification | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/internal/newsfragments/1765.clarification

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 05e5be7a..6f8d1353 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -26,8 +26,9 @@ jobs:
       - name: 🔨 Install dependencies
         run: "yarn install --frozen-lockfile"
 
+      # We bump the package.json version to git, we just need it for publish to do the right thing
       - name: 🎖 Bump package.json version
-        run: "yarn version --new-version $VERSION"
+        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
         env:
           VERSION: ${{ github.event.release.tag_name }}.0
 
diff --git a/changelogs/internal/newsfragments/1765.clarification b/changelogs/internal/newsfragments/1765.clarification
new file mode 100644
index 00000000..c1b999bf
--- /dev/null
+++ b/changelogs/internal/newsfragments/1765.clarification
@@ -0,0 +1 @@
+Fix npm release script for `@matrix-org/spec`.

From c25ff9e01290f5dbc5160038e41eb37e8009fb14 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 26 Mar 2024 11:28:31 +0000
Subject: [PATCH 09/82]  Formatting fixes in CONTRIBUTING.rst  (#1769)

* Formatting fix in CONTRIBUTING.rst

* Fix link

* Create 1769.clarification
---
 CONTRIBUTING.rst                                     | 4 ++--
 changelogs/internal/newsfragments/1769.clarification | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1769.clarification

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 93763a29..f93b44f4 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -12,7 +12,7 @@ The documentation style is described at
 https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
 
 Matrix-spec workflows
---------------------
+---------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
@@ -117,7 +117,7 @@ license - in our case, this is Apache Software License v2 (see LICENSE).
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
 same lightweight approach used by the `Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md`_, and many other
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
 projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
 (DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::
diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification
new file mode 100644
index 00000000..ebf8030d
--- /dev/null
+++ b/changelogs/internal/newsfragments/1769.clarification
@@ -0,0 +1 @@
+Formatting fixes in CONTRIBUTING.rst.

From eb7ac353e2b0f671ac103e0af46c079ebaf25611 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 26 Mar 2024 20:10:55 +0100
Subject: [PATCH 10/82] Add support for muting in VoIP calls (#1755)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As per MSC3291.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../newsfragments/1755.clarification          |  1 +
 .../client-server-api/modules/voip_events.md  | 18 +++++++++-------
 .../m.call.sdp_stream_metadata_changed.yaml   | 16 ++++++++++++++
 .../components/sdp_stream_metadata.yaml       | 20 +++++++++++++++---
 .../m.call.sdp_stream_metadata_changed.yaml   | 21 +++++++++++++++++++
 5 files changed, 66 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1755.clarification
 create mode 100644 data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml
 create mode 100644 data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml

diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.clarification
new file mode 100644
index 00000000..65c5ba36
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1755.clarification
@@ -0,0 +1 @@
+Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).
diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md
index 4df0ba13..c45a4824 100644
--- a/content/client-server-api/modules/voip_events.md
+++ b/content/client-server-api/modules/voip_events.md
@@ -174,15 +174,19 @@ In response to an incoming invite, a client may do one of several things:
 Clients may send more than one stream in a VoIP call. The streams should be
 differentiated by including metadata in the [`m.call.invite`](/client-server-api/#mcallinvite),
 [`m.call.answer`](/client-server-api/#mcallanswer) and [`m.call.negotiate`](/client-server-api/#mcallnegotiate)
-events, using the `sdp_stream_metadata` property.
+events, using the `sdp_stream_metadata` property. An [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event can be sent when the metadata changes but no negotiation is required.
 
-`sdp_stream_metadata` maps from the `id` of a stream in the session description, 
-to metadata about that stream. Currently only one property is defined for the
-metadata. This is `purpose`, which should be a string indicating the purpose of
-the stream. The following `purpose`s are defined:
+Clients are recommended to not mute the audio of WebRTC tracks locally when an
+incoming stream has the `audio_muted` field set to `true`. This is because when
+the other user unmutes themselves, there may be a slight delay between their
+client sending audio and the [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed)
+event arriving and any audio sent in between will not be heard. The other user
+will still stop transmitting audio once they mute on their side, so no audio is
+sent without the user's knowledge.
 
-*  `m.usermedia` - stream that contains the webcam and/or microphone tracks
-*  `m.screenshare` - stream with the screen-sharing tracks
+The same suggestion does not apply to `video_muted`. Clients _should_ mute video
+locally, so that the receiving side doesn't see a black video.
 
 If `sdp_stream_metadata` is present and an incoming stream is not listed in it,
 the stream should be ignored. If a stream has a `purpose` of an unknown type, it
diff --git a/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml
new file mode 100644
index 00000000..43b4fd75
--- /dev/null
+++ b/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml
@@ -0,0 +1,16 @@
+{
+  "$ref": "core/room_event.json",
+  "type": "m.call.sdp_stream_metadata_changed",
+  "content": {
+    "version": "1",
+    "call_id": "1414213562373095",
+    "party_id": "1732050807568877",
+    "sdp_stream_metadata": {
+        "2311546231": {
+            "purpose": "m.usermedia",
+            "audio_muted:": true,
+            "video_muted": true
+        }
+    }
+  }
+}
diff --git a/data/event-schemas/schema/components/sdp_stream_metadata.yaml b/data/event-schemas/schema/components/sdp_stream_metadata.yaml
index f16b4cbd..35566abe 100644
--- a/data/event-schemas/schema/components/sdp_stream_metadata.yaml
+++ b/data/event-schemas/schema/components/sdp_stream_metadata.yaml
@@ -13,8 +13,8 @@ additionalProperties:
     purpose:
       type: string
       enum:
-        - m.usermedia
-        - m.screenshare
+      - m.usermedia
+      - m.screenshare
       description: |-
         The purpose of the stream.
 
@@ -23,5 +23,19 @@ additionalProperties:
         * `m.usermedia`: Stream that contains the webcam and/or microphone
           tracks.
         * `m.screenshare`: Stream with the screen-sharing tracks.
+    audio_muted:
+      type: boolean
+      description: |-
+        Whether the audio track in the stream is muted.
+
+        Defaults to `false` if not present.
+      x-addedInMatrixVersion: "1.11"        
+    video_muted:
+      type: boolean
+      description: |-
+        Whether the video track in the stream is muted.
+
+        Defaults to `false` if not present.
+      x-addedInMatrixVersion: "1.11"        
   required:
-    - purpose
+  - purpose
diff --git a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml
new file mode 100644
index 00000000..953817c2
--- /dev/null
+++ b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml
@@ -0,0 +1,21 @@
+type: object
+x-addedInMatrixVersion: "1.11"
+description: |-
+  This event is sent by callers when they wish to update a stream's metadata
+  but no negotiation is required.
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - $ref: core-event-schema/call_event.yaml
+    properties:
+      sdp_stream_metadata:
+        $ref: components/sdp_stream_metadata.yaml
+    required:
+    - sdp_stream_metadata
+  type:
+    type: string
+    enum:
+    - m.call.sdp_stream_metadata_changed

From 8ff3623e373b7d553d8de654ffcb6f054bafa891 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 27 Mar 2024 10:55:01 +0100
Subject: [PATCH 11/82] Reduce whitespace on mobile viewports (#1770)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 assets/scss/_styles_project.scss              | 24 +++++++++++++++----
 .../internal/newsfragments/1770.clarification |  1 +
 2 files changed, 21 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1770.clarification

diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
index b275db4f..41cc149f 100644
--- a/assets/scss/_styles_project.scss
+++ b/assets/scss/_styles_project.scss
@@ -40,10 +40,13 @@ Custom SCSS for the Matrix spec
   .navbar-brand {
     font-size: 1.1rem;
 
+    /* Allow the text to wrap if it is wider than the viewport */
+    text-align: center;
+    white-space: normal;
+
     .navbar-version {
       color: $secondary;
     }
-
   }
 
   .nav-link {
@@ -115,7 +118,7 @@ Custom SCSS for the Matrix spec
   }
 }
 
-@media (min-width: 768px) {
+@include media-breakpoint-up(md) {
   @supports (position: sticky) {
     .td-sidebar-nav {
       /* This overrides calc(100vh - 10rem);, which gives us a blank space at the bottom of the sidebar */
@@ -172,6 +175,13 @@ footer {
 
 }
 
+/* Remove some padding before the main content, when the sidebar is disabled */
+.td-main main {
+  @include media-breakpoint-down(md) {
+    padding-top: 0;
+  }
+}
+
 /* Adjust the scroll margin for everything in the main content, so that
  * it doesn't disappear behind the header bar */
 .td-content * {
@@ -471,12 +481,18 @@ of .td-content. This applies the same style to any blockquotes that descend from
 Make padding symmetrical (this selector is used in the default styles to apply padding-left: 3rem)
 */
 .pl-md-5, .px-md-5 {
-  padding-right: 3rem;
+  @include media-breakpoint-up(md) {
+    padding-right: 3rem;
+  }
 }
 
 /* Adjust default styles for info banner */
 .pageinfo-primary {
-  max-width: 80%;
+  @include media-breakpoint-up(lg) {
+    max-width: 80%;
+  }
+  margin-top: 0;
+  margin-right: 0;
   margin-left: 0;
   border: 0;
   border-left: solid 5px $secondary;
diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification
new file mode 100644
index 00000000..e5fb516f
--- /dev/null
+++ b/changelogs/internal/newsfragments/1770.clarification
@@ -0,0 +1 @@
+Reduce whitespace on mobile viewports

From d547154c910f785ef079bf3fcbc7f95c771d6342 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 1 Apr 2024 15:14:42 -0600
Subject: [PATCH 12/82] Spec `?animated` on `/thumbnail` (#1757)

* Spec `?animated` on `/thumbnail`

* v3*

* v1.11
---
 .../client_server/newsfragments/1757.feature  |  1 +
 data/api/client-server/content-repo.yaml      | 43 ++++++++++++++++++-
 2 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1757.feature

diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature
new file mode 100644
index 00000000..3471c1b9
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1757.feature
@@ -0,0 +1 @@
+Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).
\ No newline at end of file
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index c8800279..f6913874 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -633,6 +633,28 @@ paths:
           schema:
             type: boolean
             default: false
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server should behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
       responses:
         "200":
           description: A thumbnail of the requested content.
@@ -644,6 +666,9 @@ paths:
                 enum:
                   - image/jpeg
                   - image/png
+                  - image/apng
+                  - image/gif
+                  - image/webp
           content:
             image/jpeg:
               schema:
@@ -651,7 +676,23 @@ paths:
                 description: "**Required.** The bytes for the thumbnail."
             image/png:
               schema:
-                description: "**Required.** The bytes for the thumbnail."
+                x-changedInMatrixVersion:
+                  "1.11": The PNG may be of the APNG variety if animation is supported and requested.
+                description: |
+                  **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
+                  format if `animated=true`.
+            image/apng:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/gif:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/webp:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
         "307":
           description: A redirect to the thumbnail of the requested content.
           headers:

From e74c7c154012834ebd3339827b195b351de2edad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 9 Apr 2024 15:18:16 +0200
Subject: [PATCH 13/82] Fix Hugo warnings (#1775)

---
 changelogs/internal/newsfragments/1775.clarification | 1 +
 config.toml                                          | 7 ++++---
 2 files changed, 5 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1775.clarification

diff --git a/changelogs/internal/newsfragments/1775.clarification b/changelogs/internal/newsfragments/1775.clarification
new file mode 100644
index 00000000..649503a0
--- /dev/null
+++ b/changelogs/internal/newsfragments/1775.clarification
@@ -0,0 +1 @@
+Fix Hugo warnings.
diff --git a/config.toml b/config.toml
index 7197c693..a4245d0b 100644
--- a/config.toml
+++ b/config.toml
@@ -10,15 +10,16 @@ enableRobotsTXT = true
 # We disable RSS, because (a) it's useless, (b) Hugo seems to generate broken
 # links to it when used with a --baseURL (for example, https://spec.matrix.org/v1.4/
 # contains `<link rel="alternate" type="application/rss&#43;xml" href="/v1.4/v1.4/index.xml">`).
-disableKinds = ["taxonomy", "taxonomyTerm", "RSS"]
+disableKinds = ["taxonomy", "RSS"]
 
 [languages]
 [languages.en]
 title = "Matrix Specification"
-description = "Home of the Matrix specification for decentralised communication"
 languageName ="English"
 # Weight used for sorting.
 weight = 1
+[languages.en.params]
+description = "Home of the Matrix specification for decentralised communication"
 
 # Entries in the main menu in the header.
 [menus]
@@ -129,7 +130,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.110.0"
+    min = "0.113.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false

From ee1a169121e481900cd8d3ac65682f69105e649f Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Tue, 9 Apr 2024 15:31:46 +0200
Subject: [PATCH 14/82] Arrange rows in .basic-info tables vertically when
 horizontal space is constrained (#1771)

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 assets/scss/_styles_project.scss              | 25 +++++++++++++++++++
 .../internal/newsfragments/1771.clarification |  1 +
 2 files changed, 26 insertions(+)
 create mode 100644 changelogs/internal/newsfragments/1771.clarification

diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
index 41cc149f..63953697 100644
--- a/assets/scss/_styles_project.scss
+++ b/assets/scss/_styles_project.scss
@@ -437,6 +437,31 @@ footer {
     &.basic-info th {
       width: 15rem;
     }
+
+    /* Arrange rows vertically when horizontal space is constrained to avoid overflowing */
+    @include media-breakpoint-down(sm) {
+      /* Make cells full width without vertical margin */
+      &.basic-info th, &.basic-info td {
+        width: 100%;
+        display: inline-block;
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+
+      /* Remove border and padding between header & data cells to make them appear like a single cell */
+      &.basic-info td {
+        padding-top: 0;
+        border-top: none;
+      }
+      &.basic-info th {
+        border-bottom: none;
+      }
+
+      /* Remove top border on all but the first header cell to prevent double borders between rows */
+      &.basic-info tr + tr th {
+        border-top: none;
+      }
+    }
   }
 
   pre {
diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification
new file mode 100644
index 00000000..b1941e18
--- /dev/null
+++ b/changelogs/internal/newsfragments/1771.clarification
@@ -0,0 +1 @@
+Arrange rows in `.basic-info` tables vertically when horizontal space is constrained.

From efe72d3b26653c131c09ba058596494a7a567682 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 9 Apr 2024 18:12:30 +0200
Subject: [PATCH 15/82] Fix security schemes in OpenAPI definitions (#1772)

---
 .../newsfragments/1772.clarification          |  1 +
 .../newsfragments/1772.clarification          |  1 +
 .../newsfragments/1772.clarification          |  1 +
 .../newsfragments/1772.clarification          |  1 +
 .../definitions/security.yaml                 |  5 +-
 data/api/application-service/ping.yaml        |  3 +-
 data/api/application-service/protocols.yaml   |  3 +-
 data/api/application-service/query_room.yaml  |  3 +-
 data/api/application-service/query_user.yaml  |  3 +-
 .../api/application-service/transactions.yaml |  3 +-
 data/api/client-server/account-data.yaml      | 17 +++++--
 data/api/client-server/admin.yaml             |  8 +++-
 .../client-server/administrative_contact.yaml | 23 ++++++---
 data/api/client-server/appservice_ping.yaml   | 11 +++--
 .../appservice_room_directory.yaml            | 11 +++--
 data/api/client-server/banning.yaml           | 11 +++--
 data/api/client-server/capabilities.yaml      |  8 +++-
 data/api/client-server/content-repo.yaml      | 17 +++++--
 data/api/client-server/create_room.yaml       |  8 +++-
 data/api/client-server/cross_signing.yaml     | 11 +++--
 .../client-server/definitions/security.yaml   | 32 ++++++++++++-
 data/api/client-server/device_management.yaml | 20 +++++---
 data/api/client-server/directory.yaml         | 14 ++++--
 data/api/client-server/event_context.yaml     |  8 +++-
 data/api/client-server/filter.yaml            | 11 +++--
 data/api/client-server/inviting.yaml          |  8 +++-
 data/api/client-server/joining.yaml           | 11 +++--
 data/api/client-server/key_backup.yaml        | 47 +++++++++++++------
 data/api/client-server/keys.yaml              | 17 +++++--
 data/api/client-server/kicking.yaml           |  8 +++-
 data/api/client-server/knocking.yaml          |  8 +++-
 data/api/client-server/leaving.yaml           | 11 +++--
 data/api/client-server/list_joined_rooms.yaml |  8 +++-
 data/api/client-server/list_public_rooms.yaml | 12 ++++-
 data/api/client-server/login.yaml             |  5 +-
 data/api/client-server/login_token.yaml       |  8 +++-
 data/api/client-server/logout.yaml            | 11 +++--
 .../api/client-server/message_pagination.yaml |  8 +++-
 data/api/client-server/notifications.yaml     |  8 +++-
 data/api/client-server/old_sync.yaml          | 14 ++++--
 data/api/client-server/openid.yaml            |  8 +++-
 data/api/client-server/peeking_events.yaml    |  8 +++-
 data/api/client-server/presence.yaml          | 11 +++--
 data/api/client-server/profile.yaml           | 11 +++--
 data/api/client-server/pusher.yaml            | 11 +++--
 data/api/client-server/pushrules.yaml         | 29 ++++++++----
 data/api/client-server/read_markers.yaml      |  8 +++-
 data/api/client-server/receipts.yaml          |  8 +++-
 data/api/client-server/redaction.yaml         |  8 +++-
 data/api/client-server/registration.yaml      | 12 ++++-
 data/api/client-server/relations.yaml         | 14 ++++--
 data/api/client-server/report_content.yaml    |  8 +++-
 .../room_event_by_timestamp.yaml              |  8 +++-
 data/api/client-server/room_initial_sync.yaml |  8 +++-
 data/api/client-server/room_send.yaml         |  8 +++-
 data/api/client-server/room_state.yaml        |  8 +++-
 data/api/client-server/room_upgrades.yaml     |  8 +++-
 data/api/client-server/rooms.yaml             | 20 +++++---
 data/api/client-server/search.yaml            |  8 +++-
 data/api/client-server/space_hierarchy.yaml   |  8 +++-
 data/api/client-server/sync.yaml              |  8 +++-
 data/api/client-server/tags.yaml              | 14 ++++--
 .../api/client-server/third_party_lookup.yaml | 23 ++++++---
 .../client-server/third_party_membership.yaml |  8 +++-
 data/api/client-server/threads_list.yaml      |  8 +++-
 data/api/client-server/to_device.yaml         |  8 +++-
 data/api/client-server/typing.yaml            |  8 +++-
 data/api/client-server/users.yaml             |  8 +++-
 data/api/client-server/versions.yaml          |  8 +++-
 data/api/client-server/voip.yaml              |  8 +++-
 data/api/client-server/whoami.yaml            |  8 +++-
 data/api/identity/definitions/security.yaml   | 13 ++++-
 data/api/identity/v2_associations.yaml        | 14 ++++--
 data/api/identity/v2_auth.yaml                | 11 +++--
 data/api/identity/v2_email_associations.yaml  | 14 ++++--
 data/api/identity/v2_invitation_signing.yaml  |  8 +++-
 data/api/identity/v2_lookup.yaml              | 11 +++--
 data/api/identity/v2_phone_associations.yaml  | 14 ++++--
 data/api/identity/v2_store_invite.yaml        |  8 +++-
 data/api/identity/v2_terms.yaml               |  8 +++-
 data/api/server-server/backfill.yaml          |  3 +-
 .../server-server/definitions/security.yaml   |  8 ++--
 data/api/server-server/event_auth.yaml        |  3 +-
 data/api/server-server/events.yaml            |  3 +-
 data/api/server-server/invites-v1.yaml        |  3 +-
 data/api/server-server/invites-v2.yaml        |  3 +-
 data/api/server-server/joins-v1.yaml          |  3 +-
 data/api/server-server/joins-v2.yaml          |  3 +-
 data/api/server-server/knocks.yaml            |  3 +-
 data/api/server-server/leaving-v1.yaml        |  3 +-
 data/api/server-server/leaving-v2.yaml        |  3 +-
 data/api/server-server/public_rooms.yaml      |  3 +-
 data/api/server-server/query.yaml             |  3 +-
 data/api/server-server/space_hierarchy.yaml   |  3 +-
 .../api/server-server/third_party_invite.yaml |  3 +-
 data/api/server-server/transactions.yaml      |  3 +-
 data/api/server-server/user_devices.yaml      |  3 +-
 data/api/server-server/user_keys.yaml         |  3 +-
 98 files changed, 653 insertions(+), 246 deletions(-)
 create mode 100644 changelogs/application_service/newsfragments/1772.clarification
 create mode 100644 changelogs/client_server/newsfragments/1772.clarification
 create mode 100644 changelogs/identity_service/newsfragments/1772.clarification
 create mode 100644 changelogs/server_server/newsfragments/1772.clarification

diff --git a/changelogs/application_service/newsfragments/1772.clarification b/changelogs/application_service/newsfragments/1772.clarification
new file mode 100644
index 00000000..b2aafa0d
--- /dev/null
+++ b/changelogs/application_service/newsfragments/1772.clarification
@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1772.clarification b/changelogs/client_server/newsfragments/1772.clarification
new file mode 100644
index 00000000..b2aafa0d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1772.clarification
@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/identity_service/newsfragments/1772.clarification b/changelogs/identity_service/newsfragments/1772.clarification
new file mode 100644
index 00000000..b2aafa0d
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1772.clarification
@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1772.clarification b/changelogs/server_server/newsfragments/1772.clarification
new file mode 100644
index 00000000..b2aafa0d
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1772.clarification
@@ -0,0 +1 @@
+Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml
index b28d033a..b2ba1293 100644
--- a/data/api/application-service/definitions/security.yaml
+++ b/data/api/application-service/definitions/security.yaml
@@ -13,7 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 homeserverAccessToken:
-  type: apiKey
-  name: Authorization
-  in: header
+  type: http
+  scheme: bearer
   description: The `Bearer` `hs_token` provided by the application service's registration.
diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml
index 291f96fa..277955ff 100644
--- a/data/api/application-service/ping.yaml
+++ b/data/api/application-service/ping.yaml
@@ -69,4 +69,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken
diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml
index dddd26d4..194bdeef 100644
--- a/data/api/application-service/protocols.yaml
+++ b/data/api/application-service/protocols.yaml
@@ -339,4 +339,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken
diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml
index b5280e39..57175637 100644
--- a/data/api/application-service/query_room.yaml
+++ b/data/api/application-service/query_room.yaml
@@ -103,4 +103,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken
diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml
index 09503be1..c8ca9781 100644
--- a/data/api/application-service/query_user.yaml
+++ b/data/api/application-service/query_user.yaml
@@ -100,4 +100,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken
diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml
index 473def4b..a94434cc 100644
--- a/data/api/application-service/transactions.yaml
+++ b/data/api/application-service/transactions.yaml
@@ -88,4 +88,5 @@ servers:
         default: /_matrix/app/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    homeserverAccessToken:
+      $ref: definitions/security.yaml#/homeserverAccessToken
diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml
index bf89b21b..8fda4c39 100644
--- a/data/api/client-server/account-data.yaml
+++ b/data/api/client-server/account-data.yaml
@@ -26,7 +26,8 @@ paths:
         [/sync](#get_matrixclientv3sync).
       operationId: setAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -117,7 +118,8 @@ paths:
         that set the account data.
       operationId: getAccountData
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -186,7 +188,8 @@ paths:
         clients in the per-room entries via [/sync](#get_matrixclientv3sync).
       operationId: setAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -285,7 +288,8 @@ paths:
         visible to the user that set the account data.
       operationId: getAccountDataPerRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -379,4 +383,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/admin.yaml b/data/api/client-server/admin.yaml
index ec92eadb..19f084b7 100644
--- a/data/api/client-server/admin.yaml
+++ b/data/api/client-server/admin.yaml
@@ -27,7 +27,8 @@ paths:
         specified in this document.
       operationId: getWhoIs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml
index f2adefd1..a1f7be9d 100644
--- a/data/api/client-server/administrative_contact.yaml
+++ b/data/api/client-server/administrative_contact.yaml
@@ -31,7 +31,8 @@ paths:
         identifiers that it will accept to reset the user's account password.
       operationId: getAccount3PIDs
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The lookup was successful.
@@ -101,7 +102,8 @@ paths:
       operationId: post3PIDs
       deprecated: true
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -201,7 +203,8 @@ paths:
         already been added to another user's account on the homeserver.
       operationId: add3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -263,7 +266,8 @@ paths:
         Homeservers should track successful binds so they can be unbound later.
       operationId: bind3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -324,7 +328,8 @@ paths:
         identity server instead.
       operationId: delete3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -393,7 +398,8 @@ paths:
         identity server instead.
       operationId: unbind3pidFromAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -584,4 +590,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml
index 7102659e..5596119e 100644
--- a/data/api/client-server/appservice_ping.yaml
+++ b/data/api/client-server/appservice_ping.yaml
@@ -57,8 +57,8 @@ paths:
                   example: mautrix-go_1683636478256400935_123
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
-        - accessToken: []
+        - appserviceAccessTokenQuery: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The ping was successful.
@@ -177,6 +177,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
-    # server API, however this expects an access token for an application service.
-    $ref: definitions/security.yaml
+    appserviceAccessTokenQuery:
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer
diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml
index 2af58a22..b4ec42f0 100644
--- a/data/api/client-server/appservice_room_directory.yaml
+++ b/data/api/client-server/appservice_room_directory.yaml
@@ -67,8 +67,8 @@ paths:
                 - visibility
         required: true
       security:
-        # again, this is the appservice's token - not a typical client's
-        - accessToken: []
+        - appserviceAccessTokenQuery: []
+        - appserviceAccessTokenBearer: []
       responses:
         "200":
           description: The room's directory visibility has been updated.
@@ -95,6 +95,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    # Note: this is the same access_token definition used elsewhere in the client
-    # server API, however this expects an access token for an application service.
-    $ref: definitions/security.yaml
+    appserviceAccessTokenQuery:
+      $ref: definitions/security.yaml#/appserviceAccessTokenQuery
+    appserviceAccessTokenBearer:
+      $ref: definitions/security.yaml#/appserviceAccessTokenBearer
diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml
index 5185d89b..3cb9a540 100644
--- a/data/api/client-server/banning.yaml
+++ b/data/api/client-server/banning.yaml
@@ -27,7 +27,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: ban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -96,7 +97,8 @@ paths:
         The caller must have the required power level in order to perform this operation.
       operationId: unban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -169,4 +171,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml
index 96fdfb56..99f07962 100644
--- a/data/api/client-server/capabilities.yaml
+++ b/data/api/client-server/capabilities.yaml
@@ -24,7 +24,8 @@ paths:
         and other relevant capabilities.
       operationId: getCapabilities
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The capabilities of the server.
@@ -120,4 +121,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index f6913874..8a4aa4f6 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -22,7 +22,8 @@ paths:
       summary: Upload some content to the content repository.
       operationId: uploadContent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: header
           name: Content-Type
@@ -234,7 +235,8 @@ paths:
       operationId: createContent
       x-addedInMatrixVersion: "1.7"
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       # empty json object
       responses:
         "200":
@@ -782,7 +784,8 @@ paths:
         being shared should also not be shared with the homeserver.
       operationId: getUrlPreview
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: url
@@ -857,7 +860,8 @@ paths:
         than is advertised by the server on this endpoint.
       operationId: getConfig
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The public content repository configuration for the matrix server.
@@ -900,4 +904,7 @@ servers:
         default: /_matrix
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml
index 3c04de00..9e36d5e8 100644
--- a/data/api/client-server/create_room.yaml
+++ b/data/api/client-server/create_room.yaml
@@ -64,7 +64,8 @@ paths:
         `creation_content`.
       operationId: createRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -290,4 +291,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml
index 15d093c2..16539eb0 100644
--- a/data/api/client-server/cross_signing.yaml
+++ b/data/api/client-server/cross_signing.yaml
@@ -26,7 +26,8 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
       operationId: uploadCrossSigningKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -155,7 +156,8 @@ paths:
         property, which contains the new signature(s) to add.
       operationId: uploadCrossSigningSignatures
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -262,4 +264,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml
index 963e1d43..16ceb8ac 100644
--- a/data/api/client-server/definitions/security.yaml
+++ b/data/api/client-server/definitions/security.yaml
@@ -11,8 +11,36 @@
 # 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.
-accessToken:
+accessTokenQuery:
   type: apiKey
-  description: The access_token returned by a call to `/login` or `/register`
+  description: |-
+    The `access_token` returned by a call to `/login` or `/register`, as a query
+    parameter.
+
+    It can also be the `as_token` of an application service.
   name: access_token
   in: query
+accessTokenBearer:
+  type: http
+  description: |-
+    The `access_token` returned by a call to `/login` or `/register`, using the
+    `Authorization: Bearer` header.
+
+    It can also be the `as_token` of an application service.
+    
+    This is the preferred method.
+  scheme: bearer
+appserviceAccessTokenQuery:
+  type: apiKey
+  description: |-
+    The `as_token` of an application service, as a query parameter.
+  name: access_token
+  in: query
+appserviceAccessTokenBearer:
+  type: http
+  description: |-
+    The `as_token` of an application service, using the `Authorization: Bearer`
+    header.
+    
+    This is the preferred method.
+  scheme: bearer
diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml
index 32d3db9a..c4d1ce36 100644
--- a/data/api/client-server/device_management.yaml
+++ b/data/api/client-server/device_management.yaml
@@ -22,7 +22,8 @@ paths:
       description: Gets information about all devices for the current user.
       operationId: getDevices
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: Device information
@@ -58,7 +59,8 @@ paths:
       description: Gets information on a single device, by device id.
       operationId: getDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -93,7 +95,8 @@ paths:
       description: Updates the metadata on the given device.
       operationId: updateDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -140,7 +143,8 @@ paths:
         Deletes the given device, and invalidates any access token associated with it.
       operationId: deleteDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: deviceId
@@ -191,7 +195,8 @@ paths:
         Deletes the given devices, and invalidates any access token associated with them.
       operationId: deleteDevices
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -250,4 +255,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml
index df29fbf8..f5c357d9 100644
--- a/data/api/client-server/directory.yaml
+++ b/data/api/client-server/directory.yaml
@@ -21,7 +21,8 @@ paths:
       summary: Create a new mapping from room alias to room ID.
       operationId: setRoomAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomAlias
@@ -172,7 +173,8 @@ paths:
         have permission to update the `m.room.canonical_alias` event.
       operationId: deleteRoomAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomAlias
@@ -229,7 +231,8 @@ paths:
         state event.
       operationId: getLocalAliases
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -309,4 +312,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml
index 0d740241..0c927a6d 100644
--- a/data/api/client-server/event_context.yaml
+++ b/data/api/client-server/event_context.yaml
@@ -28,7 +28,8 @@ paths:
         [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getEventContext
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -154,4 +155,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml
index 8405f81e..805f79f8 100644
--- a/data/api/client-server/filter.yaml
+++ b/data/api/client-server/filter.yaml
@@ -25,7 +25,8 @@ paths:
         restrict which events are returned to the client.
       operationId: defineFilter
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -119,7 +120,8 @@ paths:
       summary: Download a filter
       operationId: getFilter
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -214,4 +216,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml
index ce5d503d..6aa9e08a 100644
--- a/data/api/client-server/inviting.yaml
+++ b/data/api/client-server/inviting.yaml
@@ -38,7 +38,8 @@ paths:
         `m.room.member` event to the room.
       operationId: inviteUser
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -136,4 +137,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml
index 020c5a0e..afd19fa8 100644
--- a/data/api/client-server/joining.yaml
+++ b/data/api/client-server/joining.yaml
@@ -33,7 +33,8 @@ paths:
         and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
       operationId: joinRoomById
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -126,7 +127,8 @@ paths:
         and [`/sync`](/client-server-api/#get_matrixclientv3sync) APIs.
       operationId: joinRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomIdOrAlias
@@ -229,4 +231,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml
index cd7cf5a0..464d4b4c 100644
--- a/data/api/client-server/key_backup.yaml
+++ b/data/api/client-server/key_backup.yaml
@@ -23,7 +23,8 @@ paths:
       description: Creates a new backup.
       operationId: postRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -80,7 +81,8 @@ paths:
       description: Get information about the latest backup version.
       operationId: getRoomKeysVersionCurrent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The information about the backup.
@@ -155,7 +157,8 @@ paths:
       description: Get information about an existing backup.
       operationId: getRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -242,7 +245,8 @@ paths:
         be modified.
       operationId: putRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -344,7 +348,8 @@ paths:
         as well as all key data related to the backup will be deleted.
       operationId: deleteRoomKeysVersion
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: version
@@ -396,7 +401,8 @@ paths:
       description: Store a key in the backup.
       operationId: putRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -478,7 +484,8 @@ paths:
       description: Retrieve a key from the backup.
       operationId: getRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -534,7 +541,8 @@ paths:
       description: Delete a key from the backup.
       operationId: deleteRoomKeyBySessionId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -606,7 +614,8 @@ paths:
       description: Store several keys in the backup for a given room.
       operationId: putRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -693,7 +702,8 @@ paths:
       description: Retrieve the keys from the backup for a given room.
       operationId: getRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -745,7 +755,8 @@ paths:
       description: Delete the keys from the backup for a given room.
       operationId: deleteRoomKeysByRoomId
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -810,7 +821,8 @@ paths:
       description: Store several keys in the backup.
       operationId: putRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -910,7 +922,8 @@ paths:
       description: Retrieve the keys from the backup.
       operationId: getRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -974,7 +987,8 @@ paths:
       description: Delete the keys from the backup.
       operationId: deleteRoomKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: version
@@ -1039,4 +1053,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index 3ec2a977..f5172ec9 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -24,7 +24,8 @@ paths:
       description: Publishes end-to-end encryption keys for the device.
       operationId: uploadKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -120,7 +121,8 @@ paths:
       description: Returns the current devices and identity keys for the given users.
       operationId: queryKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -283,7 +285,8 @@ paths:
       description: Claims one-time keys for use in pre-key messages.
       operationId: claimKeys
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -383,7 +386,8 @@ paths:
           identity keys, between `from` and `to`.
       operationId: getKeysChanges
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -453,4 +457,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml
index 6eaa8243..eb5b02d2 100644
--- a/data/api/client-server/kicking.yaml
+++ b/data/api/client-server/kicking.yaml
@@ -29,7 +29,8 @@ paths:
         the target member's state by making a request to `/rooms/<room id>/state/m.room.member/<user id>`.
       operationId: kick
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -103,4 +104,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml
index b778f02b..1eb6cde7 100644
--- a/data/api/client-server/knocking.yaml
+++ b/data/api/client-server/knocking.yaml
@@ -38,7 +38,8 @@ paths:
         [`/sync`](/client-server-api/#get_matrixclientv3sync) API.
       operationId: knockRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomIdOrAlias
@@ -144,4 +145,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml
index 6e7d67d0..6bdadb08 100644
--- a/data/api/client-server/leaving.yaml
+++ b/data/api/client-server/leaving.yaml
@@ -33,7 +33,8 @@ paths:
         they were previously allowed to see.
       operationId: leaveRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -91,7 +92,8 @@ paths:
         before calling this API.
       operationId: forgetRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -144,4 +146,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml
index 68451409..cec458c8 100644
--- a/data/api/client-server/list_joined_rooms.yaml
+++ b/data/api/client-server/list_joined_rooms.yaml
@@ -22,7 +22,8 @@ paths:
       description: This API returns a list of the user's current rooms.
       operationId: getJoinedRooms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: A list of the rooms the user is in.
@@ -61,4 +62,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml
index 678f52ad..497ccb44 100644
--- a/data/api/client-server/list_public_rooms.yaml
+++ b/data/api/client-server/list_public_rooms.yaml
@@ -74,7 +74,8 @@ paths:
         the room creator or a server administrator.
       operationId: setRoomVisibilityOnDirectory
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -175,7 +176,8 @@ paths:
         of joined members, with the largest rooms first.
       operationId: queryPublicRooms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: server
@@ -267,3 +269,9 @@ servers:
         default: localhost:8008
       basePath:
         default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
\ No newline at end of file
diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml
index a8953e65..6ae5d3a8 100644
--- a/data/api/client-server/login.yaml
+++ b/data/api/client-server/login.yaml
@@ -284,4 +284,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml
index d31607fb..a8ab1248 100644
--- a/data/api/client-server/login_token.yaml
+++ b/data/api/client-server/login_token.yaml
@@ -53,7 +53,8 @@ paths:
       operationId: generateLoginToken
       x-addedInMatrixVersion: "1.7"
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -131,4 +132,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/logout.yaml b/data/api/client-server/logout.yaml
index c3287472..60464932 100644
--- a/data/api/client-server/logout.yaml
+++ b/data/api/client-server/logout.yaml
@@ -25,7 +25,8 @@ paths:
         [Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
       operationId: logout
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The access token used in the request was successfully invalidated.
@@ -53,7 +54,8 @@ paths:
         this way.
       operationId: logout_all
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The user's access tokens were successfully invalidated.
@@ -78,4 +80,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml
index 07c16497..4d5c94e1 100644
--- a/data/api/client-server/message_pagination.yaml
+++ b/data/api/client-server/message_pagination.yaml
@@ -27,7 +27,8 @@ paths:
         [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
       operationId: getRoomEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -185,4 +186,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml
index 21d6640a..03db22af 100644
--- a/data/api/client-server/notifications.yaml
+++ b/data/api/client-server/notifications.yaml
@@ -24,7 +24,8 @@ paths:
         user has been, or would have been notified about.
       operationId: getNotifications
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -145,4 +146,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml
index 2d1e4f61..a1d0f497 100644
--- a/data/api/client-server/old_sync.yaml
+++ b/data/api/client-server/old_sync.yaml
@@ -29,7 +29,8 @@ paths:
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: getEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -99,7 +100,8 @@ paths:
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: initialSync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: limit
@@ -325,7 +327,8 @@ paths:
         or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
       operationId: getOneEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: eventId
@@ -366,4 +369,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml
index 2dbd1227..a65f9fef 100644
--- a/data/api/client-server/openid.yaml
+++ b/data/api/client-server/openid.yaml
@@ -30,7 +30,8 @@ paths:
         example.
       operationId: requestOpenIdToken
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -91,4 +92,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml
index b323d940..eaea5bbb 100644
--- a/data/api/client-server/peeking_events.yaml
+++ b/data/api/client-server/peeking_events.yaml
@@ -34,7 +34,8 @@ paths:
         yet known.
       operationId: peekEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: from
@@ -114,4 +115,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml
index caa19854..d3141911 100644
--- a/data/api/client-server/presence.yaml
+++ b/data/api/client-server/presence.yaml
@@ -26,7 +26,8 @@ paths:
         presence state of another user.
       operationId: setPresence
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -82,7 +83,8 @@ paths:
       description: Get the given user's presence state.
       operationId: getPresence
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -161,4 +163,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index b47cf591..e00bdd96 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -24,7 +24,8 @@ paths:
         set this user's display name, e.g. you need to have their `access_token`.
       operationId: setDisplayName
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -109,7 +110,8 @@ paths:
         set this user's avatar URL, e.g. you need to have their `access_token`.
       operationId: setAvatarUrl
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -269,4 +271,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml
index c686e9ae..b8997308 100644
--- a/data/api/client-server/pusher.yaml
+++ b/data/api/client-server/pusher.yaml
@@ -23,7 +23,8 @@ paths:
       description: Gets all currently active pushers for the authenticated user.
       operationId: getPushers
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The pushers for this user.
@@ -136,7 +137,8 @@ paths:
         user is deleted.
       operationId: postPusher
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -288,4 +290,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml
index 57638583..d009d351 100644
--- a/data/api/client-server/pushrules.yaml
+++ b/data/api/client-server/pushrules.yaml
@@ -26,7 +26,8 @@ paths:
         specified key e.g. the `global` key.
       operationId: getPushRules
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: All the push rulesets for this user.
@@ -242,7 +243,8 @@ paths:
       description: Retrieve a single specified push rule.
       operationId: getPushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -313,7 +315,8 @@ paths:
       description: This endpoint removes the push rule defined in the path.
       operationId: deletePushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -389,7 +392,8 @@ paths:
         When creating push rules, they MUST be enabled by default.
       operationId: setPushRule
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -527,7 +531,8 @@ paths:
       description: This endpoint gets whether the specified push rule is enabled.
       operationId: isPushRuleEnabled
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -598,7 +603,8 @@ paths:
         push rule.
       operationId: setPushRuleEnabled
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -676,7 +682,8 @@ paths:
       description: This endpoint get the actions for the specified push rule.
       operationId: getPushRuleActions
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -756,7 +763,8 @@ paths:
         This can be used to change the actions of builtin rules.
       operationId: setPushRuleActions
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: scope
@@ -849,4 +857,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml
index 5372df34..ba2f4f0b 100644
--- a/data/api/client-server/read_markers.yaml
+++ b/data/api/client-server/read_markers.yaml
@@ -25,7 +25,8 @@ paths:
         the read receipt's location.
       operationId: setReadMarker
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -96,4 +97,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml
index abbd7a62..c68ef3f6 100644
--- a/data/api/client-server/receipts.yaml
+++ b/data/api/client-server/receipts.yaml
@@ -25,7 +25,8 @@ paths:
         specified.
       operationId: postReceipt
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -132,4 +133,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml
index aca69fa6..a61f01c4 100644
--- a/data/api/client-server/redaction.yaml
+++ b/data/api/client-server/redaction.yaml
@@ -33,7 +33,8 @@ paths:
         Server administrators may redact events sent by users on their server.
       operationId: redactEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -103,4 +104,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml
index 5679d02c..afd30459 100644
--- a/data/api/client-server/registration.yaml
+++ b/data/api/client-server/registration.yaml
@@ -387,7 +387,8 @@ paths:
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       operationId: changePassword
       requestBody:
         content:
@@ -591,7 +592,8 @@ paths:
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       operationId: deactivateAccount
       requestBody:
         content:
@@ -757,3 +759,9 @@ servers:
         default: localhost:8008
       basePath:
         default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml
index 25c70199..b033e88f 100644
--- a/data/api/client-server/relations.yaml
+++ b/data/api/client-server/relations.yaml
@@ -31,7 +31,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEvents
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -88,7 +89,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEventsWithRelType
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -149,7 +151,8 @@ paths:
         page 1 and a `to` token from page 2 to paginate over the same range, however.
       operationId: getRelatingEventsWithRelTypeAndEventType
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/roomId'
         - $ref: '#/components/parameters/eventId'
@@ -217,7 +220,10 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
   parameters:
     roomId:
       in: path
diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml
index 9241705a..f30e189d 100644
--- a/data/api/client-server/report_content.yaml
+++ b/data/api/client-server/report_content.yaml
@@ -65,7 +65,8 @@ paths:
                   description: The reason the content is being reported. May be blank.
         required: true
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       x-changedInMatrixVersion:
         1.8: |
           This endpoint now requires the user to be joined to the room.
@@ -112,4 +113,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml
index 19e7302b..232950f5 100644
--- a/data/api/client-server/room_event_by_timestamp.yaml
+++ b/data/api/client-server/room_event_by_timestamp.yaml
@@ -46,7 +46,8 @@ paths:
         found in that direction is outside of the expected range.
       operationId: getEventByTimestamp
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -136,4 +137,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml
index 53cb0bee..6b34f331 100644
--- a/data/api/client-server/room_initial_sync.yaml
+++ b/data/api/client-server/room_initial_sync.yaml
@@ -15,7 +15,8 @@ paths:
         [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: roomInitialSync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -175,4 +176,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml
index 638dc86d..25d8a75b 100644
--- a/data/api/client-server/room_send.yaml
+++ b/data/api/client-server/room_send.yaml
@@ -30,7 +30,8 @@ paths:
         [Room Events](/client-server-api/#room-events) for the m. event specification.
       operationId: sendMessage
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -110,4 +111,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml
index 1c03dbdd..7096f511 100644
--- a/data/api/client-server/room_state.yaml
+++ b/data/api/client-server/room_state.yaml
@@ -39,7 +39,8 @@ paths:
         being removed or are already present in the state event.
       operationId: setRoomStateWithKey
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -142,4 +143,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/room_upgrades.yaml b/data/api/client-server/room_upgrades.yaml
index 296ffe6a..5109a9b7 100644
--- a/data/api/client-server/room_upgrades.yaml
+++ b/data/api/client-server/room_upgrades.yaml
@@ -22,7 +22,8 @@ paths:
       description: Upgrades the given room to a particular room version.
       operationId: upgradeRoom
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -106,4 +107,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml
index 4a192305..be5466b7 100644
--- a/data/api/client-server/rooms.yaml
+++ b/data/api/client-server/rooms.yaml
@@ -24,7 +24,8 @@ paths:
         retrieve this event e.g. by being a member in the room for this event.
       operationId: getOneRoomEvent
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -78,7 +79,8 @@ paths:
         taken from the state of the room when they left.
       operationId: getRoomStateWithKey
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -128,7 +130,8 @@ paths:
       description: Get the state events for the current state of a room.
       operationId: getRoomState
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -234,7 +237,8 @@ paths:
               - leave
               - ban
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: |-
@@ -284,7 +288,8 @@ paths:
           schema:
             type: string
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: A map of MXID to room member objects.
@@ -337,4 +342,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml
index 981f93aa..2d0475c5 100644
--- a/data/api/client-server/search.yaml
+++ b/data/api/client-server/search.yaml
@@ -22,7 +22,8 @@ paths:
       description: Performs a full text search across different categories.
       operationId: search
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: next_batch
@@ -374,4 +375,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml
index 9b33ee66..8378aee0 100644
--- a/data/api/client-server/space_hierarchy.yaml
+++ b/data/api/client-server/space_hierarchy.yaml
@@ -30,7 +30,8 @@ paths:
         rooms and parent events are not covered by this endpoint.
       operationId: getSpaceHierarchy
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -216,4 +217,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml
index 5e554722..3f06d13c 100644
--- a/data/api/client-server/sync.yaml
+++ b/data/api/client-server/sync.yaml
@@ -43,7 +43,8 @@ paths:
         events, alongside other state, when lazy-loading is not enabled.
       operationId: sync
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: filter
@@ -544,4 +545,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml
index f805e02f..5faed29c 100644
--- a/data/api/client-server/tags.yaml
+++ b/data/api/client-server/tags.yaml
@@ -23,7 +23,8 @@ paths:
       description: List the tags set by a user on a room.
       operationId: getRoomTags
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -83,7 +84,8 @@ paths:
       description: Add a tag to the room.
       operationId: setRoomTag
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -143,7 +145,8 @@ paths:
       description: Remove a tag from the room.
       operationId: deleteRoomTag
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -194,4 +197,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml
index 797f065f..1abcb771 100644
--- a/data/api/client-server/third_party_lookup.yaml
+++ b/data/api/client-server/third_party_lookup.yaml
@@ -25,7 +25,8 @@ paths:
         required for queries against each protocol.
       operationId: getProtocols
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The protocols supported by the homeserver.
@@ -42,7 +43,8 @@ paths:
         third-party protocol.
       operationId: getProtocolMetadata
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -85,7 +87,8 @@ paths:
         as reasonably possible given the network type.
       operationId: queryLocationByProtocol
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -129,7 +132,8 @@ paths:
         a set of user parameters.
       operationId: queryUserByProtocol
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: protocol
@@ -174,7 +178,8 @@ paths:
         alias.
       operationId: queryLocationByAlias
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: alias
@@ -209,7 +214,8 @@ paths:
       description: Retrieve an array of third-party users from a Matrix User ID.
       operationId: queryUserByID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: userid
@@ -252,4 +258,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml
index 7105ac84..ea366648 100644
--- a/data/api/client-server/third_party_membership.yaml
+++ b/data/api/client-server/third_party_membership.yaml
@@ -62,7 +62,8 @@ paths:
         append a `m.room.third_party_invite` event to the room.
       operationId: inviteBy3PID
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -157,4 +158,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/threads_list.yaml b/data/api/client-server/threads_list.yaml
index 8724b58d..1f16dde2 100644
--- a/data/api/client-server/threads_list.yaml
+++ b/data/api/client-server/threads_list.yaml
@@ -27,7 +27,8 @@ paths:
         user has participated in the thread.
       operationId: getThreadRoots
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: roomId
@@ -160,4 +161,7 @@ servers:
         default: /_matrix/client/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml
index d8832fa3..d8c0fff0 100644
--- a/data/api/client-server/to_device.yaml
+++ b/data/api/client-server/to_device.yaml
@@ -24,7 +24,8 @@ paths:
         client devices.
       operationId: sendToDevice
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: eventType
@@ -95,4 +96,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml
index 6d6a7437..0d21f452 100644
--- a/data/api/client-server/typing.yaml
+++ b/data/api/client-server/typing.yaml
@@ -26,7 +26,8 @@ paths:
         user has stopped typing.
       operationId: setTyping
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
@@ -96,4 +97,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml
index 67854f08..3a7f2bfa 100644
--- a/data/api/client-server/users.yaml
+++ b/data/api/client-server/users.yaml
@@ -32,7 +32,8 @@ paths:
         `Accept-Language` header provided in the request, if present.
       operationId: searchUserDirectory
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -122,4 +123,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml
index 7cf9a40e..bf4353f2 100644
--- a/data/api/client-server/versions.yaml
+++ b/data/api/client-server/versions.yaml
@@ -45,7 +45,8 @@ paths:
       operationId: getVersions
       security:
         - {}
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       x-changedInMatrixVersion:
         "1.10": |
           This endpoint can behave differently when authentication is provided.
@@ -101,4 +102,7 @@ servers:
         default: /_matrix/client
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/voip.yaml b/data/api/client-server/voip.yaml
index ea9146ec..4466e36c 100644
--- a/data/api/client-server/voip.yaml
+++ b/data/api/client-server/voip.yaml
@@ -24,7 +24,8 @@ paths:
         calls.
       operationId: getTurnServer
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The TURN server credentials.
@@ -86,4 +87,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml
index 342cbeb7..390fa773 100644
--- a/data/api/client-server/whoami.yaml
+++ b/data/api/client-server/whoami.yaml
@@ -30,7 +30,8 @@ paths:
         body.
       operationId: getTokenOwner
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token belongs to a known user.
@@ -112,4 +113,7 @@ servers:
         default: /_matrix/client/v3
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/definitions/security.yaml b/data/api/identity/definitions/security.yaml
index 64225ec4..f3c668c5 100644
--- a/data/api/identity/definitions/security.yaml
+++ b/data/api/identity/definitions/security.yaml
@@ -11,8 +11,17 @@
 # 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.
-accessToken:
+accessTokenQuery:
   type: apiKey
-  description: The access_token returned by a call to `/register`.
+  description: |-
+    The `access_token` returned by a call to `/register`, as a query parameter.
   name: access_token
   in: query
+accessTokenBearer:
+  type: http
+  description: |-
+    The `access_token` returned by a call to `/register`, using the
+    `Authorization: Bearer` header.
+    
+    This is the preferred method.
+  scheme: bearer
diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml
index c9b8ba6e..73de676e 100644
--- a/data/api/identity/v2_associations.yaml
+++ b/data/api/identity/v2_associations.yaml
@@ -23,7 +23,8 @@ paths:
       description: Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pidV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -128,7 +129,8 @@ paths:
         deprecated.
       operationId: bindV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -279,7 +281,8 @@ paths:
         homeserver is acting on behalf of a client.
       operationId: unbindV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -383,4 +386,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml
index 64433f81..cb41cdab 100644
--- a/data/api/identity/v2_auth.yaml
+++ b/data/api/identity/v2_auth.yaml
@@ -58,7 +58,8 @@ paths:
         request.
       operationId: getAccount
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token holder's information.
@@ -99,7 +100,8 @@ paths:
         future requests to the server.
       operationId: logout
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The token was successfully logged out.
@@ -150,4 +152,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml
index ad5c2517..81f4486c 100644
--- a/data/api/identity/v2_email_associations.yaml
+++ b/data/api/identity/v2_email_associations.yaml
@@ -40,7 +40,8 @@ paths:
         deprecated.
       operationId: emailRequestTokenV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -107,7 +108,8 @@ paths:
         deprecated.
       operationId: emailSubmitTokenPostV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -180,7 +182,8 @@ paths:
         used by end-users, and so the response should be human-readable.
       operationId: emailSubmitTokenGetV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -242,4 +245,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml
index ae05c6fd..104cafd6 100644
--- a/data/api/identity/v2_invitation_signing.yaml
+++ b/data/api/identity/v2_invitation_signing.yaml
@@ -27,7 +27,8 @@ paths:
         to `store-invite`, and fetch the sender of the invite.
       operationId: blindlySignStuffV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -132,4 +133,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml
index ce716abd..e3c7985f 100644
--- a/data/api/identity/v2_lookup.yaml
+++ b/data/api/identity/v2_lookup.yaml
@@ -28,7 +28,8 @@ paths:
         any of the algorithms defined in this specification.
       operationId: getHashDetails
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       responses:
         "200":
           description: The hash function information.
@@ -70,7 +71,8 @@ paths:
         later in this specification.
       operationId: lookupUsersV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -162,4 +164,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml
index 7f44fb3d..b985a972 100644
--- a/data/api/identity/v2_phone_associations.yaml
+++ b/data/api/identity/v2_phone_associations.yaml
@@ -40,7 +40,8 @@ paths:
         deprecated.
       operationId: msisdnRequestTokenV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -109,7 +110,8 @@ paths:
         deprecated.
       operationId: msisdnSubmitTokenPostV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -182,7 +184,8 @@ paths:
         used by end-users, and so the response should be human-readable.
       operationId: msisdnSubmitTokenGetV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - in: query
           name: sid
@@ -243,4 +246,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml
index 230dd503..5dcd9a78 100644
--- a/data/api/identity/v2_store_invite.yaml
+++ b/data/api/identity/v2_store_invite.yaml
@@ -51,7 +51,8 @@ paths:
         the `address` of the pending invite for display purposes.
       operationId: storeInviteV2
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -224,4 +225,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml
index 550d0bdb..d9eea90e 100644
--- a/data/api/identity/v2_terms.yaml
+++ b/data/api/identity/v2_terms.yaml
@@ -119,7 +119,8 @@ paths:
         may not be accepting all terms at once.
       operationId: agreeToTerms
       security:
-        - accessToken: []
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       requestBody:
         content:
           application/json:
@@ -159,4 +160,7 @@ servers:
         default: /_matrix/identity/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml
index a37e5ed4..ddcc6ab0 100644
--- a/data/api/server-server/backfill.yaml
+++ b/data/api/server-server/backfill.yaml
@@ -162,4 +162,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/definitions/security.yaml b/data/api/server-server/definitions/security.yaml
index 822b3fdf..8b91accd 100644
--- a/data/api/server-server/definitions/security.yaml
+++ b/data/api/server-server/definitions/security.yaml
@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 signedRequest:
-  type: apiKey
+  type: http
   description: |-
-    The `Authorization` header defined in the [Authentication](/server-server-api/#authentication) section.
-  name: Authorization
-  in: header
+    The `Authorization: X-Matrix` header defined in the [Authentication](/server-server-api/#authentication) 
+    section.
+  scheme: X-Matrix
diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml
index 99d2b3ac..18ec0072 100644
--- a/data/api/server-server/event_auth.yaml
+++ b/data/api/server-server/event_auth.yaml
@@ -75,4 +75,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml
index 009df48b..9087df97 100644
--- a/data/api/server-server/events.yaml
+++ b/data/api/server-server/events.yaml
@@ -285,4 +285,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml
index 270682d9..c328f05e 100644
--- a/data/api/server-server/invites-v1.yaml
+++ b/data/api/server-server/invites-v1.yaml
@@ -194,4 +194,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml
index 91dfca3a..8984b6d1 100644
--- a/data/api/server-server/invites-v2.yaml
+++ b/data/api/server-server/invites-v2.yaml
@@ -216,4 +216,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml
index d04e2ced..a56315d1 100644
--- a/data/api/server-server/joins-v1.yaml
+++ b/data/api/server-server/joins-v1.yaml
@@ -407,4 +407,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml
index 1182e100..8dcdaaf0 100644
--- a/data/api/server-server/joins-v2.yaml
+++ b/data/api/server-server/joins-v2.yaml
@@ -307,4 +307,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml
index 266e3368..f5b44003 100644
--- a/data/api/server-server/knocks.yaml
+++ b/data/api/server-server/knocks.yaml
@@ -355,4 +355,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml
index ee616323..a630f6d7 100644
--- a/data/api/server-server/leaving-v1.yaml
+++ b/data/api/server-server/leaving-v1.yaml
@@ -263,4 +263,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml
index 60064cfc..0db16cbe 100644
--- a/data/api/server-server/leaving-v2.yaml
+++ b/data/api/server-server/leaving-v2.yaml
@@ -148,4 +148,5 @@ servers:
         default: /_matrix/federation/v2
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml
index c81789ae..5bfa0f71 100644
--- a/data/api/server-server/public_rooms.yaml
+++ b/data/api/server-server/public_rooms.yaml
@@ -218,4 +218,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml
index 8d727a57..efb3a6c9 100644
--- a/data/api/server-server/query.yaml
+++ b/data/api/server-server/query.yaml
@@ -196,4 +196,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml
index 4ddfd1d0..1b9ba99c 100644
--- a/data/api/server-server/space_hierarchy.yaml
+++ b/data/api/server-server/space_hierarchy.yaml
@@ -228,4 +228,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml
index 3eac4811..76a7d2ff 100644
--- a/data/api/server-server/third_party_invite.yaml
+++ b/data/api/server-server/third_party_invite.yaml
@@ -329,4 +329,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml
index 1ca2ed3c..6edd04c3 100644
--- a/data/api/server-server/transactions.yaml
+++ b/data/api/server-server/transactions.yaml
@@ -111,4 +111,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml
index a0022f56..8a5669c4 100644
--- a/data/api/server-server/user_devices.yaml
+++ b/data/api/server-server/user_devices.yaml
@@ -120,4 +120,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml
index be50fcea..6007b304 100644
--- a/data/api/server-server/user_keys.yaml
+++ b/data/api/server-server/user_keys.yaml
@@ -252,4 +252,5 @@ servers:
         default: /_matrix/federation/v1
 components:
   securitySchemes:
-    $ref: definitions/security.yaml
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest

From 2ea8e0f514cfeb8742f502b6bdf3320da01876ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 9 Apr 2024 18:27:26 +0200
Subject: [PATCH 16/82] Remove enum for `POST /login` `type` definition (#1776)

Since the enum is not exhaustive, improve the description of the property instead.
---
 .../client_server/newsfragments/1776.clarification     |  1 +
 data/api/client-server/login.yaml                      | 10 ++++++----
 2 files changed, 7 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1776.clarification

diff --git a/changelogs/client_server/newsfragments/1776.clarification b/changelogs/client_server/newsfragments/1776.clarification
new file mode 100644
index 00000000..4d2def20
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1776.clarification
@@ -0,0 +1 @@
+Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response.
diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml
index 6ae5d3a8..b37d1742 100644
--- a/data/api/client-server/login.yaml
+++ b/data/api/client-server/login.yaml
@@ -109,10 +109,12 @@ paths:
               properties:
                 type:
                   type: string
-                  enum:
-                    - m.login.password
-                    - m.login.token
-                  description: The login type being used.
+                  description: |-
+                    The login type being used.
+
+                    This must be a type returned in one of the flows of the
+                    response of the [`GET /login`](/client-server-api/#get_matrixclientv3login)
+                    endpoint, like `m.login.password` or `m.login.token`.
                 identifier:
                   $ref: definitions/user_identifier.yaml
                 user:

From 2678370f2c52b383090e1af8d2b5667f0353b5a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 9 Apr 2024 19:06:53 +0200
Subject: [PATCH 17/82] Simplify uses of `resolve-refs` partial (#1773)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Use the resolve-refs partial as soon as possible

Call it right after accessing the site.Data,
since it is recursing it will solve all references in the tree.
That way we don't need to wonder where to call it,
we trust the validators that the refs will be used in the right place.

* Enable strict $ref rule in OpenAPI validator

* Document use of $ref to compose examples

* Fix schema path in event-fields shortcode

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1773.clarification      |  1 +
 layouts/partials/openapi/render-api.html           |  6 +-----
 layouts/partials/openapi/render-operation.html     |  6 ++----
 layouts/partials/openapi/render-parameters.html    |  3 ---
 layouts/partials/openapi/render-request.html       | 14 +++++---------
 layouts/partials/openapi/render-responses.html     |  7 +------
 layouts/shortcodes/event-fields.html               |  2 +-
 layouts/shortcodes/http-api.html                   |  4 +++-
 openapi_extensions.md                              |  5 +++++
 redocly.yaml                                       |  5 +++--
 10 files changed, 22 insertions(+), 31 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1773.clarification

diff --git a/changelogs/internal/newsfragments/1773.clarification b/changelogs/internal/newsfragments/1773.clarification
new file mode 100644
index 00000000..53d959d1
--- /dev/null
+++ b/changelogs/internal/newsfragments/1773.clarification
@@ -0,0 +1 @@
+Simplify uses of `resolve-refs` partial.
diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html
index 8af18e97..fcbb1cfc 100644
--- a/layouts/partials/openapi/render-api.html
+++ b/layouts/partials/openapi/render-api.html
@@ -5,15 +5,11 @@
   * `api_data`: the OpenAPI data
   * `base_url`: the base URL: that is, the part we glue onto the front
   of each value in `paths` to get a complete URL.
-  * `path`: the directory under /data where we found this API definition.
-  We use this to resolve "$ref" values, since they are relative to the schema's
-  location.
 
 */}}
 
 {{ $api_data := index .api_data }}
 {{ $base_url := .base_url }}
-{{ $path := .path }}
 
 {{ range $path_name, $path_data := $api_data.paths }}
 
@@ -21,7 +17,7 @@
 
     {{/* note that a `paths` entry can be a $ref */}}
 
-    {{ $params := dict "endpoint" $endpoint "path" $path }}
+    {{ $params := dict "endpoint" $endpoint }}
 
     {{ with $path_data.get }}
 
diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
index 253e2efe..8c6fce0e 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/layouts/partials/openapi/render-operation.html
@@ -5,7 +5,6 @@
   * `method`: the method, e.g. GET, PUT
   * `endpoint`: the endpoint
   * `operation_data`: the OpenAPI data for the operation
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
 
   This template renders the operation as a `<section>` containing:
 
@@ -21,7 +20,6 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
-{{ $path := .path }}
 {{ $anchor := anchorize $endpoint }}
 
 <section class="rendered-data http-api {{ $method }}">
@@ -80,9 +78,9 @@
 </table>
 
 <hr/>
-{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }}
+{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "anchor_base" $anchor ) }}
 <hr/>
-{{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path "anchor_base" $anchor ) }}
+{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "anchor_base" $anchor ) }}
 
 </details>
 
diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html
index ecabfc05..1cd263a3 100644
--- a/layouts/partials/openapi/render-parameters.html
+++ b/layouts/partials/openapi/render-parameters.html
@@ -5,7 +5,6 @@
   * `parameters`: OpenAPI data specifying the parameters
   * `type`: the type of parameters to render: "header, ""path", "query"
   * `caption`: caption to use for the table
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
 
   This template renders a single table containing parameters of the given type.
 
@@ -14,9 +13,7 @@
 {{ $parameters := .parameters }}
 {{ $type := .type }}
 {{ $caption := .caption }}
-{{ $path := .path }}
 
-{{ $parameters = partial "json-schema/resolve-refs" (dict "schema" $parameters "path" $path) }}
 {{ $parameters_of_type := where $parameters "in" $type }}
 
 {{ with $parameters_of_type }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index f41e062d..d922b64e 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -4,7 +4,6 @@
 
   * `parameters`: OpenAPI data specifying the parameters
   * `request_body`: OpenAPI data specifying the request body
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
   * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
@@ -16,7 +15,6 @@
 
 {{ $parameters := .parameters }}
 {{ $request_body := .request_body }}
-{{ $path := .path }}
 {{ $anchor_base := .anchor_base }}
 
 <h2>Request</h2>
@@ -26,9 +24,9 @@
     {{ if $parameters }}
 <h3>Request parameters</h3>
 
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters" "path" .path) }}
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters" "path" .path) }}
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters" "path" .path) }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters") }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters") }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters") }}
 
     {{ end }}
 
@@ -42,8 +40,7 @@
             {{/*
                 Display the JSON schemas
             */}}
-            {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }}
-            {{ $schema := partial "json-schema/resolve-allof" $schema }}
+            {{ $schema := partial "json-schema/resolve-allof" $json_body.schema }}
 
             {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
             {{ range $additional_types }}
@@ -70,8 +67,7 @@
             {{ $example := dict }}
 
             {{ if $body.schema }}
-                {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }}
-                {{ $schema := partial "json-schema/resolve-allof" $schema }}
+                {{ $schema := partial "json-schema/resolve-allof" $body.schema }}
 
                 {{ $example = partial "json-schema/resolve-example" $schema }}
             {{ end }}
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index dba7fa8b..437e811a 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -3,7 +3,6 @@
   Render the response part of a single HTTP API operation, given:
 
   * `responses`: OpenAPI data specifying the responses
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
   * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
@@ -15,7 +14,6 @@
 */}}
 
 {{ $responses := .responses }}
-{{ $path := .path }}
 {{ $anchor_base := .anchor_base }}
 
 <h2>Responses</h2>
@@ -26,8 +24,6 @@
   <th class="col-status-description">Description</th>
  </thead>
 
-{{ $responses = partial "json-schema/resolve-refs" (dict "schema" $responses "path" $path) }}
-
 {{ range $code, $response := $responses }}
 
  <tr>
@@ -92,8 +88,7 @@
             {{ if or (eq $schema.type "object") (eq $schema.type "array") }}
                 {{ $example := partial "json-schema/resolve-example" $schema }}
                 {{ if $json_body.examples }}
-                    {{ $example = partial "json-schema/resolve-refs" (dict "schema" $json_body.examples "path" $path) }}
-                    {{ $example = $example.response.value }}
+                    {{ $example = $json_body.examples.response.value }}
                 {{ end }}
 
                 {{ $example_json := jsonify (dict "indent" "  ") $example }}
diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html
index 91e2faf2..e06d77ee 100644
--- a/layouts/shortcodes/event-fields.html
+++ b/layouts/shortcodes/event-fields.html
@@ -13,7 +13,7 @@
 */}}
 
 {{ $event := index .Site.Data "event-schemas" "schema" "core-event-schema" .Params.event_type }}
-{{ $path := "event-schemas/schema/core-event-schema" }}
+{{ $path := delimit (slice "event-schemas/schema/core-event-schema" .Params.event_type) "/" }}
 
 {{ $event = partial "json-schema/resolve-refs" (dict "schema" $event "path" $path) }}
 {{ $event := partial "json-schema/resolve-allof" $event }}
diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html
index 43d08b9e..28e76400 100644
--- a/layouts/shortcodes/http-api.html
+++ b/layouts/shortcodes/http-api.html
@@ -23,4 +23,6 @@
 {{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
 {{ $path := delimit (slice "api" $spec $api) "/" }}
 
-{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }}
+{{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
+
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}
diff --git a/openapi_extensions.md b/openapi_extensions.md
index 15b93adc..8a7146a9 100644
--- a/openapi_extensions.md
+++ b/openapi_extensions.md
@@ -26,3 +26,8 @@ property, etc).
 
 A variation of the above: indicates changes to the associated parameter in
 particular Matrix specification versions.
+
+## Use of `$ref` inside examples
+
+Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
+whole example, we use it to compose examples from other examples.
diff --git a/redocly.yaml b/redocly.yaml
index 263f0bca..28dda2db 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -1,10 +1,11 @@
 # See https://redocly.com/docs/cli/configuration/ for more information.
 extends:
-  - minimal
+  - recommended-strict
 rules:
   info-license: off
   security-defined: off
   operation-4xx-response: off
   no-invalid-media-type-examples: off
   no-path-trailing-slash: off
-  operation-2xx-response: off
\ No newline at end of file
+  operation-2xx-response: off
+  spec-strict-refs: error
\ No newline at end of file

From becc6676725252aa951e999c91e58ec143d16454 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 10 Apr 2024 07:16:01 +0100
Subject: [PATCH 18/82] Update github-labels.rst (#1781)

Fix formatting
---
 .../internal/newsfragments/1781.clarification      |  1 +
 meta/github-labels.rst                             | 14 +++++++-------
 2 files changed, 8 insertions(+), 7 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1781.clarification

diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification
new file mode 100644
index 00000000..4fb58650
--- /dev/null
+++ b/changelogs/internal/newsfragments/1781.clarification
@@ -0,0 +1 @@
+Fix `github-labels.rst`
diff --git a/meta/github-labels.rst b/meta/github-labels.rst
index 14fb9f69..44c52185 100644
--- a/meta/github-labels.rst
+++ b/meta/github-labels.rst
@@ -1,7 +1,7 @@
 The following labels are used to help categorize issues:
 
 `spec-omission <https://github.com/matrix-org/matrix-spec/labels/spec-omission>`_
---------------------------------------------------------------------------------
+---------------------------------------------------------------------------------
 
 Things which have been implemented but not currently specified. These may range
 from entire API endpoints, to particular options or return parameters.
@@ -17,7 +17,7 @@ Examples:
   <https://github.com/matrix-org/matrix-doc/issues/904>`_
 
 `clarification <https://github.com/matrix-org/matrix-spec/labels/clarification>`_
---------------------------------------------------------------------------------
+---------------------------------------------------------------------------------
 
 An area where the spec could do with being more explicit.
 
@@ -30,7 +30,7 @@ Examples:
   <https://github.com/matrix-org/matrix-doc/issues/686>`_
 
 `spec-bug <https://github.com/matrix-org/matrix-spec/labels/spec-bug>`_
-----------------------------------------------------------------------
+-----------------------------------------------------------------------
 
 Something which is in the spec, but is wrong.
 
@@ -47,7 +47,7 @@ Examples:
   <https://github.com/matrix-org/matrix-doc/issues/695>`_
 
 `improvement <https://github.com/matrix-org/matrix-spec/labels/improvement>`_
-----------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 
 A suggestion for a relatively simple improvement to the protocol.
 
@@ -59,7 +59,7 @@ Examples:
   <https://github.com/matrix-org/matrix-spec/issues/145>`_
 
 `feature <https://github.com/matrix-org/matrix-spec/labels/feature>`_
---------------------------------------------------------------------
+---------------------------------------------------------------------
 
 A suggestion for a significant extension to the matrix protocol which
 needs considerable consideration before implementation.
@@ -72,7 +72,7 @@ Examples:
 
 
 `wart <https://github.com/matrix-org/matrix-spec/labels/wart>`_
---------------------------------------------------------------
+---------------------------------------------------------------
 
 A point where the protocol is inconsistent or inelegant, but which isn't really
 causing anybody any problems right now. Might be nice to consider fixing one
@@ -80,7 +80,7 @@ day.
 
 
 `question <https://github.com/matrix-org/matrix-spec/labels/question>`_
-----------------------------------------------------------------------
+-----------------------------------------------------------------------
 
 A thought or idea about the protocol which we aren't really sure whether to
 pursue or not.

From a81b72015131eae45ba19deb9935b37422ec4ffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 16 Apr 2024 18:59:12 +0200
Subject: [PATCH 19/82] Upgrade CI scripts dependencies (#1786)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Will allow us to benefit from future fixes in JSON Schema validation.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1786.clarification    |  1 +
 scripts/check-event-schema-examples.py           | 13 ++++++++++---
 scripts/check-json-schemas.py                    | 16 ++++++++++++----
 scripts/check-openapi-sources.py                 | 13 +++++++++++--
 scripts/helpers.py                               | 14 +++++++++++++-
 scripts/requirements.txt                         |  7 ++++---
 6 files changed, 51 insertions(+), 13 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1786.clarification

diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification
new file mode 100644
index 00000000..1810c632
--- /dev/null
+++ b/changelogs/internal/newsfragments/1786.clarification
@@ -0,0 +1 @@
+Upgrade jsonschema and python-jsonpath CI scripts dependencies.
diff --git a/scripts/check-event-schema-examples.py b/scripts/check-event-schema-examples.py
index 9058ff4e..fae129f6 100755
--- a/scripts/check-event-schema-examples.py
+++ b/scripts/check-event-schema-examples.py
@@ -42,6 +42,12 @@ except ImportError as e:
     import_error("jsonschema", "jsonschema", "jsonschema", e)
     raise
 
+try:
+    import referencing
+except ImportError as e:
+    import_error("referencing", "referencing", "referencing", e)
+    raise
+
 try:
     import yaml
 except ImportError as e:
@@ -56,13 +62,14 @@ def check_example_file(examplepath, schemapath):
     with open(schemapath) as f:
         schema = yaml.safe_load(f)
 
+    # $id as a URI with scheme is necessary to make registry resolver work.
     fileurl = "file://" + os.path.abspath(schemapath)
-    schema["id"] = fileurl
-    resolver = jsonschema.RefResolver(fileurl, schema, handlers={"file": helpers.load_file_from_uri})
+    schema["$id"] = fileurl
 
     print ("Checking schema for: %r %r" % (examplepath, schemapath))
     try:
-        validator = jsonschema.Draft202012Validator(schema, resolver)
+        registry = referencing.Registry(retrieve=helpers.load_resource_from_uri)
+        validator = jsonschema.validators.Draft202012Validator(schema, registry=registry)
         validator.validate(example)
     except Exception as e:
         raise ValueError("Error validating JSON schema for %r %r" % (
diff --git a/scripts/check-json-schemas.py b/scripts/check-json-schemas.py
index 06b24106..5e0ceaa3 100755
--- a/scripts/check-json-schemas.py
+++ b/scripts/check-json-schemas.py
@@ -42,6 +42,12 @@ except ImportError as e:
     import_error("jsonschema", "jsonschema", "jsonschema", e)
     raise
 
+try:
+    import referencing
+except ImportError as e:
+    import_error("referencing", "referencing", "referencing", e)
+    raise
+
 try:
     import yaml
 except ImportError as e:
@@ -70,10 +76,12 @@ class SchemaDirReport:
         self.errors += other_report.errors
         
 def check_example(path, schema, example):
-    # URI with scheme is necessary to make RefResolver work.
+    # $id as a URI with scheme is necessary to make registry resolver work.
     fileurl = "file://" + os.path.abspath(path)
-    resolver = jsonschema.RefResolver(fileurl, schema, handlers={"file": helpers.load_file_from_uri})
-    validator = jsonschema.Draft202012Validator(schema, resolver)
+    schema["$id"] = fileurl
+
+    registry = referencing.Registry(retrieve=helpers.load_resource_from_uri)
+    validator = jsonschema.validators.Draft202012Validator(schema, registry=registry)
 
     validator.validate(example)
 
@@ -128,7 +136,7 @@ def check_schema_file(schema_path):
 
     # Check schema is valid.
     try:
-        validator = jsonschema.Draft202012Validator
+        validator = jsonschema.validators.Draft202012Validator
         validator.check_schema(schema)
     except Exception as e:
         print(f"Failed to validate JSON schema: {e}")
diff --git a/scripts/check-openapi-sources.py b/scripts/check-openapi-sources.py
index 7f28d860..4ba0392e 100755
--- a/scripts/check-openapi-sources.py
+++ b/scripts/check-openapi-sources.py
@@ -42,6 +42,12 @@ except ImportError as e:
     import_error("jsonschema", "jsonschema", "jsonschema", e)
     raise
 
+try:
+    import referencing
+except ImportError as e:
+    import_error("referencing", "referencing", "referencing", e)
+    raise
+
 try:
     import yaml
 except ImportError as e:
@@ -50,8 +56,11 @@ except ImportError as e:
 
 
 def check_schema(filepath, example, schema):
-    resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": helpers.load_file_from_uri})
-    validator = jsonschema.Draft202012Validator(schema, resolver)
+    # $id as a URI with scheme is necessary to make registry resolver work.
+    schema["$id"] = filepath
+
+    registry = referencing.Registry(retrieve=helpers.load_resource_from_uri)
+    validator = jsonschema.validators.Draft202012Validator(schema, registry=registry)
     validator.validate(example)
 
 
diff --git a/scripts/helpers.py b/scripts/helpers.py
index c35e8e2a..a30b2831 100755
--- a/scripts/helpers.py
+++ b/scripts/helpers.py
@@ -19,6 +19,7 @@
 import json
 import os
 import os.path
+import referencing
 import urllib.parse
 import yaml
 
@@ -84,4 +85,15 @@ def load_file_from_uri(path):
         else:
             # We have to assume it's YAML because some of the YAML examples
             # do not have file extensions.
-            return yaml.safe_load(f)
\ No newline at end of file
+            return yaml.safe_load(f)
+
+def load_resource_from_uri(path):
+    """Load a JSON or YAML JSON Schema, as a `referencing.Resource` object, from
+    a file:// URI.
+    """
+    contents = load_file_from_uri(path)    
+    resource = referencing.Resource(
+        contents=contents,
+        specification=referencing.jsonschema.DRAFT202012
+    )
+    return resource
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
index 5878b9cc..4d508bf4 100644
--- a/scripts/requirements.txt
+++ b/scripts/requirements.txt
@@ -1,10 +1,11 @@
 # no doubt older versions would be fine for many of these but these were
 # current at the time of writing
 
-# we need at least version 4.0.0 for support of JSON Schema Draft 2020-12.
-jsonschema == 4.17.3
+# we need at least version 4.18.0 for support of referencing library.
+jsonschema >= 4.18.0
+referencing >= 0.28.4
 
-python-jsonpath == 0.9.0
+python-jsonpath >= 1.0.0
 attrs >= 23.1.0
 PyYAML >= 3.12
 requests >= 2.18.4

From 521e555cf6ba951b3768fb9313c8ef5fbff991e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 16 Apr 2024 19:00:06 +0200
Subject: [PATCH 20/82] Bump minimum Hugo version in README (#1788)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

To match the one in config.toml

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 README.md                                            | 2 +-
 changelogs/internal/newsfragments/1788.clarification | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/internal/newsfragments/1788.clarification

diff --git a/README.md b/README.md
index 8b40c0f5..17fa5614 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.110.0 is required.
+   v0.113.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
diff --git a/changelogs/internal/newsfragments/1788.clarification b/changelogs/internal/newsfragments/1788.clarification
new file mode 100644
index 00000000..649503a0
--- /dev/null
+++ b/changelogs/internal/newsfragments/1788.clarification
@@ -0,0 +1 @@
+Fix Hugo warnings.

From f4e7b2aa97bda9766ae7225b8495b87ecc99ef4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 16 Apr 2024 19:25:33 +0200
Subject: [PATCH 21/82] Fix property type resolution in render-object-table
 (#1789)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The split was not clear between property-type and type-or-title,
so it was not obvious which partial should be called for recursion.
That resulted in an error where type-or-title was only called for objects and array items, even if it also resolves
arrays of types.

This makes the split clearer. property-type must be called for any schema,
and object-type-or-title is only called for object schemas.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1789.clarification |  1 +
 .../partials/openapi/render-object-table.html | 98 +++++++++----------
 2 files changed, 49 insertions(+), 50 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1789.clarification

diff --git a/changelogs/internal/newsfragments/1789.clarification b/changelogs/internal/newsfragments/1789.clarification
new file mode 100644
index 00000000..f90c8934
--- /dev/null
+++ b/changelogs/internal/newsfragments/1789.clarification
@@ -0,0 +1 @@
+Fix property type resolution in `render-object-table` partial.
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 47be51ec..7c0be431 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -78,20 +78,20 @@
 {{ end }}
 
 {{/*
-    Computes the type to display for a property, given:
+    Computes the type to display for a property's schema, given:
 
-    * `type`: string or array of strings for the type(s) of the property
+    * `type`: optional string or array of strings for the type(s) of the property
 
     * `title`: optional string for the title of the property
 
     * `oneOf`: optional array of dictionaries describing the different formats
       that the property can have
 
-    * `additionalProperties`: optional dictionary for properties with undefined
-      names
+    * `additionalProperties`: if the type is an object, optional dictionary for
+      properties with undefined names
 
-    * `patternProperties`: optional dictionary for properties with names
-      adhering to a regex pattern
+    * `patternProperties`: if the type is an object, optional dictionary for
+      properties with names adhering to a regex pattern
 
     * `items`: if the type is an array, array of dictionaries describing the
       format of the array's items
@@ -100,37 +100,59 @@
 
 */}}
 {{ define "partials/property-type" }}
-    {{ $type := .type }}
+    {{ $type := "" }}
 
-    {{ if or (eq .type "object") (and .oneOf (reflect.IsSlice .oneOf)) }}
-        {{ $type = partial "type-or-title" . }}
-    {{ end }}
-
-    {{/*
-        If the property is an array, indicate this with square brackets,
-        like `[type]`.
-    */}}
-    {{ if eq .type "array"}}
+    {{ if eq .type "object" }}
+        {{/* Resolve the type or title of the object */}}
+        {{ $type = partial "object-type-or-title" . }}
+    {{ else if eq .type "array"}}
+        {{/*
+            If the property is an array, indicate this with square brackets,
+            like `[type]`.
+        */}}
         {{ $items := .items }}
         {{ if .items }}
             {{ $items = partial "json-schema/resolve-allof" .items }}
         {{ end }}
-        {{ $inner_type := partial "type-or-title" $items }}
+        {{ $inner_type := partial "property-type" $items }}
         {{ $type = delimit (slice "[" $inner_type "]") "" }}
+    {{ else if or (reflect.IsSlice .type) .oneOf }}
+        {{/*
+            It's legal to specify an array of types.
+            
+            There are two ways to do that:
+              - Use an array of strings.
+              - Use oneOf, with items having a schema.
+
+            Join them together in that case, like `type|other_type`.
+        */}}
+        {{ $types := slice }}
+
+        {{ if .oneOf }}
+            {{ range .oneOf }}
+                {{ $types = $types | append (partial "property-type" .) }}
+            {{ end }}
+        {{ else }}
+            {{ range .type }}
+                {{ $types = $types | append . }}
+            {{ end }}
+        {{ end }}
+
+        {{ $type = delimit $types "|" }}
+    {{ else }}
+        {{/* A simple type like string or boolean */}}
+        {{ $type = .type }}
     {{ end }}
 
     {{ return $type }}
 {{ end }}
 
 {{/*
-    Computes the type to display for a property's schema, given:
+    Computes the type to display for an object property's schema, given:
 
-    * `type`: string or array of strings for the type(s) of the property
+    * `type`: string equal to "object"
 
-    * `title`: optional string for the title of the property
-
-    * `oneOf`: optional array of dictionaries describing the different formats
-      that the property can have
+    * `title`: optional string for the title of the object property
 
     * `additionalProperties`: optional dictionary for properties with undefined
       names
@@ -142,8 +164,8 @@
 
     The title has a higher priority than anything else.
 */}}
-{{ define "partials/type-or-title" }}
-    {{ $type := "" }}
+{{ define "partials/object-type-or-title" }}
+    {{ $type := "object" }}
     {{ if .title }}
         {{/*
             If the property has a `title`, use that rather than `type`.
@@ -176,32 +198,8 @@
         {{ end }}
 
         {{ $type = delimit (slice "{string: " (delimit $types "|") "}" ) "" }}
-    {{ else if reflect.IsSlice .type }}
-        {{/* It's legal to specify an array of types. Join them together in that case */}}
-
-        {{ $types := slice }}
-
-        {{ range .type }}
-            {{ $types = $types | append . }}
-        {{ end }}
-
-        {{ $type = delimit $types "|" }}
-    {{ else if and .oneOf (reflect.IsSlice .oneOf) }}
-        {{/*
-            This is like an array of types except some of the types probably have a schema.
-            Join them together too.
-        */}}
-
-        {{ $types := slice }}
-
-        {{ range .oneOf }}
-            {{ $types = $types | append (partial "type-or-title" .) }}
-        {{ end }}
-
-        {{ $type = delimit $types "|" }}
-    {{ else }}
-        {{ $type = .type }}
     {{ end }}
+
     {{ return $type }}
 {{ end }}
 

From 073ce659df13aa90d3abea4458597dc9210f869d Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 17 Apr 2024 09:22:06 +0100
Subject: [PATCH 22/82] Define opaque identifier grammar (#1791)

Since we already have three of these, and I'm about to add a fourth, let's pull
it out to a common definition.

We could, of course, keep defining the grammar each time it's used, but
defining it in an appendix helps us be consistent for future API design.
---
 .../newsfragments/1791.clarification          |  1 +
 content/appendices.md                         | 19 +++++++++++++++++++
 content/client-server-api/_index.md           | 13 +++++++------
 .../client-server-api/modules/voip_events.md  |  7 +------
 .../definitions/sso_login_flow.yaml           |  5 +----
 5 files changed, 29 insertions(+), 16 deletions(-)
 create mode 100644 changelogs/appendices/newsfragments/1791.clarification

diff --git a/changelogs/appendices/newsfragments/1791.clarification b/changelogs/appendices/newsfragments/1791.clarification
new file mode 100644
index 00000000..22f59c5a
--- /dev/null
+++ b/changelogs/appendices/newsfragments/1791.clarification
@@ -0,0 +1 @@
+Define 'Opaque Identifier Grammar'.
diff --git a/content/appendices.md b/content/appendices.md
index a5ddb7bf..cdaf2629 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -921,6 +921,25 @@ unique servers based on the following criteria:
     specify the servers it can. For example, a room with only 2 users in
     it would result in maximum 2 `via` parameters.
 
+### Opaque Identifiers
+
+The specification defines some identifiers to use the *Opaque Identifier
+Grammar*. This is a common grammar intended for non-user-visible identifiers
+which do not require parsing or interpretation (other than as a unique
+identifier).
+
+The grammar is defined as:
+
+* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
+  `[a-z]`, `-`, `.`, `_`, and `~`.
+* Unless otherwise specified, identifiers must be at least one character and at
+  most 255 characters in length.
+
+{{% boxes/note %}}
+The acceptable character set matches the unreserved character set in [RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 5889ec0f..8c017e62 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -943,11 +943,12 @@ or completely closed registration (where the homeserver administrators create
 and distribute accounts).
 
 The token required for this authentication type is shared out of band from
-Matrix and is an opaque string with maximum length of 64 characters in the
-range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any
-length of time/validity. Such cases might be a token limited to 100 uses or
-for the next 2 hours - after the tokens expire, they can no longer be used
-to create accounts.
+Matrix and is an opaque string using the [Opaque Identifier
+Grammar](/appendices#opaque-identifiers), with maximum length of 64
+characters. The server can keep any number of tokens for any length of
+time/validity. Such cases might be a token limited to 100 uses or for the next
+2 hours - after the tokens expire, they can no longer be used to create
+accounts.
 
 To use this authentication type, clients should submit an auth dict with just
 the type, token, and session:
@@ -1201,7 +1202,7 @@ is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
 {{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
-a token for their user ID if supported by the homeserver using 
+a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
 
 {{% http-api spec="client-server" api="login" %}}
diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md
index c45a4824..14b7d796 100644
--- a/content/client-server-api/modules/voip_events.md
+++ b/content/client-server-api/modules/voip_events.md
@@ -96,13 +96,8 @@ Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of A
 in the RTP payload.
 
 #### Grammar for VoIP IDs
-`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
-of the characters `[0-9a-zA-Z._~-]`.
 
-(Note that this matches the grammar of 'opaque IDs' from
-[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
-and that of the `id` property of the
- [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
+`call_id`s and `party_id` must follow the [Opaque Identifier Grammar](/appendices#opaque-identifiers).
 
 #### Behaviour on Room Leave
 If the client sees the user it is in a call with leave the room, the client should treat this
diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml
index e30b18f9..3b95e664 100644
--- a/data/api/client-server/definitions/sso_login_flow.yaml
+++ b/data/api/client-server/definitions/sso_login_flow.yaml
@@ -40,10 +40,7 @@ properties:
           description: |-
             Opaque string chosen by the homeserver, uniquely identifying
             the IdP from other IdPs the homeserver might support. Should
-            be between 1 and 255 characters in length, containing unreserved
-            characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
-            (`ALPHA  DIGIT  "-" / "." / "_" / "~"`). Clients are not intended
-            to parse or infer meaning from opaque strings.
+            use the [Opaque identifier Grammar](/appendices#opaque-identifiers).
           example: "com.example.idp.github"
         name:
           type: string

From e82829d4a24056286b917228fa1cf8d2d89ffb1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 17 Apr 2024 10:29:34 +0200
Subject: [PATCH 23/82] Make resolve-allof partial recursive (#1787)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Makes it easier to use, like resolve-refs. It just needs to be called once.

Fixes an issue with m.call.* events not displaying the common fields

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 .../internal/newsfragments/1787.clarification |   1 +
 .../json-schema/resolve-additional-types.html |  11 +-
 .../partials/json-schema/resolve-allof.html   | 115 +++++++-----------
 .../partials/json-schema/resolve-example.html |   2 +-
 .../partials/openapi/render-object-table.html |  12 +-
 layouts/partials/openapi/render-request.html  |   6 +-
 .../partials/openapi/render-responses.html    |   2 +-
 layouts/shortcodes/http-api.html              |   1 +
 8 files changed, 56 insertions(+), 94 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1787.clarification

diff --git a/changelogs/internal/newsfragments/1787.clarification b/changelogs/internal/newsfragments/1787.clarification
new file mode 100644
index 00000000..5d2d1378
--- /dev/null
+++ b/changelogs/internal/newsfragments/1787.clarification
@@ -0,0 +1 @@
+Solve `allOf` recursively in OpenAPI and JSON Schemas.
diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html
index a24eddf4..157045b5 100644
--- a/layouts/partials/json-schema/resolve-additional-types.html
+++ b/layouts/partials/json-schema/resolve-additional-types.html
@@ -20,10 +20,6 @@
  * The returned entries are based on the JSON schema definitions found by
  * recursing through the input `schema`, with the following differences:
  *
- *   * `allOf` references are expanded. (Although this partial requires that
- *     `resolve-allof` is called on the top-level `schema` beforehand,
- *     `resolve-allof` doesn't recurse down to subschemas).
- *
  *   * If `anchor_base` is set, each object with a `title` and `properties`
  *     is given an `anchor`, which is a string suitable for using as an html
  *     anchor for that object schema.
@@ -210,12 +206,7 @@
       {{ errorf "Invalid call to partials/get-additional-objects: %s is not a map" $name .this_object }}
     {{ end }}
 
-    /* Although we expect resolve-allof to be called on the input, resolve-allof does not recurse into
-     * nested schemas, so we have to call it again.
-     */
-    {{ $this_object := partial "json-schema/resolve-allof" .this_object }}
-
-    {{ $res := partial "resolve-additional-types-inner" (dict "schema" $this_object "anchor_base" .anchor_base "name" $name) }}
+    {{ $res := partial "resolve-additional-types-inner" (dict "schema" .this_object "anchor_base" .anchor_base "name" $name) }}
     {{ range $res.objects }}
         {{ $all_objects = $all_objects | append (partial "clean-object" .) }}
     {{ end }}
diff --git a/layouts/partials/json-schema/resolve-allof.html b/layouts/partials/json-schema/resolve-allof.html
index db8fc13a..b8b81e7d 100644
--- a/layouts/partials/json-schema/resolve-allof.html
+++ b/layouts/partials/json-schema/resolve-allof.html
@@ -1,7 +1,7 @@
 {{/*
 
-  Resolves the `allOf` keyword (https://spec.openapis.org/oas/v3.1.0#composition-and-inheritance-polymorphism),
-  given a JSON schema object.
+  Resolves the `allOf` keyword (https://spec.openapis.org/oas/v3.1.0#composition-and-inheritance-polymorphism)
+  recursively, given a JSON schema object.
 
   `allOf` is used to support a kind of inheritance for JSON schema objects.
 
@@ -11,92 +11,71 @@
 
   Of course the parent can itself inherit from *its* parent, so we recurse to
   handle that.
-
-  Note that `allOf` is only resolved at the top level of the schema object. For
-  example, if you call this on an API definition which defines a `parameter`
-  which has an allOf schema, it will not be resolved. To handle this, the
-  openapi templates call resolve-allof for every schema object that they
-  process.
 */}}
 
 {{ $ret := . }}
 {{ $original := . }}
 
-{{/*
-  We special-case 'required', and accumulate the values from all the 'allOf'
-  entries (rather than simply overriding them). Start the accumulation here.
-*/}}
+{{ if reflect.IsSlice $original }}
+    {{/*
+      If it's a slice, just recurse.
+    */}}
+    {{ $ret = slice }}
 
-{{ $required := .required }}
-{{ if not $required }}
-    {{ $required := slice }}
-{{ end }}
-
-{{ with $ret.allOf }}
+    {{ range $original }}
+        {{ $resolved := partial "json-schema/resolve-allof" . }}
+        {{ $ret = $ret | append $resolved }}
+    {{ end }}
+{{ else if reflect.IsMap $original }}
+    {{ $ret = dict }}
 
     {{/*
-      construct a new dict, with each of the allOf entries merged into it in
-      turn.
+      We special-case 'required', and accumulate the values from all the 'allOf'
+      entries (rather than simply overriding them). Start the accumulation here.
     */}}
-    {{ $all_of_values := dict }}
-    {{ range . }}
-        {{ with .required }}
-            {{ $required = union $required . }}
-        {{ end }}
+    {{ $required := slice }}
+    {{ with $original.required }}
+      {{ $required = . }}
+    {{ end }}
 
+    {{ with $original.allOf }}
         {{/*
-          With merge, values from the second argument override those from the first argument.
-          So this order will accumulate values from allOf items, allowing later ones to override earlier
-
-          Note also that `merge` does a *deep* merge - nested maps are also
-          merged. (Slices are replaced though.)
+          Merge each of the allOf entries.
         */}}
-        {{ $all_of_values = merge $all_of_values . }}
+        {{ range . }}
+            {{/*
+              First, resolve allOf in child.  
+            */}}
+            {{ $resolved := partial "json-schema/resolve-allof" . }}
+
+            {{ with $resolved.required }}
+                {{ $required = union $required . }}
+            {{ end }}
+
+            {{/*
+              With merge, values from the second argument override those from the first argument.
+              So this order will accumulate values from allOf items, allowing later ones to override earlier
+
+              Note also that `merge` does a *deep* merge - nested maps are also
+              merged. (Slices are replaced though.)
+            */}}
+            {{ $ret = merge $ret $resolved }}
+        {{ end }}
     {{ end }}
 
     {{/*
       Finally, merge in the original, allowing the original to override allOf.
     */}}
-    {{ $ret = merge $all_of_values $ret }}
-
-    {{/*
-      Except that if allOf *itself* contains allOf (ie, the parent also
-      inherits from a grandparent), then we replace allOf in the original
-      with that in the parent. Below, we see that this has happened, and
-      recurse.
-
-      TODO: surely it would be better to simply do the recursion as we iterate
-      though the allOf list above - not least because we might have multiple
-      parents with different grandparents, and by doing this we only get one
-      set of grandparents.
-    */}}
-    {{ with $all_of_values.allOf }}
-        {{ $ret = merge $ret (dict "allOf" . ) }}
+    {{ range $key, $value := $original }}
+        {{ if and (ne $key "allOf") (ne $key "required") }}
+            {{ $resolved := partial "json-schema/resolve-allof" $value }}
+            {{ $ret = merge $ret (dict $key $resolved) }}
+        {{ end }}
     {{ end }}
 
-    {{/*
-       special-case 'required': replace it with the union of all the
-       'required' arrays from the original and allOf values.
-
-       XXX: but first we merge in the original 'required', again? why
-          do we do that? it should already have been done at the start.
-    */}}
-    {{ with $ret.required }}
-        {{ $required = union $required $ret.required }}
+    {{ with $required }}
+      {{ $ret = merge $ret (dict "required" .) }}
     {{ end }}
-
-    {{ $ret = merge $ret (dict "required" $required) }}
-{{ end }}
-
-{{/*
-  If we replaced the 'allOf' dict with one from a grandparent, we now
-  need to recurse.
-*/}}
-{{ if ne $ret.allOf $original.allOf }}
-
-    {{ $resolved := partial "json-schema/resolve-allof" $ret }}
-    {{ $ret = merge $ret $resolved }}
-
 {{ end }}
 
 {{ return $ret }}
diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html
index ef626afd..09b4254e 100644
--- a/layouts/partials/json-schema/resolve-example.html
+++ b/layouts/partials/json-schema/resolve-example.html
@@ -9,7 +9,7 @@
 
 */}}
 
-{{ $this_object := partial "json-schema/resolve-allof" . }}
+{{ $this_object := . }}
 
 {{ $example := $this_object.example }}
 
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 7c0be431..030978b1 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -38,9 +38,6 @@
  </thead>
 
     {{ range $property_name, $property := $properties }}
-
-        {{ $property := partial "json-schema/resolve-allof" $property }}
-
         {{/*
           Handle two ways of indicating "required", one for simple parameters,
           the other for request and response body objects.
@@ -67,7 +64,7 @@
   <th class="col-description">Description</th>
  </thead>
 
- {{ $property := partial "json-schema/resolve-allof" . }}
+ {{ $property := . }}
 
  <tr>
   <td><code>{{ partial "partials/property-type" $property }}</code></td>
@@ -111,9 +108,6 @@
             like `[type]`.
         */}}
         {{ $items := .items }}
-        {{ if .items }}
-            {{ $items = partial "json-schema/resolve-allof" .items }}
-        {{ end }}
         {{ $inner_type := partial "property-type" $items }}
         {{ $type = delimit (slice "[" $inner_type "]") "" }}
     {{ else if or (reflect.IsSlice .type) .oneOf }}
@@ -180,8 +174,7 @@
             If the property uses `additionalProperties` to describe its
             internal structure, handle this with a bit of recursion
         */}}
-        {{ $additionalProperties := partial "json-schema/resolve-allof" .additionalProperties }}
-        {{ $type = delimit (slice "{string: " (partial "property-type" $additionalProperties) "}" ) "" }}
+        {{ $type = delimit (slice "{string: " (partial "property-type" .additionalProperties) "}" ) "" }}
     {{ else if reflect.IsMap .patternProperties }}
         {{/*
             If the property uses `patternProperties` to describe its
@@ -193,7 +186,6 @@
         {{ $types := slice }}
 
         {{ range $pattern, $schema := .patternProperties}}
-            {{ $schema = partial "json-schema/resolve-allof" $schema }}
             {{ $types = $types | append (partial "property-type" $schema) }}
         {{ end }}
 
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index d922b64e..5fa0c255 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -40,7 +40,7 @@
             {{/*
                 Display the JSON schemas
             */}}
-            {{ $schema := partial "json-schema/resolve-allof" $json_body.schema }}
+            {{ $schema := $json_body.schema }}
 
             {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
             {{ range $additional_types }}
@@ -67,9 +67,7 @@
             {{ $example := dict }}
 
             {{ if $body.schema }}
-                {{ $schema := partial "json-schema/resolve-allof" $body.schema }}
-
-                {{ $example = partial "json-schema/resolve-example" $schema }}
+                {{ $example = partial "json-schema/resolve-example" $body.schema }}
             {{ end }}
 
             {{ if and (eq ($example | len) 0) $body.example }}
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 437e811a..07ebaebd 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -47,7 +47,7 @@
                 Display the JSON schemas
             */}}
 
-            {{ $schema := partial "json-schema/resolve-allof" $json_body.schema }}
+            {{ $schema := $json_body.schema }}
 
             {{/*
             All this is to work out how to express the content of the response
diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html
index 28e76400..489385de 100644
--- a/layouts/shortcodes/http-api.html
+++ b/layouts/shortcodes/http-api.html
@@ -24,5 +24,6 @@
 {{ $path := delimit (slice "api" $spec $api) "/" }}
 
 {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
+{{ $api_data = partial "json-schema/resolve-allof" $api_data }}
 
 {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}

From 2b5f990f60187b2af763c8298300b520d91c9d21 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 17 Apr 2024 13:51:24 +0100
Subject: [PATCH 24/82] Factor out common definition of `Tag` type (#1793)

... and remove spurious `additionalProperties: true`
---
 changelogs/internal/newsfragments/1793.misc |  1 +
 data/api/client-server/definitions/tag.yaml | 24 +++++++++++++++++++++
 data/api/client-server/tags.yaml            | 24 ++-------------------
 data/event-schemas/schema/m.tag.yaml        | 11 +---------
 4 files changed, 28 insertions(+), 32 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1793.misc
 create mode 100644 data/api/client-server/definitions/tag.yaml

diff --git a/changelogs/internal/newsfragments/1793.misc b/changelogs/internal/newsfragments/1793.misc
new file mode 100644
index 00000000..bc5abca9
--- /dev/null
+++ b/changelogs/internal/newsfragments/1793.misc
@@ -0,0 +1 @@
+Factor out common definition of `Tag` type.
diff --git a/data/api/client-server/definitions/tag.yaml b/data/api/client-server/definitions/tag.yaml
new file mode 100644
index 00000000..05c911a5
--- /dev/null
+++ b/data/api/client-server/definitions/tag.yaml
@@ -0,0 +1,24 @@
+# Copyright 2020-2024 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.
+
+title: Tag
+type: object
+properties:
+  order:
+    type: number
+    format: float
+    description: |-
+      A number in a range `[0,1]` describing a relative
+      position of the room under the given tag.
+    example: 0.25
diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml
index 5faed29c..c8e1d78c 100644
--- a/data/api/client-server/tags.yaml
+++ b/data/api/client-server/tags.yaml
@@ -53,16 +53,7 @@ paths:
                   tags:
                     type: object
                     additionalProperties:
-                      title: Tag
-                      type: object
-                      properties:
-                        order:
-                          type: number
-                          format: float
-                          description: |-
-                            A number in a range `[0,1]` describing a relative
-                            position of the room under the given tag.
-                      additionalProperties: true
+                      $ref: definitions/tag.yaml
               examples:
                 response:
                   value: {
@@ -114,18 +105,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                order:
-                  type: number
-                  format: float
-                  description: |-
-                    A number in a range `[0,1]` describing a relative
-                    position of the room under the given tag.
-              additionalProperties: true
-              example: {
-                "order": 0.25
-              }
+              $ref: definitions/tag.yaml
         description: Extra data for the tag, e.g. ordering.
         required: true
       responses:
diff --git a/data/event-schemas/schema/m.tag.yaml b/data/event-schemas/schema/m.tag.yaml
index afa22420..77010350 100644
--- a/data/event-schemas/schema/m.tag.yaml
+++ b/data/event-schemas/schema/m.tag.yaml
@@ -17,16 +17,7 @@
           "type": "object",
           "description": "The tags on the room and their contents.",
           "additionalProperties": {
-            "title": "Tag",
-            "type": "object",
-            "properties": {
-              "order": {
-                "type": "number",
-                "format": "float",
-                "description":
-                  "A number in a range `[0,1]` describing a relative position of the room under the given tag."
-              }
-            }
+            "$ref": "../../api/client-server/definitions/tag.yaml"
           }
         }
       }

From 1095179374987771732009ac9eb702fc783eb025 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 23 Apr 2024 17:30:21 +0200
Subject: [PATCH 25/82] Upgrade version of Hugo used to build the spec in CI
 (#1794)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Upgrade version of Hugo used to build the spec in CI

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Escape HTML manually in property-type partial

The behavior of `delimit` changed,
so Hugo doesn't recognize "safe" HTML passed to it anymore, so it escapes nested HTML links.

To fix that we escape the schema data manually
and consider the output of the partial as "safe".

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .github/workflows/main.yml                           |  3 ++-
 changelogs/internal/newsfragments/1794.clarification |  1 +
 layouts/partials/openapi/render-object-table.html    | 12 ++++++------
 3 files changed, 9 insertions(+), 7 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1794.clarification

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 3288b42a..de66484d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -268,7 +268,8 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
         with:
-          hugo-version: '0.113.0'
+          # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
+          hugo-version: '0.124.1'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
diff --git a/changelogs/internal/newsfragments/1794.clarification b/changelogs/internal/newsfragments/1794.clarification
new file mode 100644
index 00000000..3c38016a
--- /dev/null
+++ b/changelogs/internal/newsfragments/1794.clarification
@@ -0,0 +1 @@
+Update the version of Hugo used to render the spec to v0.124.1.
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 030978b1..6faa21d9 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -46,7 +46,7 @@
 
  <tr>
   <td><code>{{ $property_name }}</code></td>
-  <td><code>{{ partial "partials/property-type" $property }}</code></td>
+  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
   <td>{{ partial "partials/property-description" (dict "property" $property "required" $required) }}</td>
  </tr>
 
@@ -67,7 +67,7 @@
  {{ $property := . }}
 
  <tr>
-  <td><code>{{ partial "partials/property-type" $property }}</code></td>
+  <td><code>{{ partial "partials/property-type" $property | safeHTML }}</code></td>
   <td>{{ partial "partials/property-description" (dict "property" $property) }}</td>
  </tr>
 </table>
@@ -128,14 +128,14 @@
             {{ end }}
         {{ else }}
             {{ range .type }}
-                {{ $types = $types | append . }}
+                {{ $types = $types | append (htmlEscape .) }}
             {{ end }}
         {{ end }}
 
         {{ $type = delimit $types "|" }}
     {{ else }}
         {{/* A simple type like string or boolean */}}
-        {{ $type = .type }}
+        {{ $type = (htmlEscape .type) }}
     {{ end }}
 
     {{ return $type }}
@@ -165,9 +165,9 @@
             If the property has a `title`, use that rather than `type`.
             This means we can write things like `EventFilter` rather than `object`.
         */}}
-        {{ $type = .title }}
+        {{ $type = .title | htmlEscape }}
         {{ if .anchor }}
-            {{ $type = printf "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) (htmlEscape $type) | safeHTML }}
+            {{ $type = printf "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) $type }}
         {{ end }}
     {{ else if reflect.IsMap .additionalProperties }}
         {{/*

From 26ce3929b4ae238f080bfc368fe3da092a890f2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 23 Apr 2024 18:07:24 +0200
Subject: [PATCH 26/82] Clean up unecessary `allOf`s (#1797)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1797.clarification |  1 +
 .../definitions/push_ruleset.yaml             | 25 ++++---------------
 .../definitions/room_key_backup.yaml          |  3 +--
 data/api/client-server/device_management.yaml |  8 ++----
 data/api/client-server/filter.yaml            |  4 +--
 data/api/client-server/key_backup.yaml        |  6 ++---
 data/api/client-server/keys.yaml              |  9 +++----
 data/api/client-server/pushrules.yaml         |  4 +--
 data/api/server-server/knocks.yaml            | 12 +++------
 data/api/server-server/user_keys.yaml         |  6 ++---
 data/event-schemas/schema/m.call.reject.yaml  |  4 +--
 .../schema/m.key.verification.accept.yaml     |  3 +--
 .../schema/m.key.verification.cancel.yaml     |  3 +--
 .../schema/m.key.verification.done.yaml       |  3 +--
 .../schema/m.key.verification.key.yaml        |  3 +--
 .../schema/m.key.verification.mac.yaml        |  3 +--
 .../schema/m.key.verification.ready.yaml      |  3 +--
 ...y.verification.start$m.reciprocate.v1.yaml |  3 +--
 .../m.key.verification.start$m.sas.v1.yaml    |  3 +--
 .../schema/m.key.verification.start.yaml      |  3 +--
 20 files changed, 32 insertions(+), 77 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1797.clarification

diff --git a/changelogs/internal/newsfragments/1797.clarification b/changelogs/internal/newsfragments/1797.clarification
new file mode 100644
index 00000000..d98e89f0
--- /dev/null
+++ b/changelogs/internal/newsfragments/1797.clarification
@@ -0,0 +1 @@
+Clean up unnecessary `allOf`s in OpenAPI definitions.
diff --git a/data/api/client-server/definitions/push_ruleset.yaml b/data/api/client-server/definitions/push_ruleset.yaml
index 2d8cd67c..bbd07f7c 100644
--- a/data/api/client-server/definitions/push_ruleset.yaml
+++ b/data/api/client-server/definitions/push_ruleset.yaml
@@ -14,37 +14,22 @@
 properties:
   content:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   override:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   room:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   sender:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
   underride:
     items:
-      allOf:
-      - $ref: push_rule.yaml
-      title: PushRule
-      type: object
+      $ref: push_rule.yaml
     type: array
 type: object
diff --git a/data/api/client-server/definitions/room_key_backup.yaml b/data/api/client-server/definitions/room_key_backup.yaml
index 5c70850f..ef7ef983 100644
--- a/data/api/client-server/definitions/room_key_backup.yaml
+++ b/data/api/client-server/definitions/room_key_backup.yaml
@@ -20,8 +20,7 @@ properties:
     type: object
     description: "A map of session IDs to key data."
     additionalProperties:
-      allOf:
-        - $ref: "key_backup_data.yaml"
+      $ref: "key_backup_data.yaml"
     example: {
       "sessionid1": {
         "first_message_index": 1,
diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml
index c4d1ce36..b2bcb8ce 100644
--- a/data/api/client-server/device_management.yaml
+++ b/data/api/client-server/device_management.yaml
@@ -36,9 +36,7 @@ paths:
                     type: array
                     description: A list of all registered devices for this user.
                     items:
-                      type: object
-                      allOf:
-                        - $ref: definitions/client_device.yaml
+                      $ref: definitions/client_device.yaml
               examples:
                 response:
                   value: {
@@ -75,9 +73,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                allOf:
-                  - $ref: definitions/client_device.yaml
+                $ref: definitions/client_device.yaml
               examples:
                 response:
                   value: {
diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml
index 805f79f8..f1135939 100644
--- a/data/api/client-server/filter.yaml
+++ b/data/api/client-server/filter.yaml
@@ -143,9 +143,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                allOf:
-                  - $ref: definitions/sync_filter.yaml
+                $ref: definitions/sync_filter.yaml
               examples:
                 response:
                   value: {
diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml
index 464d4b4c..103071dd 100644
--- a/data/api/client-server/key_backup.yaml
+++ b/data/api/client-server/key_backup.yaml
@@ -841,8 +841,7 @@ paths:
                   type: object
                   description: A map of room IDs to room key backup data.
                   additionalProperties:
-                    allOf:
-                      - $ref: definitions/room_key_backup.yaml
+                    $ref: definitions/room_key_backup.yaml
                   example:
                     "!room:example.org":
                       sessions:
@@ -946,8 +945,7 @@ paths:
                     type: object
                     description: A map of room IDs to room key backup data.
                     additionalProperties:
-                      allOf:
-                        - $ref: definitions/room_key_backup.yaml
+                      $ref: definitions/room_key_backup.yaml
                     example:
                       "!room:example.org":
                         sessions:
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index f5172ec9..2fd40172 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -226,8 +226,7 @@ paths:
                       uploaded via `/keys/signatures/upload` that the requesting user
                       is allowed to see.
                     additionalProperties:
-                      allOf:
-                        - $ref: definitions/cross_signing_key.yaml
+                      $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -244,8 +243,7 @@ paths:
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
                     additionalProperties:
-                      allOf:
-                        - $ref: definitions/cross_signing_key.yaml
+                      $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -265,8 +263,7 @@ paths:
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
                     additionalProperties:
-                      allOf:
-                        - $ref: definitions/cross_signing_key.yaml
+                      $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml
index d009d351..d85e3d85 100644
--- a/data/api/client-server/pushrules.yaml
+++ b/data/api/client-server/pushrules.yaml
@@ -470,9 +470,7 @@ paths:
                     rule to be applied to an event. A rule with no conditions
                     always matches. Only applicable to `underride` and `override` rules.
                   items:
-                    type: object
-                    allOf:
-                      - $ref: definitions/push_condition.yaml
+                    $ref: definitions/push_condition.yaml
                 pattern:
                   type: string
                   description: Only applicable to `content` rules. The glob-style pattern to match
diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml
index f5b44003..cba9d32b 100644
--- a/data/api/server-server/knocks.yaml
+++ b/data/api/server-server/knocks.yaml
@@ -171,8 +171,7 @@ paths:
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -186,8 +185,7 @@ paths:
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -318,8 +316,7 @@ paths:
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
                 response:
                   value: {
@@ -333,8 +330,7 @@ paths:
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: ../client-server/definitions/errors/error.yaml
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
                 response:
                   value: {
diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml
index 6007b304..780303e3 100644
--- a/data/api/server-server/user_keys.yaml
+++ b/data/api/server-server/user_keys.yaml
@@ -178,8 +178,7 @@ paths:
                       uploaded via `/keys/signatures/upload` that the user is
                       allowed to see.
                     additionalProperties:
-                      allOf:
-                        - $ref: ../client-server/definitions/cross_signing_key.yaml
+                      $ref: ../client-server/definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -196,8 +195,7 @@ paths:
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
                     additionalProperties:
-                      allOf:
-                        - $ref: ../client-server/definitions/cross_signing_key.yaml
+                      $ref: ../client-server/definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml
index 39726c1a..d12a0b5c 100644
--- a/data/event-schemas/schema/m.call.reject.yaml
+++ b/data/event-schemas/schema/m.call.reject.yaml
@@ -18,9 +18,7 @@ allOf:
 - "$ref": core-event-schema/room_event.yaml
 properties:
   content:
-    type: object
-    allOf:
-    - "$ref": core-event-schema/call_event.yaml
+    "$ref": core-event-schema/call_event.yaml
   type:
     type: string
     enum:
diff --git a/data/event-schemas/schema/m.key.verification.accept.yaml b/data/event-schemas/schema/m.key.verification.accept.yaml
index 2a1bbf0d..a61edd66 100644
--- a/data/event-schemas/schema/m.key.verification.accept.yaml
+++ b/data/event-schemas/schema/m.key.verification.accept.yaml
@@ -44,8 +44,7 @@ properties:
           ephemeral public key (encoded as unpadded base64) and the canonical JSON
           representation of the `m.key.verification.start` message.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - method
       - key_agreement_protocol
diff --git a/data/event-schemas/schema/m.key.verification.cancel.yaml b/data/event-schemas/schema/m.key.verification.cancel.yaml
index 6474b763..237f0d06 100644
--- a/data/event-schemas/schema/m.key.verification.cancel.yaml
+++ b/data/event-schemas/schema/m.key.verification.cancel.yaml
@@ -58,8 +58,7 @@ properties:
           respond again with `m.unexpected_message` to avoid the other device potentially
           sending another error response.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - code
       - reason
diff --git a/data/event-schemas/schema/m.key.verification.done.yaml b/data/event-schemas/schema/m.key.verification.done.yaml
index bfdc540b..0e1c24e6 100644
--- a/data/event-schemas/schema/m.key.verification.done.yaml
+++ b/data/event-schemas/schema/m.key.verification.done.yaml
@@ -13,8 +13,7 @@ properties:
           Required when sent as a to-device message. The opaque identifier for
           the verification process/request.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     type: object
   type:
     enum:
diff --git a/data/event-schemas/schema/m.key.verification.key.yaml b/data/event-schemas/schema/m.key.verification.key.yaml
index 62704ea7..c0b31c1b 100644
--- a/data/event-schemas/schema/m.key.verification.key.yaml
+++ b/data/event-schemas/schema/m.key.verification.key.yaml
@@ -18,8 +18,7 @@ properties:
         description: |-
           The device's ephemeral public key, encoded as unpadded base64.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - key
     type: object
diff --git a/data/event-schemas/schema/m.key.verification.mac.yaml b/data/event-schemas/schema/m.key.verification.mac.yaml
index 7f404fa0..ad4a3f05 100644
--- a/data/event-schemas/schema/m.key.verification.mac.yaml
+++ b/data/event-schemas/schema/m.key.verification.mac.yaml
@@ -29,8 +29,7 @@ properties:
           The MAC of the comma-separated, sorted, list of key IDs given in the `mac`
           property, encoded as unpadded base64.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - mac
       - keys
diff --git a/data/event-schemas/schema/m.key.verification.ready.yaml b/data/event-schemas/schema/m.key.verification.ready.yaml
index bf9d975b..1c5ed7bd 100644
--- a/data/event-schemas/schema/m.key.verification.ready.yaml
+++ b/data/event-schemas/schema/m.key.verification.ready.yaml
@@ -27,8 +27,7 @@ properties:
         items:
           type: string
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - from_device
       - methods
diff --git a/data/event-schemas/schema/m.key.verification.start$m.reciprocate.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.reciprocate.v1.yaml
index a60711b3..4f3071ac 100644
--- a/data/event-schemas/schema/m.key.verification.start$m.reciprocate.v1.yaml
+++ b/data/event-schemas/schema/m.key.verification.start$m.reciprocate.v1.yaml
@@ -30,8 +30,7 @@ properties:
         description: |-
           The shared secret from the QR code, encoded using unpadded base64.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - from_device
       - method
diff --git a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml
index 9bc7bcad..c5f2e8af 100644
--- a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml
+++ b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml
@@ -58,8 +58,7 @@ properties:
           type: string
           enum: ["decimal", "emoji"]
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - from_device
       - method
diff --git a/data/event-schemas/schema/m.key.verification.start.yaml b/data/event-schemas/schema/m.key.verification.start.yaml
index a36a72f8..cc16d275 100644
--- a/data/event-schemas/schema/m.key.verification.start.yaml
+++ b/data/event-schemas/schema/m.key.verification.start.yaml
@@ -32,8 +32,7 @@ properties:
           when the `method` chosen only verifies one user's key. This field will
           never be present if the `method` verifies keys both ways.
       m.relates_to:
-        allOf:
-          - $ref: m.key.verification.m.relates_to.yaml
+        $ref: m.key.verification.m.relates_to.yaml
     required:
       - from_device
       - method

From 2edfb21d5d85d6ca01c4a0b9523f2a799a6d5a92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 24 Apr 2024 13:42:34 +0200
Subject: [PATCH 27/82] Add support for pattern formats for `patternProperties`
 (#1796)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1796.clarification |  1 +
 data/custom-formats.yaml                      | 33 ++++++++++++++++
 .../schema/m.ignored_user_list.yaml           |  2 +-
 data/event-schemas/schema/m.receipt.yaml      |  4 +-
 .../partials/openapi/render-object-table.html | 38 ++++++++++++++++---
 openapi_extensions.md                         | 10 +++++
 6 files changed, 80 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1796.clarification
 create mode 100644 data/custom-formats.yaml

diff --git a/changelogs/internal/newsfragments/1796.clarification b/changelogs/internal/newsfragments/1796.clarification
new file mode 100644
index 00000000..6a489a01
--- /dev/null
+++ b/changelogs/internal/newsfragments/1796.clarification
@@ -0,0 +1 @@
+Add support for pattern formats for `patternProperties`.
diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml
new file mode 100644
index 00000000..f0001c80
--- /dev/null
+++ b/data/custom-formats.yaml
@@ -0,0 +1,33 @@
+# Copyright 2024 Commaille Kévin
+#
+# 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.
+
+# This file contains the list of custom formats supported for the `format` key
+# and the `x-pattern-format` extension (see `openapi_extensions.md` for more
+# details).
+#
+# Each entry must use the `mx-` prefix and have the form:
+#
+# mx-custom-key:
+#   title: The title rendered in the specification
+#   url: /url/to#definition
+
+mx-user-id:
+  title: User ID
+  url: /appendices#user-identifiers
+  # regex: "^@"
+
+mx-event-id:
+  title: Event ID
+  url: /appendices#event-ids
+  # regex: "^\\$"
diff --git a/data/event-schemas/schema/m.ignored_user_list.yaml b/data/event-schemas/schema/m.ignored_user_list.yaml
index 32cc6a46..af838490 100644
--- a/data/event-schemas/schema/m.ignored_user_list.yaml
+++ b/data/event-schemas/schema/m.ignored_user_list.yaml
@@ -17,7 +17,7 @@ properties:
           "^@":
             type: "object"
             description: "An empty object for future enhancement"
-            x-pattern: "$USER_ID"
+            x-pattern-format: "mx-user-id"
     required:
       - ignored_users
   type:
diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml
index 702191d1..23a5d835 100644
--- a/data/event-schemas/schema/m.receipt.yaml
+++ b/data/event-schemas/schema/m.receipt.yaml
@@ -16,7 +16,7 @@ properties:
         patternProperties:
             "^\\$":
                 type: object
-                x-pattern: "$EVENT_ID"
+                x-pattern-format: "mx-event-id"
                 title: Event Receipts
                 description: |-
                     The collection of receipts for this event ID.
@@ -34,7 +34,7 @@ properties:
                                 description: |-
                                     The mapping of user ID to receipt. The user ID is the
                                     entity who sent this receipt.
-                                x-pattern: "$USER_ID"
+                                x-pattern-format: "mx-user-id"
                                 properties:
                                     ts:
                                         type: integer
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 6faa21d9..227e9e04 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -179,17 +179,45 @@
         {{/*
             If the property uses `patternProperties` to describe its
             internal structure, handle this with a bit of recursion.
-            Note that we ignore the pattern as the current definitions
+            Types are grouped by pattern format. Note that we ignore
+            patterns without a format as the current definitions
             always have a single pattern, but we might need to handle
             them later to differentiate schemas according to patterns.
         */}}
-        {{ $types := slice }}
 
-        {{ range $pattern, $schema := .patternProperties}}
-            {{ $types = $types | append (partial "property-type" $schema) }}
+        {{/*
+            Construct a map from format ID to the type string of the format.
+        */}}
+        {{ $formatMap := newScratch }}
+
+        {{ range $pattern, $schema := .patternProperties }}
+            {{ $formatId := or (index $schema "x-pattern-format") "string" }}
+
+            {{ if $formatMap.Get $formatId }}
+                {{ errorf "'%s' pattern format is defined more than once for the same property" $formatId }}
+            {{ end }}
+
+            {{ $formatMap.Set $formatId (partial "property-type" $schema) }}
         {{ end }}
 
-        {{ $type = delimit (slice "{string: " (delimit $types "|") "}" ) "" }}
+        {{/* First generate the type string for each format. */}}
+        {{ $types := slice }}
+        {{ range $formatId, $formatType := $formatMap.Values }}
+            {{ $formatKey := "string" }}
+            {{ if ne $formatId "string" }}
+                {{ with index site.Data "custom-formats" $formatId }}
+                    {{ $formatKey = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+                {{ else }}
+                    {{ errorf "Unsupported value for `x-pattern-format`: %s" $formatId }}
+                {{ end }}
+            {{ end }}
+
+            {{ $formatString := printf "{%s: %s}" $formatKey $formatType }}
+            {{ $types = $types | append $formatString }}
+        {{ end }}
+
+        {{/* Then join all the formats. */}}
+        {{ $type = delimit $types "|" }}
     {{ end }}
 
     {{ return $type }}
diff --git a/openapi_extensions.md b/openapi_extensions.md
index 8a7146a9..e8fd1002 100644
--- a/openapi_extensions.md
+++ b/openapi_extensions.md
@@ -31,3 +31,13 @@ particular Matrix specification versions.
 
 Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
 whole example, we use it to compose examples from other examples.
+
+## Custom `x-pattern-format` key and custom formats 
+
+In JSON Schema, [`format`](https://json-schema.org/understanding-json-schema/reference/string#format)
+is a property to convey semantic information about a schema. We define
+`x-pattern-format` as a key on the schemas under `patternProperties` with the
+same use as `format`, but that applies to the pattern of the property. We also
+define custom values for formats with the `mx-` prefix in
+`data/custom-formats.yaml`. Those values are recognized in the rendered
+specification and link to the definition of the format.

From 7201042894dfcaf8da468d3bcb6e9a60805baaa0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 24 Apr 2024 13:53:49 +0200
Subject: [PATCH 28/82] Fix anchors for schemas under `oneOf` (#1799)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 changelogs/internal/newsfragments/1799.clarification       | 1 +
 layouts/partials/json-schema/resolve-additional-types.html | 5 +++++
 2 files changed, 6 insertions(+)
 create mode 100644 changelogs/internal/newsfragments/1799.clarification

diff --git a/changelogs/internal/newsfragments/1799.clarification b/changelogs/internal/newsfragments/1799.clarification
new file mode 100644
index 00000000..d47e0183
--- /dev/null
+++ b/changelogs/internal/newsfragments/1799.clarification
@@ -0,0 +1 @@
+Fix anchors for schemas under `oneOf`.
diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html
index 157045b5..cf5e9953 100644
--- a/layouts/partials/json-schema/resolve-additional-types.html
+++ b/layouts/partials/json-schema/resolve-additional-types.html
@@ -165,6 +165,7 @@
      * (https://json-schema.org/understanding-json-schema/reference/combining.html#oneof)
      */
     {{ if $this_object.oneOf }}
+        {{ $updated_items := slice }}
         {{ range $idx, $item := $this_object.oneOf }}
             {{ $res := partial "get-additional-objects" (dict
                 "this_object" $item
@@ -173,7 +174,11 @@
                 "name" (printf "%s.oneOf[%d]" $name $idx)
             ) }}
             {{ $all_objects = $res.objects }}
+            {{ $updated_items = $updated_items | append $res.schema }}
         {{ end }}
+
+        /* Update the top-level schema with the updated subschemas for the items */
+        {{ $this_object = merge $this_object (dict "oneOf" $updated_items) }}
     {{ end }}
 
     {{ return (dict

From a0bc6e7f8391fc0b10fdc6fab0d899716186043e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 17:52:23 +0200
Subject: [PATCH 29/82] Add anchors in `definition` shortcode (#1802)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 changelogs/internal/newsfragments/1802.clarification |  1 +
 layouts/shortcodes/definition.html                   | 10 ++++++++--
 2 files changed, 9 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1802.clarification

diff --git a/changelogs/internal/newsfragments/1802.clarification b/changelogs/internal/newsfragments/1802.clarification
new file mode 100644
index 00000000..09aebc5d
--- /dev/null
+++ b/changelogs/internal/newsfragments/1802.clarification
@@ -0,0 +1 @@
+Add anchors in `definition` shortcode.
diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html
index 23461878..a1f0904e 100644
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@@ -26,7 +26,9 @@
 {{ $definition = partial "json-schema/resolve-refs" (dict "schema" $definition "path" $path) }}
 {{ $definition = partial "json-schema/resolve-allof" $definition }}
 
-<section class="rendered-data definition" id="definition-{{ anchorize $definition.title }}">
+{{ $anchor_base := printf "definition-%s" (anchorize $definition.title) }}
+
+<section class="rendered-data definition" id="{{ $anchor_base }}">
 
 <details {{ if not $compact }}open{{ end }}>
 <summary>
@@ -46,7 +48,11 @@
 {{ $definition.description | markdownify }}
 
 
-{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition "name" (printf "\"%s\"" $path)) }}
+{{ $additional_types := partial "json-schema/resolve-additional-types" (dict
+    "schema" $definition
+    "anchor_base" $anchor_base
+    "name" (printf "\"%s\"" $path))
+}}
 
 {{ range $additional_types }}
     {{ partial "openapi/render-object-table" . }}

From b0115a96132543d4e62faadd1a3513927a88463c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 17:56:03 +0200
Subject: [PATCH 30/82] Update typos CI action (#1804)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .github/_typos.toml                                  | 1 +
 .github/workflows/spell-check.yaml                   | 4 ++--
 changelogs/internal/newsfragments/1804.clarification | 1 +
 3 files changed, 4 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1804.clarification

diff --git a/.github/_typos.toml b/.github/_typos.toml
index e48ab53c..3cdecaa3 100644
--- a/.github/_typos.toml
+++ b/.github/_typos.toml
@@ -10,3 +10,4 @@ au1ba7o = "au1ba7o"
 [default.extend-words]
 Appy = "Appy"
 fo = "fo"
+Iy = "Iy"
diff --git a/.github/workflows/spell-check.yaml b/.github/workflows/spell-check.yaml
index b4a9060e..541f7f93 100644
--- a/.github/workflows/spell-check.yaml
+++ b/.github/workflows/spell-check.yaml
@@ -14,6 +14,6 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Check spelling of proposals
-      uses: crate-ci/typos@ff3f309513469397e1094520fb7a054e057589e1
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
       with:
-        config: ${{github.workspace}}/.github/_typos.toml
\ No newline at end of file
+        config: ${{github.workspace}}/.github/_typos.toml
diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification
new file mode 100644
index 00000000..39249cb8
--- /dev/null
+++ b/changelogs/internal/newsfragments/1804.clarification
@@ -0,0 +1 @@
+Update typos CI action.

From d6b1d7300f54f2c87dc6134fd57da47f8e29b2ac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 17:57:20 +0200
Subject: [PATCH 31/82] Update most CI actions (#1803)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .github/workflows/main.yml                    | 46 +++++++++----------
 .github/workflows/netlify.yaml                |  5 +-
 .github/workflows/release.yaml                |  4 +-
 .../internal/newsfragments/1803.clarification |  1 +
 4 files changed, 28 insertions(+), 28 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1803.clarification

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index de66484d..7d58b383 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -20,9 +20,9 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "🔎 Run validator"
         run: |
           npx @redocly/cli@latest lint data/api/*/*.yaml
@@ -34,7 +34,7 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -51,9 +51,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -70,9 +70,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: "📥 Source checkout"
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -114,7 +114,7 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
           cache: 'pip'
@@ -152,7 +152,7 @@ jobs:
               -o spec/server-server-api/api.json
           tar -czf openapi.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: openapi-artifact
           path: openapi.tar.gz
@@ -166,13 +166,13 @@ jobs:
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
         run: ./scripts/generate-changelog.sh vUNSTABLE
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog/vUNSTABLE.md
@@ -185,11 +185,11 @@ jobs:
     if: ${{ always() }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
           hugo-version: '0.113.0'
           extended: true
@@ -201,7 +201,7 @@ jobs:
           npm run get-proposals
       - name: "📥 Download generated changelog"
         if: "needs.generate-changelog.result == 'success'"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: changelog-artifact
           path: content/changelog
@@ -212,7 +212,7 @@ jobs:
       # https://spec.matrix.org/latest/client-server-api/api.json
       # Works for /unstable/ and /v1.1/ as well.
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -222,7 +222,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-artifact
           path: spec.tar.gz
@@ -236,7 +236,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: spec-artifact
 
@@ -262,11 +262,11 @@ jobs:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     steps:
       - name: "➕ Setup Node"
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
           # Cannot build the spec with Hugo 0.125.0 because of https://github.com/google/docsy/issues/1930
           hugo-version: '0.124.1'
@@ -284,7 +284,7 @@ jobs:
           hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
 
       - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: openapi-artifact
       - name: "📝 Unpack the OpenAPI definitions in the right location"
@@ -294,7 +294,7 @@ jobs:
       - name: "📦 Tarball creation"
         run: tar -czf spec-historical.tar.gz spec
       - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: spec-historical-artifact
           path: spec-historical.tar.gz
diff --git a/.github/workflows/netlify.yaml b/.github/workflows/netlify.yaml
index fb2d05c9..09360720 100644
--- a/.github/workflows/netlify.yaml
+++ b/.github/workflows/netlify.yaml
@@ -35,7 +35,7 @@ jobs:
           echo "::set-output name=prnumber::$pr_number"
         
       - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e # v2.28.0
+        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
         with:
           workflow: main.yaml
           run_id: ${{ github.event.workflow_run.id }}
@@ -46,8 +46,7 @@ jobs:
         
       - name: "📤 Deploy to Netlify"
         id: netlify
-        # v2.1.0
-        uses: nwtgck/actions-netlify@7a92f00dde8c92a5a9e8385ec2919775f7647352
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: spec
           deploy-message: "Deploy from GitHub Actions"
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 6f8d1353..a53fe59a 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: 🔧 Yarn cache
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           cache: "yarn"
           cache-dependency-path: packages/npm/yarn.lock
@@ -34,7 +34,7 @@ jobs:
 
       - name: 🚀 Publish to npm
         id: npm-publish
-        uses: JS-DevTools/npm-publish@5a85faf05d2ade2d5b6682bfe5359915d5159c6c # v2.2.1
+        uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
         with:
           token: ${{ secrets.NPM_TOKEN }}
           package: packages/npm
diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification
new file mode 100644
index 00000000..dbfaa8c9
--- /dev/null
+++ b/changelogs/internal/newsfragments/1803.clarification
@@ -0,0 +1 @@
+Update most CI actions.

From d3eca873890fd3d06085e498d15840ae0e7e51f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 18:01:18 +0200
Subject: [PATCH 32/82] Set python version for the Towncrier CI job (#1805)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Otherwise the version might change depending on the runner.
We just use the same version as other jobs.

This removes a GitHub warning.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 .github/workflows/main.yml                           | 2 ++
 changelogs/internal/newsfragments/1805.clarification | 1 +
 2 files changed, 3 insertions(+)
 create mode 100644 changelogs/internal/newsfragments/1805.clarification

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 7d58b383..94cc1a5b 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -167,6 +167,8 @@ jobs:
         uses: actions/checkout@v4
       - name: "➕ Setup Python"
         uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
       - name: "➕ Install towncrier"
         run: "pip install 'towncrier'"
       - name: "Generate changelog"
diff --git a/changelogs/internal/newsfragments/1805.clarification b/changelogs/internal/newsfragments/1805.clarification
new file mode 100644
index 00000000..c1b09b62
--- /dev/null
+++ b/changelogs/internal/newsfragments/1805.clarification
@@ -0,0 +1 @@
+Set python version for the Towncrier CI job.

From ae70b5fcf3b45539a5ced367b3d5304c6f005104 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 18:02:59 +0200
Subject: [PATCH 33/82] Replace `set-output` with environment files in CI
 (#1806)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .github/workflows/main.yml                           | 6 +++---
 .github/workflows/netlify.yaml                       | 2 +-
 changelogs/internal/newsfragments/1806.clarification | 1 +
 3 files changed, 5 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1806.clarification

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 94cc1a5b..09a184a7 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -99,11 +99,11 @@ jobs:
         # the asterisk matching behaviour, not the literal string.
         run: |
           if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
+              echo "baseURL=/" >> "$GITHUB_OUTPUT"
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
           else
-              echo ::set-output name=baseURL::/unstable
+              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
           fi
 
   build-openapi:
diff --git a/.github/workflows/netlify.yaml b/.github/workflows/netlify.yaml
index 09360720..889d6eed 100644
--- a/.github/workflows/netlify.yaml
+++ b/.github/workflows/netlify.yaml
@@ -32,7 +32,7 @@ jobs:
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
                jq -r '.[] | .number')
           echo "PR number: $pr_number"
-          echo "::set-output name=prnumber::$pr_number"
+          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
         
       - name: '📥 Download artifact'
         uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
diff --git a/changelogs/internal/newsfragments/1806.clarification b/changelogs/internal/newsfragments/1806.clarification
new file mode 100644
index 00000000..88b875bb
--- /dev/null
+++ b/changelogs/internal/newsfragments/1806.clarification
@@ -0,0 +1 @@
+Replace `set-output` with environment files in CI.

From 625999a039075b165ccc72e49f98eb97ba87ffd3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 18:07:59 +0200
Subject: [PATCH 34/82] Deprecate authentication via a query string (#1808)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../newsfragments/1808.clarification          |  1 +
 .../newsfragments/1808.clarification          |  1 +
 content/client-server-api/_index.md           | 22 ++++++++++---------
 content/identity-service-api.md               | 19 ++++++++++------
 .../client-server/definitions/security.yaml   |  5 +++--
 data/api/identity/definitions/security.yaml   |  3 ++-
 6 files changed, 31 insertions(+), 20 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1808.clarification
 create mode 100644 changelogs/identity_service/newsfragments/1808.clarification

diff --git a/changelogs/client_server/newsfragments/1808.clarification b/changelogs/client_server/newsfragments/1808.clarification
new file mode 100644
index 00000000..ff2c1651
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1808.clarification
@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
diff --git a/changelogs/identity_service/newsfragments/1808.clarification b/changelogs/identity_service/newsfragments/1808.clarification
new file mode 100644
index 00000000..ff2c1651
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1808.clarification
@@ -0,0 +1 @@
+Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 8c017e62..ba527275 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -390,8 +390,7 @@ specify parameter values. The flow for this method is as follows:
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting
-previously obtained credentials in the form of an `access_token` query
-parameter or through an Authorization Header of `Bearer $access_token`.
+previously obtained credentials in the form of an access token.
 An access token is typically obtained via the [Login](#login) or
 [Registration](#account-registration-and-management) processes. Access tokens
 can expire; a new access token can be generated by using a refresh token.
@@ -405,16 +404,19 @@ investigate [macaroons](http://research.google.com/pubs/pub41892.html).
 
 ### Using access tokens
 
-Access tokens may be provided in two ways, both of which the homeserver
-MUST support:
+Access tokens may be provided via a request header, using the Authentication
+Bearer scheme: `Authorization: Bearer TheTokenHere`.
 
-1.  Via a query string parameter, `access_token=TheTokenHere`.
-2.  Via a request header, `Authorization: Bearer TheTokenHere`.
+Clients may alternatively provide the access token via a query string parameter:
+`access_token=TheTokenHere`. This method is deprecated to prevent the access
+token being leaked in access/HTTP logs and SHOULD NOT be used by clients.
 
-Clients are encouraged to use the `Authorization` header where possible
-to prevent the access token being leaked in access/HTTP logs. The query
-string should only be used in cases where the `Authorization` header is
-inaccessible for the client.
+Homeservers MUST support both methods.
+
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Sending the access token as a query string parameter is now deprecated.
+{{% /boxes/note %}}
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code, `M_MISSING_TOKEN` or
diff --git a/content/identity-service-api.md b/content/identity-service-api.md
index 9e2d5cdf..3c20a12a 100644
--- a/content/identity-service-api.md
+++ b/content/identity-service-api.md
@@ -162,15 +162,20 @@ of access tokens to authenticate users. The access tokens provided by an
 Identity Server cannot be used to authenticate Client-Server API
 requests.
 
-An access token is provided to an endpoint in one of two ways:
+Access tokens may be provided via a request header, using the
+Authentication Bearer scheme: `Authorization: Bearer TheTokenHere`.
 
-1.  Via a query string parameter, `access_token=TheTokenHere`.
-2.  Via a request header, `Authorization: Bearer TheTokenHere`.
+Clients may alternatively provide the access token via a query string
+parameter: `access_token=TheTokenHere`. This method is deprecated to
+prevent the access token being leaked in access/HTTP logs and SHOULD NOT
+be used by clients.
 
-Clients are encouraged to the use the `Authorization` header where
-possible to prevent the access token being leaked in access/HTTP logs.
-The query string should only be used in cases where the `Authorization`
-header is inaccessible for the client.
+Identity Servers MUST support both methods.
+
+{{% boxes/note %}}
+{{% changed-in v="1.11" %}}
+Sending the access token as a query string parameter is now deprecated.
+{{% /boxes/note %}}
 
 When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code `M_UNAUTHORIZED`.
diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml
index 16ceb8ac..0c9bd1c7 100644
--- a/data/api/client-server/definitions/security.yaml
+++ b/data/api/client-server/definitions/security.yaml
@@ -14,7 +14,7 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    The `access_token` returned by a call to `/login` or `/register`, as a query
+    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
     parameter.
 
     It can also be the `as_token` of an application service.
@@ -33,7 +33,8 @@ accessTokenBearer:
 appserviceAccessTokenQuery:
   type: apiKey
   description: |-
-    The `as_token` of an application service, as a query parameter.
+    **Deprecated.** The `as_token` of an application service, as a query
+    parameter.
   name: access_token
   in: query
 appserviceAccessTokenBearer:
diff --git a/data/api/identity/definitions/security.yaml b/data/api/identity/definitions/security.yaml
index f3c668c5..598005b7 100644
--- a/data/api/identity/definitions/security.yaml
+++ b/data/api/identity/definitions/security.yaml
@@ -14,7 +14,8 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    The `access_token` returned by a call to `/register`, as a query parameter.
+    **Deprecated.** The `access_token` returned by a call to `/register`, as a
+    query parameter.
   name: access_token
   in: query
 accessTokenBearer:

From 85ad0c767ccca1c49761e048c5a16baab2bd01e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 18:42:55 +0200
Subject: [PATCH 35/82] Render response headers (#1809)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1809.clarification  |  1 +
 layouts/partials/openapi/render-responses.html | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+)
 create mode 100644 changelogs/internal/newsfragments/1809.clarification

diff --git a/changelogs/internal/newsfragments/1809.clarification b/changelogs/internal/newsfragments/1809.clarification
new file mode 100644
index 00000000..e1124a53
--- /dev/null
+++ b/changelogs/internal/newsfragments/1809.clarification
@@ -0,0 +1 @@
+Render response headers.
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 07ebaebd..0ffc4884 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -38,6 +38,24 @@
 {{ range $code, $response := $responses }}
     {{ if $response.content }}
 <h3>{{$code}} response</h3>
+        {{/* Display defined headers */}}
+        {{ if $response.headers }}
+            {{/* build a dict mapping from name->schema, which render-object-table expects */}}
+            {{ $headers_dict := dict }}
+            {{ range $header_name,$header_props := $response.headers }}
+                {{/*
+                    merge the schema at the same level as the rest of the other fields because that is
+                    what `render-object-table` expects. Put the schema first so examples in it are
+                    overwritten.
+                */}}
+                {{ $header_schema := merge $header_props.schema $header_props }}
+                {{ $headers_dict = merge $headers_dict (dict $header_name $header_schema )}}
+            {{ end }}
+
+            {{/* and render the headers */}}
+            {{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
+        {{ end }}
+
         {{/*
             A response can have several content types.
         */}}

From 1fc25d8d48514b1fc2df0c3e4b015a3746802c22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 19:05:03 +0200
Subject: [PATCH 36/82] Do not use `title` for objects containing only
 `additionalProperties` or `patternProperties` (#1801)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, titles would appear that do not link to a subchema definition.
It would also mean that named subschemas would appear without being clearly referenced.

Now, the type clearly shows the nesting of objects
and subschema definitions should be clearly referenced.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1801.clarification |  1 +
 .../partials/openapi/render-object-table.html | 29 ++++++++++++++-----
 2 files changed, 22 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1801.clarification

diff --git a/changelogs/internal/newsfragments/1801.clarification b/changelogs/internal/newsfragments/1801.clarification
new file mode 100644
index 00000000..6d01cfb7
--- /dev/null
+++ b/changelogs/internal/newsfragments/1801.clarification
@@ -0,0 +1 @@
+Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`.
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 227e9e04..21d77c89 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -84,6 +84,9 @@
     * `oneOf`: optional array of dictionaries describing the different formats
       that the property can have
 
+    * `properties`: if the type is an object, optional dictionary for
+      well-defined properties, each given as: `property_name` : `property_data`
+
     * `additionalProperties`: if the type is an object, optional dictionary for
       properties with undefined names
 
@@ -148,6 +151,9 @@
 
     * `title`: optional string for the title of the object property
 
+    * `properties`: optional dictionary for well-defined properties, each given
+      as: `property_name` : `property_data`
+
     * `additionalProperties`: optional dictionary for properties with undefined
       names
 
@@ -155,19 +161,19 @@
       adhering to a regex pattern
 
     * `anchor`: optional HTML element id for the target type, which will be used to link to it.
-
-    The title has a higher priority than anything else.
 */}}
 {{ define "partials/object-type-or-title" }}
     {{ $type := "object" }}
-    {{ if .title }}
+    {{ if .properties }}
         {{/*
-            If the property has a `title`, use that rather than `type`.
-            This means we can write things like `EventFilter` rather than `object`.
+            The object has its own (regular) properties, so we will make a
+            separate table for it. Refer to it using its title, if it has one.
         */}}
-        {{ $type = .title | htmlEscape }}
-        {{ if .anchor }}
-            {{ $type = printf "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) $type }}
+        {{ if .title }}
+          {{ $type = .title | htmlEscape }}
+          {{ if .anchor }}
+              {{ $type = printf "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) $type }}
+          {{ end }}
         {{ end }}
     {{ else if reflect.IsMap .additionalProperties }}
         {{/*
@@ -218,6 +224,13 @@
 
         {{/* Then join all the formats. */}}
         {{ $type = delimit $types "|" }}
+    {{ else if .title }}
+        {{/*
+            No properties, so there won't be a separate table. We use the title
+            anyway, because showing the title (like `EventFilter`) is better
+            than showing `object`.
+        */}}
+        {{ $type = .title | htmlEscape }}
     {{ end }}
 
     {{ return $type }}

From 2d18aac2016eea45a3de1847dd795a679a1b59c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 19:13:05 +0200
Subject: [PATCH 37/82] Use `OneTimeKeys` schema (#1800)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This was commented prior to the
port to OpenAPI 3.1 for technical reasons (#1127).
Now we can use it just fine.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1800.clarification |  1 +
 .../definitions/one_time_keys.yaml            |  3 ++-
 data/api/client-server/keys.yaml              | 20 +++++--------------
 3 files changed, 8 insertions(+), 16 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1800.clarification

diff --git a/changelogs/internal/newsfragments/1800.clarification b/changelogs/internal/newsfragments/1800.clarification
new file mode 100644
index 00000000..7dfac999
--- /dev/null
+++ b/changelogs/internal/newsfragments/1800.clarification
@@ -0,0 +1 @@
+Use reference to `OneTimeKeys` schema in OpenAPI definitions.
diff --git a/data/api/client-server/definitions/one_time_keys.yaml b/data/api/client-server/definitions/one_time_keys.yaml
index ceb69291..d54494d9 100644
--- a/data/api/client-server/definitions/one_time_keys.yaml
+++ b/data/api/client-server/definitions/one_time_keys.yaml
@@ -9,6 +9,7 @@ additionalProperties:
   oneOf:
     - type: string
     - type: object
+      title: KeyObject
       properties:
         key:
           type: string
@@ -18,7 +19,7 @@ additionalProperties:
           description: |-
             Signature for the device. Mapped from user ID to signature object,
             containing mapping from _key signing identifier_ to the signature
-            (see also: https://spec.matrix.org/v1.2/appendices/#signing-json)
+            (see also: [Signing JSON](/appendices/#signing-json))
           additionalProperties:
             type: object
       required: ['key', 'signatures']
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index 2fd40172..f165f379 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -39,12 +39,9 @@ paths:
                   allOf:
                     - $ref: definitions/device_keys.yaml
                 one_time_keys:
-                  # $ref: "definitions/one_time_keys.yaml"
-                  # XXX: We can't define an actual object here, so we have to hope
-                  # that people will look at the OpenAPI source or can figure it out
-                  # from the other endpoints/example.
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
                   type: object
-                  title: OneTimeKeys
                   description: |-
                     One-time public keys for "pre-key" messages.  The names of
                     the properties should be in the format
@@ -65,10 +62,9 @@ paths:
                           ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
                 fallback_keys:
                   x-addedInMatrixVersion: "1.2"
-                  # $ref: "definitions/one_time_keys.yaml"
-                  # XXX: We can't define an actual object here - see above.
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
                   type: object
-                  title: OneTimeKeys
                   description: |-
                     The public key which should be used if the device's one-time keys
                     are exhausted. The fallback key is not deleted once used, but should
@@ -349,13 +345,7 @@ paths:
                     additionalProperties:
                       type: object
                       additionalProperties:
-                        # $ref: "definitions/one_time_keys.yaml"
-                        # XXX: We can't define an actual object here, so we have to hope
-                        # that people will read the link provided in the description
-                        # and figure it out from the other endpoints/example.
-                        # See also one_time_key parameter for /keys/upload above.
-                        type: object
-                        title: OneTimeKeys
+                        $ref: "definitions/one_time_keys.yaml"
                     example:
                       "@alice:example.com":
                         JLAFKJWSCS:

From eea3dfa969161fce83644f98bd26603b2cb44e7c Mon Sep 17 00:00:00 2001
From: Matthias Ahouansou <matthias@ahouansou.cz>
Date: Wed, 1 May 2024 09:48:11 +0000
Subject: [PATCH 38/82] Mention notifying AS for sender_localpart events
 (#1810)

Signed-off-by: Matthias Ahouansou <matthias@ahouansou.cz>
---
 .../newsfragments/1810.clarification                  |  1 +
 .../application-service/definitions/registration.yaml | 11 +++++++----
 2 files changed, 8 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/application_service/newsfragments/1810.clarification

diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification
new file mode 100644
index 00000000..66dab495
--- /dev/null
+++ b/changelogs/application_service/newsfragments/1810.clarification
@@ -0,0 +1 @@
+Clarify that appservices should be notified of events relating to the sender_localpart user.
diff --git a/data/api/application-service/definitions/registration.yaml b/data/api/application-service/definitions/registration.yaml
index d9dfe748..2d65a32c 100644
--- a/data/api/application-service/definitions/registration.yaml
+++ b/data/api/application-service/definitions/registration.yaml
@@ -29,7 +29,9 @@ properties:
     description: A secret token that the homeserver will use authenticate requests to the application service.
   sender_localpart:
     type: string
-    description: The localpart of the user associated with the application service.
+    description: |-
+      The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
+      is a joined member of the room where the event occurred.
   namespaces:
     type: object
     title: Namespaces
@@ -40,9 +42,10 @@ properties:
           - $ref: namespace_list.yaml
           - description: |-
               A list of namespaces defining the user IDs that the application
-              service is interested in. Events will be sent to the AS if a
-              local user matching one of the namespaces is the target of the event,
-              or is a joined member of the room where the event occurred.
+              service is interested in, in addition to its `sender_localpart`.
+              Events will be sent to the AS if a local user matching one of the
+              namespaces is the target of the event, or is a joined member of
+              the room where the event occurred.
       rooms:
         allOf:
           - $ref: namespace_list.yaml

From 48f4c4954fb7445fc9a64cf9201213e54534d802 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Thu, 2 May 2024 11:10:16 +0100
Subject: [PATCH 39/82] Include information about additionalProperties in
 object tables (#1798)

Currently, if we have an object which has additionalProperties in addition to properties, that information gets lost. This PR seeks to address that.
---
 .../internal/newsfragments/1798.clarification |  1 +
 data/api/identity/v2_terms.yaml               |  1 -
 .../json-schema/resolve-additional-types.html | 45 +++++++++++++------
 .../partials/openapi/render-object-table.html | 40 ++++++++++++++---
 4 files changed, 67 insertions(+), 20 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1798.clarification

diff --git a/changelogs/internal/newsfragments/1798.clarification b/changelogs/internal/newsfragments/1798.clarification
new file mode 100644
index 00000000..5bd28a93
--- /dev/null
+++ b/changelogs/internal/newsfragments/1798.clarification
@@ -0,0 +1 @@
+Show information about "Additional Properties" in object tables.
diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml
index d9eea90e..d7c231d4 100644
--- a/data/api/identity/v2_terms.yaml
+++ b/data/api/identity/v2_terms.yaml
@@ -52,7 +52,6 @@ paths:
                             might be and could be "alpha", semantically versioned, or arbitrary.
                       required:
                         - version
-                      # TODO: TravisR - Make this render
                       additionalProperties:
                         type: object
                         title: Internationalised Policy
diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html
index cf5e9953..f6f09646 100644
--- a/layouts/partials/json-schema/resolve-additional-types.html
+++ b/layouts/partials/json-schema/resolve-additional-types.html
@@ -29,6 +29,8 @@
  *
  *     * title
  *     * properties
+ *     * additionalProperties
+ *     * patternProperties
  *     * required
  *     * enum
  *     * anchor
@@ -45,27 +47,31 @@
     "schema" .schema
     "anchor_base" .anchor_base
     "name" (.name | default .schema.title | default "<untitled object>")
+    "top_level" true
 ) }}
 {{ return $res.objects }}
 
 /*
  * A helper for the resolve-additional-types partial.
  *
- * Takes the same inputs as resolve-additional-types itself, except that `name` is mandatory.
+ * Takes the same inputs as resolve-additional-types itself, except:
+ *   * `name` is mandatory.
+ *   * `top_level`, if set, indicates that this is the top-level object.
  *
  * Returns a dict containing:
  *
  *   * `objects`: The array of object schema definitions.
  *
- *   * `schema`: An updated copy of the `schema` input (eg, nested `allOf`
- *     entries are expanded, and an `anchor` may be added). If the input
- *     `schema` was itself an object, this will be the same as the first entry
- *     in `objects`.
+ *   * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added).
+ *     If the input `schema` was itself an object that we should create a table for,
+ *     this will be the same as the first entry in `objects`.
  */
 {{ define "partials/resolve-additional-types-inner" }}
     {{ $this_object := .schema }}
     {{ $anchor_base := .anchor_base }}
     {{ $name := .name }}
+    {{ $top_level := .top_level }}
+
     {{ $all_objects := slice }}
 
     {{ if eq $this_object.type "object" }}
@@ -126,12 +132,24 @@
             {{ $this_object = merge $this_object (dict "properties" $updated_properties) }}
         {{ end }}
 
-        /* Finally, prepend the updated schema for the top-level object onto the $all_objects array */
-        {{ $tmp := slice $this_object }}
-        {{ if $all_objects }}
-            {{ $tmp = $tmp | append $all_objects }}
+        /* We'll want to create a table for `$this_object` itself if either:
+         *
+         *  - The object has some regular properties (not just patternProperties or additionalProperties), or:
+         *  - It is the top-level object. (We use a special format of table for top-level objects that
+         *    only have patternProperties or additionalProperties)
+         *
+         * In those cases, prepend the updated schema for the top-level object onto the $all_objects array.
+         *
+         * We think about this last so that we can take advantage of any updates to the schema that happened
+         * above (in particular, addition of `anchor` attributes).
+         */
+        {{ if or $this_object.properties $top_level }}
+            {{ $tmp := slice $this_object }}
+            {{ if $all_objects }}
+                {{ $tmp = $tmp | append $all_objects }}
+            {{ end }}
+            {{ $all_objects = $tmp }}
         {{ end }}
-        {{ $all_objects = $tmp }}
     {{ end }}
 
     {{ if eq $this_object.type "array" }}
@@ -198,8 +216,7 @@
  *
  * Returns a dict containing:
  *   * `objects`: The array of object schema definitions.
- *   * `schema`: An updated copy of the `schema` input (eg, nested `allOf`
- *     entries are expanded, and an `anchor` may be added).
+ *   * `schema`: An updated copy of the `schema` input (eg, an `anchor` may be added).
  */
 {{ define "partials/get-additional-objects" }}
     /* .name is the name of the object for logging purposes */
@@ -211,7 +228,7 @@
       {{ errorf "Invalid call to partials/get-additional-objects: %s is not a map" $name .this_object }}
     {{ end }}
 
-    {{ $res := partial "resolve-additional-types-inner" (dict "schema" .this_object "anchor_base" .anchor_base "name" $name) }}
+    {{ $res := partial "resolve-additional-types-inner" (dict "schema" .this_object "anchor_base" .anchor_base "name" $name "top_level" false) }}
     {{ range $res.objects }}
         {{ $all_objects = $all_objects | append (partial "clean-object" .) }}
     {{ end }}
@@ -226,5 +243,5 @@
  * but with (for example) different examples will be considered different.
  */
 {{ define "partials/clean-object" }}
-    {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }}
+    {{ return (dict "title" .title "properties" .properties "additionalProperties" .additionalProperties "patternProperties" .patternProperties "required" .required "enum" .enum "anchor" .anchor) }}
 {{ end }}
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 21d77c89..72ea5a8a 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -9,11 +9,11 @@
   * `properties`: optional dictionary of the properties to list, each given as:
     `property_name` : `property_data`
 
-  * `additionalProperties`: optional dictionary for properties with undefined
-    names, in the same format as `property_data`
+  * `additionalProperties`: a JSON Schema for additional properties on the
+    object.
 
   * `patternProperties`: optional dictionary for properties with names adhering
-    to a regex pattern, in the same format as `property_data`
+    to a regex pattern. A map from regex pattern to JSON Schema.
 
   * `required`: optional array containing the names of required properties.
     In some cases (such as response body specifications) this isn't used, and
@@ -26,7 +26,6 @@
 {{ $required := .required}}
 
 {{ if $properties }}
-
 <table{{ if .anchor }} id="{{ .anchor }}"{{ end }} class="object-table">
  {{ with $title }}
  <caption>{{ . }}</caption>
@@ -52,9 +51,40 @@
 
     {{ end }}
 
+    {{/*
+      If the object has additional properties *as well as* regular properties, we add a special row to the table.
+
+      Note that, per https://json-schema.org/draft/2020-12/json-schema-core#name-boolean-json-schemas, JSON schemas
+      can be a simple "true" or "false" as well as the more normal object.
+
+      `additionalProperties: true` is pretty much the default for Matrix (it means: "you're allowed to include random
+      unspecced properties in your object"), so nothing to do here.
+
+      `additionalProperties: false` means "you're not allowed to include any unspecced properties in your object". We
+      may want to consider how to display that; for now we just ignore it.
+
+      TODO: support `patternProperties` here.
+    */}}
+    {{ if reflect.IsMap .additionalProperties }}
+
+ <tr>
+  <td>&lt;Other properties&gt;</code></td>
+  <td><code>{{ partial "partials/property-type" .additionalProperties | safeHTML }}</code></td>
+  <td>{{ partial "partials/property-description" (dict "property" .additionalProperties) }}</td>
+ </tr>
+    {{ end }}
 </table>
 
 {{ else if (or .additionalProperties .patternProperties) }}
+
+{{/*
+A special format of table for objects which only have additionalProperties or patternProperties.
+
+This is only ever used for top-level objects. Nested objects in this situation are just shown
+as rows within their parent object, and don't get their own table. (They are filtered out in
+resolve-additional-types.)
+*/}}
+
 <table{{ if .anchor }} id="{{ .anchor }}"{{ end }} class="object-table">
  {{ with $title }}
  <caption>{{ . }}</caption>
@@ -116,7 +146,7 @@
     {{ else if or (reflect.IsSlice .type) .oneOf }}
         {{/*
             It's legal to specify an array of types.
-            
+
             There are two ways to do that:
               - Use an array of strings.
               - Use oneOf, with items having a schema.

From 98d85cf421f23233bbfde4232d78634836281cae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 8 May 2024 02:50:36 +0200
Subject: [PATCH 40/82] Add support for rendering string formats (#1814)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1814.clarification |  1 +
 data/custom-formats.yaml                      |  5 +++
 .../partials/openapi/render-object-table.html | 32 +++++++++++++++++--
 3 files changed, 35 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1814.clarification

diff --git a/changelogs/internal/newsfragments/1814.clarification b/changelogs/internal/newsfragments/1814.clarification
new file mode 100644
index 00000000..a540ea7e
--- /dev/null
+++ b/changelogs/internal/newsfragments/1814.clarification
@@ -0,0 +1 @@
+Add support for rendering string formats.
diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml
index f0001c80..5da7e6ab 100644
--- a/data/custom-formats.yaml
+++ b/data/custom-formats.yaml
@@ -31,3 +31,8 @@ mx-event-id:
   title: Event ID
   url: /appendices#event-ids
   # regex: "^\\$"
+
+uri:
+  title: URI
+  url: http://tools.ietf.org/html/rfc3986
+  # no regex
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index 72ea5a8a..d2b09acb 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -128,6 +128,8 @@ resolve-additional-types.)
 
     * `anchor`: optional HTML element id for the target type, which will be used to link to it.
 
+    * `format`: optional string for the format of the type, used for strings.
+
 */}}
 {{ define "partials/property-type" }}
     {{ $type := "" }}
@@ -143,6 +145,15 @@ resolve-additional-types.)
         {{ $items := .items }}
         {{ $inner_type := partial "property-type" $items }}
         {{ $type = delimit (slice "[" $inner_type "]") "" }}
+    {{ else if eq .type "string" }}
+        {{ $type = "string" }}
+
+        {{/* If the string uses a known format, use it. */}}
+        {{ with .format }}
+            {{ with partial "custom-format" . }}
+                {{ $type = . }}
+            {{ end }}
+        {{ end }}
     {{ else if or (reflect.IsSlice .type) .oneOf }}
         {{/*
             It's legal to specify an array of types.
@@ -167,7 +178,7 @@ resolve-additional-types.)
 
         {{ $type = delimit $types "|" }}
     {{ else }}
-        {{/* A simple type like string or boolean */}}
+        {{/* A simple type like integer or boolean */}}
         {{ $type = (htmlEscape .type) }}
     {{ end }}
 
@@ -241,8 +252,8 @@ resolve-additional-types.)
         {{ range $formatId, $formatType := $formatMap.Values }}
             {{ $formatKey := "string" }}
             {{ if ne $formatId "string" }}
-                {{ with index site.Data "custom-formats" $formatId }}
-                    {{ $formatKey = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+                {{ with partial "custom-format" $formatId }}
+                    {{ $formatKey = . }}
                 {{ else }}
                     {{ errorf "Unsupported value for `x-pattern-format`: %s" $formatId }}
                 {{ end }}
@@ -290,3 +301,18 @@ resolve-additional-types.)
     {{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}}
     {{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}}
 {{ end }}
+
+
+{{/*
+    Computes the type to display for a string format, given the identifier of
+    the format as a string.
+*/}} 
+{{ define "partials/custom-format" }}
+  {{ $customFormat := "" }}
+
+  {{ with index site.Data "custom-formats" . }}
+    {{ $customFormat = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+  {{ end }}
+
+  {{ return $customFormat }}
+{{ end }}

From f4b34ba962b28a9372090759a74ca587b4774a9b Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Wed, 8 May 2024 13:22:26 +0100
Subject: [PATCH 41/82] Note that whitespace around `Authorization` param
 commas is allowed (#1818)

---
 .../server_server/newsfragments/1818.clarification   |  1 +
 content/server-server-api.md                         | 12 +++++++-----
 2 files changed, 8 insertions(+), 5 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1818.clarification

diff --git a/changelogs/server_server/newsfragments/1818.clarification b/changelogs/server_server/newsfragments/1818.clarification
new file mode 100644
index 00000000..8c50b6ac
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1818.clarification
@@ -0,0 +1 @@
+Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list.
\ No newline at end of file
diff --git a/content/server-server-api.md b/content/server-server-api.md
index fb1b06f4..e92d871c 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -350,9 +350,10 @@ def authorization_headers(origin_name, origin_signing_key,
 
 The format of the Authorization header is given in
 [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In
-summary, the header begins with authorization scheme `X-Matrix`, followed by
-one or more spaces, followed by a comma-separated list of parameters written as
-name=value pairs. The names are case insensitive and order does not matter. The
+summary, the header begins with authorization scheme `X-Matrix`, followed by one
+or more spaces, followed by a comma-separated list of parameters written as
+name=value pairs. Zero or more spaces and tabs around each comma are allowed.
+The names are case insensitive and order does not matter. The
 values must be enclosed in quotes if they contain characters that are not
 allowed in `token`s, as defined in
 [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a
@@ -363,8 +364,9 @@ replaced by the character that follows the backslash.
 
 For compatibility with older servers, the sender should
 - only include one space after `X-Matrix`,
-- only use lower-case names, and
-- avoid using backslashes in parameter values.
+- only use lower-case names,
+- avoid using backslashes in parameter values, and
+- avoid including whitespace around the commas between name=value pairs.
 
 For compatibility with older servers, the recipient should allow colons to be
 included in values without requiring the value to be enclosed in quotes.

From df1e799c517a9bbdcc96e3f381fd6116d4136040 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 8 May 2024 14:51:18 +0100
Subject: [PATCH 42/82] Spec terms of service at registration (MSC1692) (#1812)

Spec for matrix-org/matrix-spec-proposals#1692

Co-authored-by: Hubert Chathi <hubertc@matrix.org>
---
 .../client_server/newsfragments/1812.feature  |   1 +
 content/client-server-api/_index.md           | 153 ++++++++++++++++--
 .../definitions/m.login.terms_params.yaml     |  82 ++++++++++
 3 files changed, 226 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1812.feature
 create mode 100644 data/api/client-server/definitions/m.login.terms_params.yaml

diff --git a/changelogs/client_server/newsfragments/1812.feature b/changelogs/client_server/newsfragments/1812.feature
new file mode 100644
index 00000000..baa9aa7d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1812.feature
@@ -0,0 +1 @@
+Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index ba527275..b0ce7289 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -546,8 +546,10 @@ request parameter.
 A client should first make a request with no `auth` parameter.
 The homeserver returns an HTTP 401 response, with a JSON body, as follows:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -590,8 +592,10 @@ given. It also contains other keys dependent on the auth type being
 attempted. For example, if the client is attempting to complete auth
 type `example.type.foo`, it might submit something like this:
 
-    POST /_matrix/client/v3/endpoint HTTP/1.1
-    Content-Type: application/json
+```
+POST /_matrix/client/v3/endpoint HTTP/1.1
+Content-Type: application/json
+```
 
 ```json
 {
@@ -611,8 +615,10 @@ along with the same object as when no authentication was attempted, with
 the addition of the `completed` key which is an array of auth types the
 client has completed successfully:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -643,8 +649,10 @@ but the client may make a second attempt, it returns the same HTTP
 status 401 response as above, with the addition of the standard
 `errcode` and `error` fields describing the error. For example:
 
-    HTTP/1.1 401 Unauthorized
-    Content-Type: application/json
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: application/json
+```
 
 ```json
 {
@@ -671,8 +679,10 @@ status 401 response as above, with the addition of the standard
 If the request fails for a reason other than authentication, the server
 returns an error message in the standard format. For example:
 
-    HTTP/1.1 400 Bad request
-    Content-Type: application/json
+```
+HTTP/1.1 400 Bad request
+Content-Type: application/json
+```
 
 ```json
 {
@@ -970,6 +980,129 @@ in the registration process that their token has expired.
 
 {{% http-api spec="client-server" api="registration_tokens" %}}
 
+##### Terms of service at registration
+
+{{% added-in v="1.11" %}}
+
+| Type                     | Description                                                              |
+|--------------------------|--------------------------------------------------------------------------|
+| `m.login.terms`          | Authentication requires the user to accept a set of policy documents. |
+
+{{% boxes/note %}}
+The `m.login.terms` authentication type is only valid on the
+[`/register`](#post_matrixclientv3register) endpoint.
+{{% /boxes/note %}}
+
+This authentication type is used when the homeserver requires new users to
+accept a given set of policy documents, such as a terms of service and a privacy
+policy. There may be many different types of documents, all of which are
+versioned and presented in (potentially) multiple languages.
+
+When the server requires the user to accept some terms, it does so by returning
+a 401 response to the `/register` request, where the response body includes
+`m.login.terms` in the `flows` list, and the `m.login.terms` property in the
+`params` object has the structure [shown below](#definition-mloginterms-params).
+
+If a client encounters an invalid parameter, registration should stop with an
+error presented to the user.
+
+The client should present the user with a checkbox to accept each policy,
+including a link to the provided URL. Once the user has done so, the client
+submits an `auth` dict with just the `type` and `session`, as follows, to
+indicate that all of the policies have been accepted:
+
+```json
+{
+  "type": "m.login.terms",
+  "session": "<session ID>"
+}
+```
+
+The server is expected to track which document versions it presented to the
+user during registration, if applicable.
+
+
+**Example**
+
+1. A client might submit a registration request as follows:
+
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas"
+   }
+   ```
+
+2. The server requires the user to accept some terms of service before
+   registration, so returns the following response:
+
+   ```
+   HTTP/1.1 401 Unauthorized
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "flows": [
+       { "stages": [ "m.login.terms" ] }
+     ],
+     "params": {
+       "m.login.terms": {
+         "policies": {
+           "terms_of_service": {
+             "version": "1.2",
+             "en": {
+                 "name": "Terms of Service",
+                 "url": "https://example.org/somewhere/terms-1.2-en.html"
+             },
+             "fr": {
+                 "name": "Conditions d'utilisation",
+                 "url": "https://example.org/somewhere/terms-1.2-fr.html"
+             }
+           }
+         }
+       }
+     },
+     "session": "kasgjaelkgj"
+   }
+   ```
+
+3. The client presents the list of documents to the user, inviting them to
+   accept the polices.
+
+4. The client repeats the registration request, confirming that the user has
+   accepted the documents:
+   ```
+   POST /_matrix/client/v3/register
+   ```
+   ```json
+   {
+     "username": "cheeky_monkey",
+     "password": "ilovebananas",
+     "auth": {
+       "type": "m.login.terms",
+       "session": "kasgjaelkgj"
+     }
+   }
+   ```
+
+5. All authentication steps have now completed, so the request is successful:
+   ```
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+   ```
+   ```json
+   {
+     "access_token": "abc123",
+     "device_id": "GHTYAJCE",
+     "user_id": "@cheeky_monkey:matrix.org"
+   }
+   ```
+
+{{% definition path="api/client-server/definitions/m.login.terms_params" %}}
+
 #### Fallback
 
 Clients cannot be expected to be able to know how to process every
diff --git a/data/api/client-server/definitions/m.login.terms_params.yaml b/data/api/client-server/definitions/m.login.terms_params.yaml
new file mode 100644
index 00000000..67001c18
--- /dev/null
+++ b/data/api/client-server/definitions/m.login.terms_params.yaml
@@ -0,0 +1,82 @@
+# Copyright 2024 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: m.login.terms params
+description: Schema for `m.login.terms` entry in the `params` object in a User-Interactive Authentication response.
+required: ['policies']
+properties:
+  policies:
+    type: object
+    description: |
+      A map from "Policy ID" to the current definition of this policy document. The Policy ID is a unique
+      identifier for a given policy document, using the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+    additionalProperties:
+      type: object
+      title: Policy Definition
+      required: [version]
+      properties:
+        version:
+          type: string
+          description: |
+            The version of this policy document. This is provided as a convenience for the client,
+            and uses the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+      additionalProperties:
+        type: object
+        title: Policy Translation
+        required: [name, url]
+        description: |
+          Map from language codes to details of the document in that language.
+          Language codes SHOULD be formatted as per [Section 2.2 of RFC
+          5646](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2),
+          though some implementations may use an underscore instead of dash
+          (for example, `en_US` instead of `en-US`).
+        properties:
+          name:
+            type: string
+            description: |
+              The name of this document, in the appropriate language. An
+              arbitrary string with no specified maximum length.
+          url:
+            type: string
+            description: |
+              A link to the text of this document, in the appropriate
+              language. MUST be a valid URI with scheme `https://` or
+              `http://`. Insecure HTTP is discouraged.
+example: {
+    "policies": {
+        "terms_of_service": {
+            "version": "1.2",
+            "en": {
+                "name": "Terms of Service",
+                "url": "https://example.org/somewhere/terms-1.2-en.html"
+            },
+            "fr": {
+                "name": "Conditions d'utilisation",
+                "url": "https://example.org/somewhere/terms-1.2-fr.html"
+            }
+        },
+        "privacy_policy": {
+            "version": "1.2",
+            "en": {
+                "name": "Privacy Policy",
+                "url": "https://example.org/somewhere/privacy-1.2-en.html"
+            },
+            "fr": {
+                "name": "Politique de confidentialité",
+                "url": "https://example.org/somewhere/privacy-1.2-fr.html"
+            }
+        }
+    }
+}
\ No newline at end of file

From b0df8e7fb58ddef4f96c0c527b66d2c7e55255b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Wed, 8 May 2024 15:59:17 +0200
Subject: [PATCH 43/82] Use `patternProperties` in more places with supported
 formats (#1813)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Allows to have more places where the property name's type is better defined.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../newsfragments/1813.clarification          |   1 +
 .../newsfragments/1813.clarification          |   1 +
 data/api/client-server/cross_signing.yaml     |  18 +-
 .../definitions/device_keys.yaml              |  10 +-
 .../definitions/one_time_keys.yaml            |   6 +-
 data/api/client-server/key_backup.yaml        |  14 +-
 data/api/client-server/keys.yaml              |  95 +++--
 data/api/client-server/rooms.yaml             |  26 +-
 data/api/client-server/search.yaml            |  40 +-
 data/api/client-server/sync.yaml              | 398 +++++++++---------
 data/api/client-server/to_device.yaml         |  12 +-
 .../event-schemas/m.direct_to_device.yaml     |  14 +-
 .../definitions/event-schemas/m.receipt.yaml  |  90 ++--
 data/api/server-server/transactions.yaml      |  24 +-
 data/api/server-server/user_keys.yaml         | 126 +++---
 data/custom-formats.yaml                      |   5 +
 data/event-schemas/schema/m.direct.yaml       |  10 +-
 .../schema/m.room.power_levels.yaml           |   6 +-
 18 files changed, 489 insertions(+), 407 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1813.clarification
 create mode 100644 changelogs/server_server/newsfragments/1813.clarification

diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification
new file mode 100644
index 00000000..af643e2e
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1813.clarification
@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.
diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification
new file mode 100644
index 00000000..af643e2e
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1813.clarification
@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.
diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml
index 16539eb0..0f3a46be 100644
--- a/data/api/client-server/cross_signing.yaml
+++ b/data/api/client-server/cross_signing.yaml
@@ -165,10 +165,12 @@ paths:
               type: object
               description: |-
                 A map of user ID to a map of key ID to signed JSON object.
-              additionalProperties:
-                type: object
-                additionalProperties:
+              patternProperties:
+                "^@":
+                  x-pattern-format: mx-user-id
                   type: object
+                  additionalProperties:
+                    type: object
               example: {
                 "@alice:example.com": {
                   "HIJKLMN": {
@@ -238,11 +240,13 @@ paths:
                       A map from user ID to key ID to an error for any signatures
                       that failed.  If a signature was invalid, the `errcode` will
                       be set to `M_INVALID_SIGNATURE`.
-                    additionalProperties:
-                      type: object
-                      additionalProperties:
+                    patternProperties:
+                      "^@":
                         type: object
-                        title: Error
+                        x-pattern-format: mx-user-id
+                        additionalProperties:
+                          type: object
+                          title: Error
                     example:
                       "@alice:example.com":
                         HIJKLMN:
diff --git a/data/api/client-server/definitions/device_keys.yaml b/data/api/client-server/definitions/device_keys.yaml
index ab033941..2a7f8104 100644
--- a/data/api/client-server/definitions/device_keys.yaml
+++ b/data/api/client-server/definitions/device_keys.yaml
@@ -53,10 +53,12 @@ properties:
        `<algorithm>:<device_id>` to the signature.
 
        The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-    additionalProperties:
-      type: object
-      additionalProperties:
-        type: string
+    patternProperties:
+      "^@":
+        x-pattern-format: mx-user-id
+        type: object
+        additionalProperties:
+          type: string
     example:
       "@alice:example.com":
         "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
diff --git a/data/api/client-server/definitions/one_time_keys.yaml b/data/api/client-server/definitions/one_time_keys.yaml
index d54494d9..78711350 100644
--- a/data/api/client-server/definitions/one_time_keys.yaml
+++ b/data/api/client-server/definitions/one_time_keys.yaml
@@ -20,6 +20,8 @@ additionalProperties:
             Signature for the device. Mapped from user ID to signature object,
             containing mapping from _key signing identifier_ to the signature
             (see also: [Signing JSON](/appendices/#signing-json))
-          additionalProperties:
-            type: object
+          patternProperties:
+            "^@":
+              x-pattern-format: mx-user-id
+              type: object
       required: ['key', 'signatures']
diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml
index 103071dd..64833f6e 100644
--- a/data/api/client-server/key_backup.yaml
+++ b/data/api/client-server/key_backup.yaml
@@ -840,8 +840,11 @@ paths:
                 rooms:
                   type: object
                   description: A map of room IDs to room key backup data.
-                  additionalProperties:
-                    $ref: definitions/room_key_backup.yaml
+                  patternProperties:
+                    "^!":
+                      x-pattern-format: mx-room-id
+                      allOf:
+                        - $ref: definitions/room_key_backup.yaml
                   example:
                     "!room:example.org":
                       sessions:
@@ -944,8 +947,11 @@ paths:
                   rooms:
                     type: object
                     description: A map of room IDs to room key backup data.
-                    additionalProperties:
-                      $ref: definitions/room_key_backup.yaml
+                    patternProperties:
+                      "^!":
+                        x-pattern-format: mx-room-id
+                        allOf:
+                          - $ref: definitions/room_key_backup.yaml
                     example:
                       "!room:example.org":
                         sessions:
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index f165f379..001fe1f5 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -137,11 +137,13 @@ paths:
                     The keys to be downloaded. A map from user ID, to a list of
                     device IDs, or to an empty list to indicate all devices for the
                     corresponding user.
-                  additionalProperties:
-                    type: array
-                    items:
-                      type: string
-                      description: device ID
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: array
+                      items:
+                        type: string
+                        description: device ID
                   example:
                     "@alice:example.com": []
               required:
@@ -177,24 +179,26 @@ paths:
                       the information returned will be the same as uploaded via
                       `/keys/upload`, with the addition of an `unsigned`
                       property.
-                    additionalProperties:
-                      type: object
-                      additionalProperties:
-                        title: DeviceInformation
-                        allOf:
-                          - $ref: definitions/device_keys.yaml
-                        properties:
-                          unsigned:
-                            title: UnsignedDeviceInfo
-                            type: object
-                            description: |-
-                              Additional data added to the device key information
-                              by intermediate servers, and not covered by the
-                              signatures.
-                            properties:
-                              device_display_name:
-                                type: string
-                                description: The display name which the user set on the device.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        type: object
+                        additionalProperties:
+                          title: DeviceInformation
+                          allOf:
+                            - $ref: definitions/device_keys.yaml
+                          properties:
+                            unsigned:
+                              title: UnsignedDeviceInfo
+                              type: object
+                              description: |-
+                                Additional data added to the device key information
+                                by intermediate servers, and not covered by the
+                                signatures.
+                              properties:
+                                device_display_name:
+                                  type: string
+                                  description: The display name which the user set on the device.
                     example:
                       "@alice:example.com":
                         JLAFKJWSCS:
@@ -221,8 +225,11 @@ paths:
                       `/keys/device_signing/upload`, along with the signatures
                       uploaded via `/keys/signatures/upload` that the requesting user
                       is allowed to see.
-                    additionalProperties:
-                      $ref: definitions/cross_signing_key.yaml
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -238,8 +245,11 @@ paths:
                       from user ID, to self-signing key information.  For each key, the
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
-                    additionalProperties:
-                      $ref: definitions/cross_signing_key.yaml
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -258,8 +268,11 @@ paths:
                       from user ID, to user-signing key information.  The
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
-                    additionalProperties:
-                      $ref: definitions/cross_signing_key.yaml
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -297,12 +310,14 @@ paths:
                   description: |-
                     The keys to be claimed. A map from user ID, to a map from
                     device ID to algorithm name.
-                  additionalProperties:
-                    type: object
-                    additionalProperties:
-                      type: string
-                      description: algorithm
-                      example: signed_curve25519
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: object
+                      additionalProperties:
+                        type: string
+                        description: algorithm
+                        example: signed_curve25519
                   example:
                     "@alice:example.com":
                       JLAFKJWSCS: signed_curve25519
@@ -342,10 +357,12 @@ paths:
 
                       If necessary, the claimed key might be a fallback key. Fallback
                       keys are re-used by the server until replaced by the device.
-                    additionalProperties:
-                      type: object
-                      additionalProperties:
-                        $ref: "definitions/one_time_keys.yaml"
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        type: object
+                        additionalProperties:
+                          $ref: "definitions/one_time_keys.yaml"
                     example:
                       "@alice:example.com":
                         JLAFKJWSCS:
diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml
index be5466b7..a2197f34 100644
--- a/data/api/client-server/rooms.yaml
+++ b/data/api/client-server/rooms.yaml
@@ -299,18 +299,20 @@ paths:
                 type: object
                 properties:
                   joined:
-                    additionalProperties:
-                      title: RoomMember
-                      type: object
-                      properties:
-                        display_name:
-                          type: string
-                          description: The display name of the user this object is representing.
-                        avatar_url:
-                          type: string
-                          format: uri
-                          description: The avatar of the user this object is representing, as an [`mxc://`
-                            URI](/client-server-api/#matrix-content-mxc-uris).
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        title: RoomMember
+                        type: object
+                        properties:
+                          display_name:
+                            type: string
+                            description: The display name of the user this object is representing.
+                          avatar_url:
+                            type: string
+                            format: uri
+                            description: The avatar of the user this object is representing, as an [`mxc://`
+                              URI](/client-server-api/#matrix-content-mxc-uris).
                     description: A map from user ID to a RoomMember object.
                     type: object
               examples:
diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml
index 2d0475c5..587894ff 100644
--- a/data/api/client-server/search.yaml
+++ b/data/api/client-server/search.yaml
@@ -225,19 +225,21 @@ paths:
                                         The historic profile information of the
                                         users that sent the events returned.
 
-                                        The `string` key is the user ID for which
+                                        The key is the user ID for which
                                         the profile belongs to.
-                                      additionalProperties:
-                                        type: object
-                                        title: User Profile
-                                        properties:
-                                          displayname:
-                                            type: string
-                                            title: Display name
-                                          avatar_url:
-                                            type: string
-                                            format: uri
-                                            title: Avatar Url
+                                      patternProperties:
+                                        "^@":
+                                          x-pattern-format: mx-user-id
+                                          type: object
+                                          title: User Profile
+                                          properties:
+                                            displayname:
+                                              type: string
+                                              title: Display name
+                                            avatar_url:
+                                              type: string
+                                              format: uri
+                                              title: Avatar Url
                                     events_before:
                                       type: array
                                       title: Events Before
@@ -262,13 +264,15 @@ paths:
                               This is included if the request had the
                               `include_state` key set with a value of `true`.
 
-                              The `string` key is the room ID for which the `State
+                              The key is the room ID for which the `State
                               Event` array belongs to.
-                            additionalProperties:
-                              type: array
-                              title: Room State
-                              items:
-                                $ref: definitions/client_event.yaml
+                            patternProperties:
+                              "^!":
+                                x-pattern-format: mx-room-id
+                                type: array
+                                title: Room State
+                                items:
+                                  $ref: definitions/client_event.yaml
                           groups:
                             type: object
                             title: Groups
diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml
index 3f06d13c..efe36c5c 100644
--- a/data/api/client-server/sync.yaml
+++ b/data/api/client-server/sync.yaml
@@ -141,223 +141,233 @@ paths:
                         description: |-
                           The rooms that the user has joined, mapped as room ID to
                           room information.
-                        additionalProperties:
-                          title: Joined Room
-                          type: object
-                          properties:
-                            summary:
-                              title: RoomSummary
-                              type: object
-                              description: |-
-                                Information about the room which clients may need to
-                                correctly render it to users.
-                              properties:
-                                m.heroes:
-                                  type: array
-                                  description: |-
-                                    The users which can be used to generate a room name
-                                    if the room does not have one. Required if the room's
-                                    `m.room.name` or `m.room.canonical_alias` state events
-                                    are unset or empty.
-
-                                    This should be the first 5 members of the room, ordered
-                                    by stream ordering, which are joined or invited. The
-                                    list must never include the client's own user ID. When
-                                    no joined or invited members are available, this should
-                                    consist of the banned and left users. More than 5 members
-                                    may be provided, however less than 5 should only be provided
-                                    when there are less than 5 members to represent.
-
-                                    When lazy-loading room members is enabled, the membership
-                                    events for the heroes MUST be included in the `state`,
-                                    unless they are redundant. When the list of users changes,
-                                    the server notifies the client by sending a fresh list of
-                                    heroes. If there are no changes since the last sync, this
-                                    field may be omitted.
-                                  items:
-                                    type: string
-                                m.joined_member_count:
-                                  type: integer
-                                  description: |-
-                                    The number of users with `membership` of `join`,
-                                    including the client's own user ID. If this field has
-                                    not changed since the last sync, it may be omitted.
-                                    Required otherwise.
-                                m.invited_member_count:
-                                  type: integer
-                                  description: |-
-                                    The number of users with `membership` of `invite`.
-                                    If this field has not changed since the last sync, it
-                                    may be omitted. Required otherwise.
-                            state:
-                              title: State
-                              type: object
-                              description: |-
-                                Updates to the state, between the time indicated by
-                                the `since` parameter, and the start of the
-                                `timeline` (or all state up to the start of the
-                                `timeline`, if `since` is not given, or
-                                `full_state` is true).
-
-                                N.B. state updates for `m.room.member` events will
-                                be incomplete if `lazy_load_members` is enabled in
-                                the `/sync` filter, and only return the member events
-                                required to display the senders of the timeline events
-                                in this response.
-                              allOf:
-                                - $ref: definitions/state_event_batch.yaml
-                            timeline:
-                              title: Timeline
-                              type: object
-                              description: |-
-                                The timeline of messages and state changes in the
-                                room.
-                              allOf:
-                                - $ref: definitions/timeline_batch.yaml
-                            ephemeral:
-                              title: Ephemeral
-                              type: object
-                              description: |-
-                                The new ephemeral events in the room (events that
-                                aren't recorded in the timeline or state of the
-                                room). In this version of the spec, these are
-                                [typing notification](#typing-notifications) and
-                                [read receipt](#receipts) events.
-                              allOf:
-                                - $ref: definitions/event_batch.yaml
-                            account_data:
-                              title: Account Data
-                              type: object
-                              description: |-
-                                The private data that this user has attached to
-                                this room.
-                              allOf:
-                                - $ref: definitions/event_batch.yaml
-                            unread_notifications:
-                              title: Unread Notification Counts
-                              type: object
-                              description: |-
-                                Counts of unread notifications for this room. See the
-                                [Receiving notifications](/client-server-api/#receiving-notifications) section
-                                for more information on how these are calculated.
-
-                                If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
-                                these counts will only be for the main timeline rather than all events in the room.
-                                See the [threading module](#threading) for more information.
-                              x-changedInMatrixVersion:
-                                "1.4": |
-                                  Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
-                                  the `RoomEventFilter` for `/sync`.
-                              properties:
-                                highlight_count:
-                                  title: Highlighted notification count
-                                  type: integer
-                                  description: The number of unread notifications for this room with the highlight
-                                    flag set.
-                                notification_count:
-                                  title: Total notification count
-                                  type: integer
-                                  description: The total number of unread notifications for this room.
-                            unread_thread_notifications:
-                              title: Unread Thread Notification Counts
-                              type: object
-                              description: |-
-                                If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
-                                the notification counts for each [thread](#threading) in this room. The object is
-                                keyed by thread root ID, with values matching `unread_notifications`.
-
-                                If a thread does not have any notifications it can be omitted from this object. If
-                                no threads have notification counts, this whole object can be omitted.
-                              x-addedInMatrixVersion: "1.4"
-                              additionalProperties:
-                                title: ThreadNotificationCounts
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Joined Room
+                            type: object
+                            properties:
+                              summary:
+                                title: RoomSummary
                                 type: object
+                                description: |-
+                                  Information about the room which clients may need to
+                                  correctly render it to users.
+                                properties:
+                                  m.heroes:
+                                    type: array
+                                    description: |-
+                                      The users which can be used to generate a room name
+                                      if the room does not have one. Required if the room's
+                                      `m.room.name` or `m.room.canonical_alias` state events
+                                      are unset or empty.
+
+                                      This should be the first 5 members of the room, ordered
+                                      by stream ordering, which are joined or invited. The
+                                      list must never include the client's own user ID. When
+                                      no joined or invited members are available, this should
+                                      consist of the banned and left users. More than 5 members
+                                      may be provided, however less than 5 should only be provided
+                                      when there are less than 5 members to represent.
+
+                                      When lazy-loading room members is enabled, the membership
+                                      events for the heroes MUST be included in the `state`,
+                                      unless they are redundant. When the list of users changes,
+                                      the server notifies the client by sending a fresh list of
+                                      heroes. If there are no changes since the last sync, this
+                                      field may be omitted.
+                                    items:
+                                      type: string
+                                  m.joined_member_count:
+                                    type: integer
+                                    description: |-
+                                      The number of users with `membership` of `join`,
+                                      including the client's own user ID. If this field has
+                                      not changed since the last sync, it may be omitted.
+                                      Required otherwise.
+                                  m.invited_member_count:
+                                    type: integer
+                                    description: |-
+                                      The number of users with `membership` of `invite`.
+                                      If this field has not changed since the last sync, it
+                                      may be omitted. Required otherwise.
+                              state:
+                                title: State
+                                type: object
+                                description: |-
+                                  Updates to the state, between the time indicated by
+                                  the `since` parameter, and the start of the
+                                  `timeline` (or all state up to the start of the
+                                  `timeline`, if `since` is not given, or
+                                  `full_state` is true).
+
+                                  N.B. state updates for `m.room.member` events will
+                                  be incomplete if `lazy_load_members` is enabled in
+                                  the `/sync` filter, and only return the member events
+                                  required to display the senders of the timeline events
+                                  in this response.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              timeline:
+                                title: Timeline
+                                type: object
+                                description: |-
+                                  The timeline of messages and state changes in the
+                                  room.
+                                allOf:
+                                  - $ref: definitions/timeline_batch.yaml
+                              ephemeral:
+                                title: Ephemeral
+                                type: object
+                                description: |-
+                                  The new ephemeral events in the room (events that
+                                  aren't recorded in the timeline or state of the
+                                  room). In this version of the spec, these are
+                                  [typing notification](#typing-notifications) and
+                                  [read receipt](#receipts) events.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
+                              account_data:
+                                title: Account Data
+                                type: object
+                                description: |-
+                                  The private data that this user has attached to
+                                  this room.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
+                              unread_notifications:
+                                title: Unread Notification Counts
+                                type: object
+                                description: |-
+                                  Counts of unread notifications for this room. See the
+                                  [Receiving notifications](/client-server-api/#receiving-notifications) section
+                                  for more information on how these are calculated.
+
+                                  If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                                  these counts will only be for the main timeline rather than all events in the room.
+                                  See the [threading module](#threading) for more information.
+                                x-changedInMatrixVersion:
+                                  "1.4": |
+                                    Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
+                                    the `RoomEventFilter` for `/sync`.
                                 properties:
                                   highlight_count:
-                                    title: ThreadedHighlightNotificationCount
+                                    title: Highlighted notification count
                                     type: integer
-                                    description: The number of unread notifications for this *thread* with the
-                                      highlight flag set.
+                                    description: The number of unread notifications for this room with the highlight
+                                      flag set.
                                   notification_count:
-                                    title: ThreadedTotalNotificationCount
+                                    title: Total notification count
                                     type: integer
-                                    description: The total number of unread notifications for this *thread*.
+                                    description: The total number of unread notifications for this room.
+                              unread_thread_notifications:
+                                title: Unread Thread Notification Counts
+                                type: object
+                                description: |-
+                                  If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                                  the notification counts for each [thread](#threading) in this room. The object is
+                                  keyed by thread root ID, with values matching `unread_notifications`.
+
+                                  If a thread does not have any notifications it can be omitted from this object. If
+                                  no threads have notification counts, this whole object can be omitted.
+                                x-addedInMatrixVersion: "1.4"
+                                patternProperties:
+                                  "^\\$":
+                                    x-pattern-format: mx-event-id
+                                    title: ThreadNotificationCounts
+                                    type: object
+                                    properties:
+                                      highlight_count:
+                                        title: ThreadedHighlightNotificationCount
+                                        type: integer
+                                        description: The number of unread notifications for this *thread* with the
+                                          highlight flag set.
+                                      notification_count:
+                                        title: ThreadedTotalNotificationCount
+                                        type: integer
+                                        description: The total number of unread notifications for this *thread*.
                       invite:
                         title: Invited Rooms
                         type: object
                         description: |-
                           The rooms that the user has been invited to, mapped as room ID to
                           room information.
-                        additionalProperties:
-                          title: Invited Room
-                          type: object
-                          properties:
-                            invite_state:
-                              title: InviteState
-                              type: object
-                              description: |-
-                                The [stripped state](#stripped-state) of a room that the user has been invited
-                                to.
-                              properties:
-                                events:
-                                  description: The [stripped state events](#stripped-state) that form the invite
-                                    state.
-                                  items:
-                                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
-                                  type: array
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Invited Room
+                            type: object
+                            properties:
+                              invite_state:
+                                title: InviteState
+                                type: object
+                                description: |-
+                                  The [stripped state](#stripped-state) of a room that the user has been invited
+                                  to.
+                                properties:
+                                  events:
+                                    description: The [stripped state events](#stripped-state) that form the invite
+                                      state.
+                                    items:
+                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                    type: array
                       knock:
                         title: Knocked rooms
                         type: object
                         description: The rooms that the user has knocked upon, mapped as room ID to room
                           information.
-                        additionalProperties:
-                          title: Knocked Room
-                          type: object
-                          properties:
-                            knock_state:
-                              title: KnockState
-                              type: object
-                              description: The [stripped state](#stripped-state) of a room that the user has
-                                knocked upon.
-                              properties:
-                                events:
-                                  description: The [stripped state events](#stripped-state) that form the knock
-                                    state.
-                                  items:
-                                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
-                                  type: array
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Knocked Room
+                            type: object
+                            properties:
+                              knock_state:
+                                title: KnockState
+                                type: object
+                                description: The [stripped state](#stripped-state) of a room that the user has
+                                  knocked upon.
+                                properties:
+                                  events:
+                                    description: The [stripped state events](#stripped-state) that form the knock
+                                      state.
+                                    items:
+                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                    type: array
                       leave:
                         title: Left rooms
                         type: object
                         description: |-
                           The rooms that the user has left or been banned from, mapped as room ID to
                           room information.
-                        additionalProperties:
-                          title: Left Room
-                          type: object
-                          properties:
-                            state:
-                              title: State
-                              type: object
-                              description: The state updates for the room up to the start of the timeline.
-                              allOf:
-                                - $ref: definitions/state_event_batch.yaml
-                            timeline:
-                              title: Timeline
-                              type: object
-                              description: |-
-                                The timeline of messages and state changes in the
-                                room up to the point when the user left.
-                              allOf:
-                                - $ref: definitions/timeline_batch.yaml
-                            account_data:
-                              title: Account Data
-                              type: object
-                              description: |-
-                                The private data that this user has attached to
-                                this room.
-                              allOf:
-                                - $ref: definitions/event_batch.yaml
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Left Room
+                            type: object
+                            properties:
+                              state:
+                                title: State
+                                type: object
+                                description: The state updates for the room up to the start of the timeline.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              timeline:
+                                title: Timeline
+                                type: object
+                                description: |-
+                                  The timeline of messages and state changes in the
+                                  room up to the point when the user left.
+                                allOf:
+                                  - $ref: definitions/timeline_batch.yaml
+                              account_data:
+                                title: Account Data
+                                type: object
+                                description: |-
+                                  The private data that this user has attached to
+                                  this room.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
                   presence:
                     title: Presence
                     type: object
diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml
index d8c0fff0..cea23ab7 100644
--- a/data/api/client-server/to_device.yaml
+++ b/data/api/client-server/to_device.yaml
@@ -57,12 +57,14 @@ paths:
                     The messages to send. A map from user ID, to a map from
                     device ID to message body. The device ID may also be `*`,
                     meaning all known devices for the user.
-                  additionalProperties:
-                    type: object
-                    additionalProperties:
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
                       type: object
-                      title: EventContent
-                      description: Message content
+                      additionalProperties:
+                        type: object
+                        title: EventContent
+                        description: Message content
                   example:
                     "@alice:example.com":
                       TLLBEANAAG:
diff --git a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml
index 6cb59fdd..3740eace 100644
--- a/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml
+++ b/data/api/server-server/definitions/event-schemas/m.direct_to_device.yaml
@@ -51,13 +51,15 @@ allOf:
               The contents of the messages to be sent.  These are arranged in
               a map of user IDs to a map of device IDs to message bodies.
               The device ID may also be `*`, meaning all known devices for the user.
-            additionalProperties:
-              type: object
-              title: User Devices
-              additionalProperties:
+            patternProperties:
+              "^@":
+                x-pattern-format: mx-user-id
                 type: object
-                title: Device Message Contents
-                properties: {}
+                title: User Devices
+                additionalProperties:
+                  type: object
+                  title: Device Message Contents
+                  properties: {}
             example: {
               "@alice:example.org": {
                 "IWHQUZUIAH": {
diff --git a/data/api/server-server/definitions/event-schemas/m.receipt.yaml b/data/api/server-server/definitions/event-schemas/m.receipt.yaml
index 677dc28d..60bff325 100644
--- a/data/api/server-server/definitions/event-schemas/m.receipt.yaml
+++ b/data/api/server-server/definitions/event-schemas/m.receipt.yaml
@@ -33,54 +33,58 @@ allOf:
         description: |-
           Receipts for a particular room. The string key is the room ID for
           which the receipts under it belong.
-        additionalProperties:
-          type: object
-          title: Room Receipts
-          properties:
-            # We strongly define the receipt type to help spec future ones later
-            # on. At that point, m.read can become optional (maybe).
-            "m.read":
-              type: object
-              description: |-
-                Read receipts for users in the room. The string key is the user
-                ID the receipt belongs to.
-              additionalProperties:
+        patternProperties:
+          "^!":
+            x-pattern-format: mx-room-id
+            type: object
+            title: Room Receipts
+            properties:
+              # We strongly define the receipt type to help spec future ones later
+              # on. At that point, m.read can become optional (maybe).
+              "m.read":
                 type: object
-                title: User Read Receipt
-                properties:
-                  event_ids:
-                    type: array
-                    description: |-
-                      The extremity event IDs that the user has read up to.
-                    minItems: 1
-                    maxItems: 1
-                    items:
-                      type: string
-                    example: ['$read_this_event:matrix.org']
-                  data:
+                description: |-
+                  Read receipts for users in the room. The string key is the user
+                  ID the receipt belongs to.
+                patternProperties:
+                  "^@":
+                    x-pattern-format: mx-user-id
                     type: object
-                    description: Metadata for the read receipt.
-                    title: Read Receipt Metadata
+                    title: User Read Receipt
                     properties:
-                      ts:
-                        type: integer
-                        format: int64
+                      event_ids:
+                        type: array
                         description: |-
-                          A POSIX timestamp in milliseconds for when the user read
-                          the event specified in the read receipt.
-                        example: 1533358089009
-                      thread_id:
+                          The extremity event IDs that the user has read up to.
+                        minItems: 1
+                        maxItems: 1
+                        items:
                           type: string
-                          x-addedInMatrixVersion: "1.4"
-                          description: |-
-                              The root thread event's ID (or `main`) for which
-                              thread this receipt is intended to be under. If
-                              not specified, the read receipt is *unthreaded*
-                              (default).
-                          example: "$threadroot"
-                    required: ['ts']
-                required: ['event_ids', 'data']
-          required: ['m.read']
+                        example: ['$read_this_event:matrix.org']
+                      data:
+                        type: object
+                        description: Metadata for the read receipt.
+                        title: Read Receipt Metadata
+                        properties:
+                          ts:
+                            type: integer
+                            format: int64
+                            description: |-
+                              A POSIX timestamp in milliseconds for when the user read
+                              the event specified in the read receipt.
+                            example: 1533358089009
+                          thread_id:
+                              type: string
+                              x-addedInMatrixVersion: "1.4"
+                              description: |-
+                                  The root thread event's ID (or `main`) for which
+                                  thread this receipt is intended to be under. If
+                                  not specified, the read receipt is *unthreaded*
+                                  (default).
+                              example: "$threadroot"
+                        required: ['ts']
+                    required: ['event_ids', 'data']
+            required: ['m.read']
         example: {
           "!some_room:example.org": {
             "m.read": {
diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml
index 6edd04c3..48377553 100644
--- a/data/api/server-server/transactions.yaml
+++ b/data/api/server-server/transactions.yaml
@@ -74,17 +74,19 @@ paths:
                     description: |-
                       The PDUs from the original transaction. The string key represents the ID of the
                       PDU (event) that was processed.
-                    additionalProperties:
-                      type: object
-                      title: PDU Processing Result
-                      description: Information about how the PDU was handled.
-                      properties:
-                        error:
-                          type: string
-                          description: |-
-                            A human readable description about what went wrong in processing this PDU.
-                            If no error is present, the PDU can be considered successfully handled.
-                          example: You are not allowed to send a message to this room.
+                    patternProperties:
+                      "^\\$":
+                        x-pattern-format: mx-event-id
+                        type: object
+                        title: PDU Processing Result
+                        description: Information about how the PDU was handled.
+                        properties:
+                          error:
+                            type: string
+                            description: |-
+                              A human readable description about what went wrong in processing this PDU.
+                              If no error is present, the PDU can be considered successfully handled.
+                            example: You are not allowed to send a message to this room.
                 required:
                   - pdus
               examples:
diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml
index 780303e3..6f242614 100644
--- a/data/api/server-server/user_keys.yaml
+++ b/data/api/server-server/user_keys.yaml
@@ -36,12 +36,14 @@ paths:
                     The keys to be claimed. A map from user ID, to a map from
                     device ID to algorithm name. Requested users must be local
                     to the receiving homeserver.
-                  additionalProperties:
-                    type: object
-                    additionalProperties:
-                      type: string
-                      description: algorithm
-                      example: signed_curve25519
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: object
+                      additionalProperties:
+                        type: string
+                        description: algorithm
+                        example: signed_curve25519
                   example:
                     "@alice:example.com":
                       JLAFKJWSCS: signed_curve25519
@@ -65,35 +67,37 @@ paths:
                       See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
                       the Key Object format.
                     # User
-                    additionalProperties:
-                      type: object
-                      # Device
-                      additionalProperties:
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
                         type: object
-                        # Key
+                        # Device
                         additionalProperties:
-                          oneOf:
-                            - type: string
-                            - type: object
-                              title: KeyObject
-                              properties:
-                                key:
-                                  type: string
-                                  description: The key, encoded using unpadded base64.
-                                signatures:
-                                  type: object
-                                  title: Signatures
-                                  additionalProperties:
+                          type: object
+                          # Key
+                          additionalProperties:
+                            oneOf:
+                              - type: string
+                              - type: object
+                                title: KeyObject
+                                properties:
+                                  key:
+                                    type: string
+                                    description: The key, encoded using unpadded base64.
+                                  signatures:
                                     type: object
+                                    title: Signatures
                                     additionalProperties:
-                                      type: string
-                                  description: |-
-                                    Signature of the key object.
+                                      type: object
+                                      additionalProperties:
+                                        type: string
+                                    description: |-
+                                      Signature of the key object.
 
-                                    The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-                              required:
-                                - key
-                                - signatures
+                                      The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
+                                required:
+                                  - key
+                                  - signatures
                     example:
                       "@alice:example.com":
                         JLAFKJWSCS:
@@ -124,11 +128,13 @@ paths:
                     device IDs, or to an empty list to indicate all devices for the
                     corresponding user.  Requested users must be local to the
                     receiving homeserver.
-                  additionalProperties:
-                    type: array
-                    items:
-                      type: string
-                      description: Device ID
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: array
+                      items:
+                        type: string
+                        description: Device ID
                   example:
                     "@alice:example.com": []
               required:
@@ -150,23 +156,25 @@ paths:
                       the information returned will be the same as uploaded via
                       `/keys/upload`, with the addition of an `unsigned`
                       property.
-                    additionalProperties:
-                      type: object
-                      additionalProperties:
-                        allOf:
-                          - $ref: ../client-server/definitions/device_keys.yaml
-                        properties:
-                          unsigned:
-                            title: UnsignedDeviceInfo
-                            type: object
-                            description: |-
-                              Additional data added to the device key information
-                              by intermediate servers, and not covered by the
-                              signatures.
-                            properties:
-                              device_display_name:
-                                type: string
-                                description: The display name which the user set on the device.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        type: object
+                        additionalProperties:
+                          allOf:
+                            - $ref: ../client-server/definitions/device_keys.yaml
+                          properties:
+                            unsigned:
+                              title: UnsignedDeviceInfo
+                              type: object
+                              description: |-
+                                Additional data added to the device key information
+                                by intermediate servers, and not covered by the
+                                signatures.
+                              properties:
+                                device_display_name:
+                                  type: string
+                                  description: The display name which the user set on the device.
                   master_keys:
                     x-addedInMatrixVersion: "1.1"
                     type: object
@@ -177,8 +185,11 @@ paths:
                       `/keys/device_signing/upload`, along with the signatures
                       uploaded via `/keys/signatures/upload` that the user is
                       allowed to see.
-                    additionalProperties:
-                      $ref: ../client-server/definitions/cross_signing_key.yaml
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: ../client-server/definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
@@ -194,8 +205,11 @@ paths:
                       from user ID, to self-signing key information.  For each key, the
                       information returned will be the same as uploaded via
                       `/keys/device_signing/upload`.
-                    additionalProperties:
-                      $ref: ../client-server/definitions/cross_signing_key.yaml
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: ../client-server/definitions/cross_signing_key.yaml
                     example:
                       "@alice:example.com":
                         user_id: "@alice:example.com"
diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml
index 5da7e6ab..2075c146 100644
--- a/data/custom-formats.yaml
+++ b/data/custom-formats.yaml
@@ -32,6 +32,11 @@ mx-event-id:
   url: /appendices#event-ids
   # regex: "^\\$"
 
+mx-room-id:
+  title: Room ID
+  url: /appendices#room-ids
+  # regex: "^!"
+
 uri:
   title: URI
   url: http://tools.ietf.org/html/rfc3986
diff --git a/data/event-schemas/schema/m.direct.yaml b/data/event-schemas/schema/m.direct.yaml
index 3256b574..9b9e8251 100644
--- a/data/event-schemas/schema/m.direct.yaml
+++ b/data/event-schemas/schema/m.direct.yaml
@@ -9,10 +9,12 @@ description: |-
   that user ID.
 properties:
   content:
-    additionalProperties:
-      type: array
-      items:
-        type: string
+    patternProperties:
+      "^@":
+        x-pattern-format: mx-user-id
+        type: array
+        items:
+          type: string
     type: object
     description: |-
       The mapping of user ID to a list of room IDs of the 'direct' rooms for
diff --git a/data/event-schemas/schema/m.room.power_levels.yaml b/data/event-schemas/schema/m.room.power_levels.yaml
index f5f15fab..858c5274 100644
--- a/data/event-schemas/schema/m.room.power_levels.yaml
+++ b/data/event-schemas/schema/m.room.power_levels.yaml
@@ -67,8 +67,10 @@ properties:
             by the `events` key. Defaults to 50 if unspecified.
         type: integer
       users:
-        additionalProperties:
-          type: integer
+        patternProperties:
+          "^@":
+            x-pattern-format: mx-user-id
+            type: integer
         description: The power levels for specific users. This is a mapping from `user_id` to power level for that user.
         title: User power levels
         type: object

From dac867dd6a6272c4e781a89d583e6e33ba33eef9 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 14 May 2024 09:35:42 +0100
Subject: [PATCH 44/82] Rename "recovery key" to "backup decryption key"
 (#1819)

Also, some other editorial improvements, including factoring out our two definitions of the same key encoding algorithm.

Co-authored-by: Travis Ralston <travisr@matrix.org>
---
 .../newsfragments/1819.clarification          |  1 +
 .../newsfragments/1819.clarification          |  1 +
 content/appendices.md                         | 25 ++++++++++
 .../modules/end_to_end_encryption.md          | 49 ++++++++-----------
 content/client-server-api/modules/secrets.md  | 18 +------
 5 files changed, 50 insertions(+), 44 deletions(-)
 create mode 100644 changelogs/appendices/newsfragments/1819.clarification
 create mode 100644 changelogs/client_server/newsfragments/1819.clarification

diff --git a/changelogs/appendices/newsfragments/1819.clarification b/changelogs/appendices/newsfragments/1819.clarification
new file mode 100644
index 00000000..dafeb10f
--- /dev/null
+++ b/changelogs/appendices/newsfragments/1819.clarification
@@ -0,0 +1 @@
+Define common cryptographic key representation.
diff --git a/changelogs/client_server/newsfragments/1819.clarification b/changelogs/client_server/newsfragments/1819.clarification
new file mode 100644
index 00000000..f04c85d4
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1819.clarification
@@ -0,0 +1 @@
+Rename "recovery key" to "backup decryption key".
diff --git a/content/appendices.md b/content/appendices.md
index cdaf2629..8861bbe9 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -940,6 +940,31 @@ The acceptable character set matches the unreserved character set in [RFC
 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
 {{% /boxes/note %}}
 
+## Cryptographic key representation
+
+Sometimes it is necessary to present a private cryptographic key in the user
+interface.
+
+When this happens, the key SHOULD be presented as a string formatted as
+follows:
+
+1.  A byte array is created, consisting of two bytes `0x8B` and `0x01`,
+    followed by the raw key.
+2.  All the bytes in the array above, including the two header bytes,
+    are XORed together to form a parity byte. This parity byte is
+    appended to the byte array.
+3.  The byte array is encoded using base58, using the the alphabet
+    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
+4.  A space is added after every 4th character.
+
+When reading in a key, clients should disregard whitespace, and
+perform the reverse of steps 1 through 4.
+
+{{% boxes/note %}}
+The base58 alphabet is the same as that used for [Bitcoin
+addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index 6c3bbbea..f18cb9eb 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -674,7 +674,7 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
-    * Each of the keys that they wish the other user to verify (usually their 
+    * Each of the keys that they wish the other user to verify (usually their
       device ed25519 key and their master cross-signing key).
     * The complete list of key IDs that they wish the other user to verify.
 
@@ -1271,10 +1271,10 @@ tries to read a message that it does not have keys for, it may request
 the key from the server and decrypt it. Backups are per-user, and users
 may replace backups with new backups.
 
-In contrast with [Key requests](#key-requests), Server-side key backups
-do not require another device to be online from which to request keys.
-However, as the session keys are stored on the server encrypted, it
-requires users to enter a decryption key to decrypt the session keys.
+In contrast with [key requests](#key-requests), server-side key backups do not
+require another device to be online from which to request keys. However, as
+the session keys are stored on the server encrypted, the client requires a
+[decryption key](#decryption-key) to decrypt the session keys.
 
 To create a backup, a client will call [POST
 /\_matrix/client/v3/room\_keys/version](#post_matrixclientv3room_keysversion) and define how the keys are to
@@ -1295,7 +1295,7 @@ Clients must only store keys in backups after they have ensured that the
 
 - checking that it is signed by the user's [master cross-signing
   key](#cross-signing) or by a verified device belonging to the same user, or
-- by deriving the public key from a private key that it obtained from a trusted
+- deriving the public key from a private key that it obtained from a trusted
   source. Trusted sources for the private key include the user entering the
   key, retrieving the key stored in [secret storage](#secret-storage), or
   obtaining the key via [secret sharing](#sharing) from a verified device
@@ -1312,31 +1312,24 @@ replace it with the new key based on the key metadata as follows:
 -   and finally, if `is_verified` and `first_message_index` are equal,
     then it will keep the key with a lower `forwarded_count`.
 
-###### Recovery key
+###### Decryption key
 
-If the recovery key (the private half of the backup encryption key) is
-presented to the user to save, it is presented as a string constructed
-as follows:
+Normally, the decryption key (i.e. the secret part of the encryption key) is
+stored on the server or shared with other devices using the [Secrets](#secrets)
+module. When doing so, it is identified using the name `m.megolm_backup.v1`,
+and the key is base64-encoded before being encrypted.
 
-1.  The 256-bit curve25519 private key is prepended by the bytes `0x8B`
-    and `0x01`
-2.  All the bytes in the string above, including the two header bytes,
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  A space should be added after every 4th character.
+If the backup decryption key is given directly to the user, the key should be
+presented as a string using the common [cryptographic key
+representation](/appendices/#cryptographic-key-representation).
 
-When reading in a recovery key, clients must disregard whitespace, and
-perform the reverse of steps 1 through 3.
-
-The recovery key can also be stored on the server or shared with other devices
-using the [Secrets](#secrets) module. When doing so, it is identified using the
-name `m.megolm_backup.v1`, and the key is base64-encoded before being
-encrypted.
+{{% boxes/note %}}
+The backup decryption key was previously referred to as a "recovery
+key". However, this conflicted with common practice in client user
+interfaces, which often use the term "recovery key" to refer to the [secret
+storage](#storage) key. The term "recovery key" is no longer used in this
+specification.
+{{% /boxes/note %}}
 
 ###### Backup algorithm: `m.megolm_backup.v1.curve25519-aes-sha2`
 
diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md
index e94f361a..541ca877 100644
--- a/content/client-server-api/modules/secrets.md
+++ b/content/client-server-api/modules/secrets.md
@@ -262,22 +262,8 @@ For example, data encrypted using this algorithm could look like this:
 ##### Key representation
 
 When a user is given a raw key for `m.secret_storage.v1.aes-hmac-sha2`,
-it will be presented as a string constructed as follows:
-
-1.  The key is prepended by the two bytes `0x8b` and `0x01`
-2.  All the bytes in the string above, including the two header bytes,
-    are XORed together to form a parity byte. This parity byte is
-    appended to the byte string.
-3.  The byte string is encoded using base58, using the same [mapping as
-    is used for Bitcoin
-    addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
-    that is, using the alphabet
-    `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
-4.  The string is formatted into groups of four characters separated by
-    spaces.
-
-When decoding a raw key, the process should be reversed, with the
-exception that whitespace is insignificant in the user's input.
+the key should be presented as a string using the common [cryptographic key
+representation](/appendices/#cryptographic-key-representation).
 
 ##### Deriving keys from passphrases
 

From 041be547d610477772663aa262cc3b18a2a71265 Mon Sep 17 00:00:00 2001
From: Matthias Ahouansou <matthias@ahouansou.cz>
Date: Fri, 24 May 2024 17:43:33 +0100
Subject: [PATCH 45/82] Fix typo of object being spelt as "obiect" (#1827)

---
 changelogs/room_versions/newsfragments/1827.clarification | 1 +
 content/rooms/v10.md                                      | 2 +-
 content/rooms/v11.md                                      | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/room_versions/newsfragments/1827.clarification

diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification
new file mode 100644
index 00000000..c122052d
--- /dev/null
+++ b/changelogs/room_versions/newsfragments/1827.clarification
@@ -0,0 +1 @@
+Fix minor spelling mistake of object being spelt "obiect".
diff --git a/content/rooms/v10.md b/content/rooms/v10.md
index 1d366c8c..ea8c9c94 100644
--- a/content/rooms/v10.md
+++ b/content/rooms/v10.md
@@ -215,7 +215,7 @@ The rules are as follows:
         If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.
-    3.  If the `users` property in `content` is not an obiect with keys that
+    3.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers, reject.
     4.  If there is no previous `m.room.power_levels` event in the room,
         allow.
diff --git a/content/rooms/v11.md b/content/rooms/v11.md
index 5d44161c..6f5d772d 100644
--- a/content/rooms/v11.md
+++ b/content/rooms/v11.md
@@ -219,7 +219,7 @@ The rules are as follows:
     2.  If either of the properties `events` or `notifications` in `content`
         are present and not an object with values that are integers,
         reject.
-    3.  If the `users` property in `content` is not an obiect with keys that
+    3.  If the `users` property in `content` is not an object with keys that
         are valid user IDs with values that are integers, reject.
     4.  If there is no previous `m.room.power_levels` event in the room,
         allow.

From 3674985dd6d7d1c0d90b9fe4a7a81a1aa7b0384e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 28 May 2024 16:38:39 +0200
Subject: [PATCH 46/82] Factor out the common definitions of the content repo
 APIs and add new formats (#1822)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../newsfragments/1822.clarification          |   1 +
 data/api/client-server/content-repo.yaml      | 577 ++++++------------
 data/custom-formats.yaml                      |  10 +
 3 files changed, 212 insertions(+), 376 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1822.clarification

diff --git a/changelogs/client_server/newsfragments/1822.clarification b/changelogs/client_server/newsfragments/1822.clarification
new file mode 100644
index 00000000..034deb48
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1822.clarification
@@ -0,0 +1 @@
+Refactor the OpenAPI definitions of the content repository endpoints.
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index 8a4aa4f6..e6d55b51 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -25,24 +25,10 @@ paths:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
-        - in: header
-          name: Content-Type
-          description: The content type of the file being uploaded
-          example: application/pdf
-          schema:
-            type: string
-        - in: query
-          name: filename
-          description: The name of the file being uploaded
-          example: War and Peace.pdf
-          schema:
-            type: string
+        - $ref: '#/components/parameters/contentType'
+        - $ref: '#/components/parameters/filename'
       requestBody:
-        content:
-          application/octet-stream:
-            example: <bytes>
-        description: The content to be uploaded.
-        required: true
+        $ref: '#/components/requestBodies/bytes'
       responses:
         "200":
           description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
@@ -56,7 +42,8 @@ paths:
                 properties:
                   content_uri:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
+                    pattern: "^mxc:\\/\\/"
                     description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
                       the uploaded content.
               examples:
@@ -81,23 +68,9 @@ paths:
                     "error": "Cannot upload this content"
                   }
         "413":
-          description: The uploaded content is too large for the server.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_TOO_LARGE",
-                    "error": "Cannot upload files larger than 100mb"
-                  }
+          $ref: '#/components/responses/uploadTooLarge'
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
       tags:
         - Media
   "/media/v3/upload/{serverName}/{mediaId}":
@@ -109,40 +82,16 @@ paths:
       operationId: uploadContentToMXC
       x-addedInMatrixVersion: "1.7"
       parameters:
-        - in: path
-          name: serverName
-          required: true
+        - $ref: '#/components/parameters/serverName'
           description: |
-            The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component).
-          example: matrix.org
-          schema:
-            type: string
-        - in: path
-          name: mediaId
-          required: true
+            The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authority component).
+        - $ref: '#/components/parameters/mediaId'
           description: |
             The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component).
-          example: ascERGshawAWawugaAcauga
-          schema:
-            type: string
-        - in: header
-          name: Content-Type
-          description: The content type of the file being uploaded
-          example: application/pdf
-          schema:
-            type: string
-        - in: query
-          name: filename
-          description: The name of the file being uploaded
-          example: War and Peace.pdf
-          schema:
-            type: string
+        - $ref: '#/components/parameters/contentType'
+        - $ref: '#/components/parameters/filename'
       requestBody:
-        content:
-          application/octet-stream:
-            example: <bytes>
-        description: The content to be uploaded.
-        required: true
+        $ref: '#/components/requestBodies/bytes'
       responses:
         "200":
           description: The upload was successful.
@@ -190,23 +139,9 @@ paths:
                     "error": "Media already uploaded"
                   }
         "413":
-          description: The uploaded content is too large for the server.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_TOO_LARGE",
-                    "error": "Cannot upload files larger than 100mb"
-                  }
+          $ref: '#/components/responses/uploadTooLarge'
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
       tags:
         - Media
   /media/v1/create:
@@ -251,7 +186,8 @@ paths:
                 properties:
                   content_uri:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
+                    pattern: "^mxc:\\/\\/"
                     description: |-
                       The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at
                       which the content will be available, once it is uploaded.
@@ -276,11 +212,7 @@ paths:
                     "error": "Cannot upload this content"
                   }
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
       tags:
         - Media
   "/media/v3/download/{serverName}/{mediaId}":
@@ -288,68 +220,17 @@ paths:
       summary: Download content from the content repository.
       operationId: getContent
       parameters:
-        - in: path
-          name: serverName
-          required: true
-          description: |
-            The server name from the `mxc://` URI (the authoritory component)
-          example: matrix.org
-          schema:
-            type: string
-        - in: path
-          name: mediaId
-          required: true
-          description: |
-            The media ID from the `mxc://` URI (the path component)
-          example: ascERGshawAWawugaAcauga
-          schema:
-            type: string
-        - in: query
-          name: allow_remote
-          required: false
-          description: |
-            Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to
-            true if not provided.
-          example: false
-          schema:
-            type: boolean
-            default: true
-        - in: query
-          name: timeout_ms
-          x-addedInMatrixVersion: "1.7"
-          description: |
-            The maximum number of milliseconds that the client is willing to
-            wait to start receiving data, in the case that the content has not
-            yet been uploaded. The default value is 20000 (20 seconds). The
-            content repository can and should impose a maximum value for this
-            parameter. The content repository may also choose to respond before
-            the timeout.
-          example: 5000
-          schema:
-            type: integer
-            format: int64
-            default: 20000
-        - in: query
-          name: allow_redirect
-          x-addedInMatrixVersion: "1.7"
-          required: false
-          description: |
-            Indicates to the server that it may return a 307 or 308 redirect response that points
-            at the relevant media content. When not explicitly set to true the server must return
-            the media content itself.
-          example: false
-          schema:
-            type: boolean
-            default: false
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
       responses:
         "200":
           description: The content that was previously uploaded.
           headers:
             Content-Type:
-              description: The content type of the file that was previously uploaded.
-              schema:
-                type: string
+              $ref: '#/components/headers/downloadContentType'
             Content-Disposition:
               description: The name of the file that was previously uploaded, if set.
               schema:
@@ -360,51 +241,15 @@ paths:
                 # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the uploaded file."
         "307":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/downloadRedirect'
         "308":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/downloadRedirect'
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
         "502":
-          description: The content is too large for the server to serve.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_TOO_LARGE",
-                    "error": "Content is too large to serve"
-                  }
+          $ref: '#/components/responses/downloadTooLarge'
         "504":
-          description: |-
-            The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
-            will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_YET_UPLOADED",
-                    "error": "Content has not yet been uploaded"
-                  }
+          $ref: '#/components/responses/notYetUploaded'
       tags:
         - Media
   "/media/v3/download/{serverName}/{mediaId}/{fileName}":
@@ -416,22 +261,8 @@ paths:
         provided by the caller.
       operationId: getContentOverrideName
       parameters:
-        - in: path
-          name: serverName
-          required: true
-          description: |
-            The server name from the `mxc://` URI (the authoritory component)
-          example: matrix.org
-          schema:
-            type: string
-        - in: path
-          name: mediaId
-          required: true
-          description: |
-            The media ID from the `mxc://` URI (the path component)
-          example: ascERGshawAWawugaAcauga
-          schema:
-            type: string
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
         - in: path
           name: fileName
           required: true
@@ -439,52 +270,15 @@ paths:
           example: filename.jpg
           schema:
             type: string
-        - in: query
-          name: allow_remote
-          required: false
-          description: |
-            Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to
-            true if not provided.
-          example: false
-          schema:
-            type: boolean
-            default: true
-        - in: query
-          name: timeout_ms
-          x-addedInMatrixVersion: "1.7"
-          description: |
-            The maximum number of milliseconds that the client is willing to
-            wait to start receiving data, in the case that the content has not
-            yet been uploaded. The default value is 20000 (20 seconds). The
-            content repository can and should impose a maximum value for this
-            parameter. The content repository may also choose to respond before
-            the timeout.
-          example: 5000
-          schema:
-            type: integer
-            format: int64
-            default: 20000
-        - in: query
-          name: allow_redirect
-          x-addedInMatrixVersion: "1.7"
-          required: false
-          description: |
-            Indicates to the server that it may return a 307 or 308 redirect response that points
-            at the relevant media content. When not explicitly set to true the server must return
-            the media content itself.
-          example: false
-          schema:
-            type: boolean
-            default: false
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
       responses:
         "200":
           description: The content that was previously uploaded.
           headers:
             Content-Type:
-              description: The content type of the file that was previously uploaded.
-              schema:
-                type: string
+              $ref: '#/components/headers/downloadContentType'
             Content-Disposition:
               description: |-
                 The `fileName` requested or the name of the file that was previously
@@ -497,51 +291,15 @@ paths:
                 # This is a workaround for us not being able to say the response is required.
                 description: "**Required.** The bytes for the uploaded file."
         "307":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/downloadRedirect'
         "308":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/downloadRedirect'
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
         "502":
-          description: The content is too large for the server to serve.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_TOO_LARGE",
-                    "error": "Content is too large to serve"
-                  }
+          $ref: '#/components/responses/downloadTooLarge'
         "504":
-          description: |-
-            The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
-            will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_YET_UPLOADED",
-                    "error": "Content has not yet been uploaded"
-                  }
+          $ref: '#/components/responses/notYetUploaded'
       tags:
         - Media
   "/media/v3/thumbnail/{serverName}/{mediaId}":
@@ -552,22 +310,8 @@ paths:
         See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
       operationId: getContentThumbnail
       parameters:
-        - in: path
-          name: serverName
-          required: true
-          description: |
-            The server name from the `mxc://` URI (the authoritory component)
-          example: example.org
-          schema:
-            type: string
-        - in: path
-          name: mediaId
-          required: true
-          description: |
-            The media ID from the `mxc://` URI (the path component)
-          example: ascERGshawAWawugaAcauga
-          schema:
-            type: string
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
         - in: query
           name: width
           required: true
@@ -597,44 +341,9 @@ paths:
             enum:
               - crop
               - scale
-        - in: query
-          name: allow_remote
-          required: false
-          description: |-
-            Indicates to the server that it should not attempt to fetch
-            the media if it is deemed remote. This is to prevent routing loops
-            where the server contacts itself. Defaults to true if not provided.
-          example: false
-          schema:
-            type: boolean
-            default: true
-        - in: query
-          name: timeout_ms
-          x-addedInMatrixVersion: "1.7"
-          description: |
-            The maximum number of milliseconds that the client is willing to
-            wait to start receiving data, in the case that the content has not
-            yet been uploaded. The default value is 20000 (20 seconds). The
-            content repository can and should impose a maximum value for this
-            parameter. The content repository may also choose to respond before
-            the timeout.
-          example: 5000
-          schema:
-            type: integer
-            format: int64
-            default: 20000
-        - in: query
-          name: allow_redirect
-          x-addedInMatrixVersion: "1.7"
-          required: false
-          description: |
-            Indicates to the server that it may return a 307 or 308 redirect response that points
-            at the relevant media content. When not explicitly set to true the server must return
-            the media content itself.
-          example: false
-          schema:
-            type: boolean
-            default: false
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
         - in: query
           name: animated
           x-addedInMatrixVersion: "1.11"
@@ -696,19 +405,9 @@ paths:
                 x-addedInMatrixVersion: "1.11"
                 description: "**Required.** The bytes for the *animated* thumbnail."
         "307":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/thumbnailRedirect'
         "308":
-          description: A redirect to the thumbnail of the requested content.
-          headers:
-            Location:
-              description: The URL of the thumbnail content.
-              schema:
-                type: string
+          $ref: '#/components/responses/thumbnailRedirect'
         "400":
           description: |-
             The request does not make sense to the server, or the server cannot thumbnail
@@ -737,11 +436,7 @@ paths:
                     "error": "Content is too large to thumbnail"
                   }
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
         "502":
           description: The remote content is too large for the server to thumbnail.
           content:
@@ -755,19 +450,7 @@ paths:
                     "error": "Content is too large to thumbnail"
                   }
         "504":
-          description: |-
-            The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
-            will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_NOT_YET_UPLOADED",
-                    "error": "Content has not yet been uploaded"
-                  }
+          $ref: '#/components/responses/notYetUploaded'
       tags:
         - Media
   /media/v3/preview_url:
@@ -837,11 +520,7 @@ paths:
                     "matrix:image:size": 102400
                   }
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          $ref: '#/components/responses/rateLimited'
       tags:
         - Media
   /media/v3/config:
@@ -883,11 +562,7 @@ paths:
                     "m.upload.size": 50000000
                   }
         "429":
-          description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
+          $ref: '#/components/responses/rateLimited'
       tags:
         - Media
 servers:
@@ -908,3 +583,153 @@ components:
       $ref: definitions/security.yaml#/accessTokenQuery
     accessTokenBearer:
       $ref: definitions/security.yaml#/accessTokenBearer
+  parameters:
+    contentType:
+      in: header
+      name: Content-Type
+      description: The content type of the file being uploaded
+      example: application/pdf
+      schema:
+        type: string
+    filename:
+      in: query
+      name: filename
+      description: The name of the file being uploaded
+      example: War and Peace.pdf
+      schema:
+        type: string
+    serverName:
+      in: path
+      name: serverName
+      required: true
+      description: |
+        The server name from the `mxc://` URI (the authority component).
+      example: matrix.org
+      schema:
+        type: string
+        format: mx-server-name
+    mediaId:
+      in: path
+      name: mediaId
+      required: true
+      description: |
+        The media ID from the `mxc://` URI (the path component).
+      example: ascERGshawAWawugaAcauga
+      schema:
+        type: string
+    allow_remote:
+      in: query
+      name: allow_remote
+      required: false
+      description: |-
+        Indicates to the server that it should not attempt to fetch the media if
+        it is deemed remote. This is to prevent routing loops where the server
+        contacts itself.
+        
+        Defaults to `true` if not provided.
+      example: false
+      schema:
+        type: boolean
+        default: true
+    timeout_ms:
+      in: query
+      name: timeout_ms
+      x-addedInMatrixVersion: "1.7"
+      description: |
+        The maximum number of milliseconds that the client is willing to wait to
+        start receiving data, in the case that the content has not yet been
+        uploaded. The default value is 20000 (20 seconds). The content
+        repository can and should impose a maximum value for this parameter. The
+        content repository may also choose to respond before the timeout.
+      example: 5000
+      schema:
+        type: integer
+        format: int64
+        default: 20000
+    allow_redirect:
+      in: query
+      name: allow_redirect
+      x-addedInMatrixVersion: "1.7"
+      required: false
+      description: |
+        Indicates to the server that it may return a 307 or 308 redirect
+        response that points at the relevant media content. When not explicitly
+        set to `true` the server must return the media content itself.
+      example: false
+      schema:
+        type: boolean
+        default: false
+  requestBodies:
+    bytes:
+      content:
+        application/octet-stream:
+          example: <bytes>
+      description: The content to be uploaded.
+      required: true
+  responses:
+    uploadTooLarge:
+      description: The uploaded content is too large for the server.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_TOO_LARGE",
+                "error": "Cannot upload files larger than 100mb"
+              }
+    rateLimited:
+      description: This request was rate-limited.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/rate_limited.yaml
+    notYetUploaded:
+      description: |-
+        The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
+        will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_NOT_YET_UPLOADED",
+                "error": "Content has not yet been uploaded"
+              }
+    downloadRedirect:
+      description: A redirect to the requested content.
+      headers:
+        Location:
+          description: The URL of the content.
+          schema:
+            type: string
+            format: uri
+    downloadTooLarge:
+      description: The content is too large for the server to serve.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_TOO_LARGE",
+                "error": "Content is too large to serve"
+              }
+    thumbnailRedirect:
+      description: A redirect to the thumbnail of the requested content.
+      headers:
+        Location:
+          description: The URL of the thumbnail content.
+          schema:
+            type: string
+            format: uri
+  headers:
+    downloadContentType:
+      description: The content type of the file that was previously uploaded.
+      schema:
+        type: string
+
diff --git a/data/custom-formats.yaml b/data/custom-formats.yaml
index 2075c146..7d52861f 100644
--- a/data/custom-formats.yaml
+++ b/data/custom-formats.yaml
@@ -37,6 +37,16 @@ mx-room-id:
   url: /appendices#room-ids
   # regex: "^!"
 
+mx-server-name:
+  title: Server Name
+  url: /appendices#server-name
+  # no regex
+
+mx-mxc-uri:
+  title: Matrix Content URI
+  url: /client-server-api#matrix-content-mxc-uris
+  # regex: "^mxc:\\/\\/"
+
 uri:
   title: URI
   url: http://tools.ietf.org/html/rfc3986

From 500e83b9b796c25a66fae94be19daa2ec7b9c9a9 Mon Sep 17 00:00:00 2001
From: Sumner Evans <me@sumnerevans.com>
Date: Tue, 28 May 2024 10:36:50 -0600
Subject: [PATCH 47/82] e2ee/qr: clarify that the device's Ed25519 signing key
 should be used (#1829)

Signed-off-by: Sumner Evans <sumner.evans@automattic.com>
---
 changelogs/client_server/newsfragments/1829.clarification  | 1 +
 content/client-server-api/modules/end_to_end_encryption.md | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1829.clarification

diff --git a/changelogs/client_server/newsfragments/1829.clarification b/changelogs/client_server/newsfragments/1829.clarification
new file mode 100644
index 00000000..68ce6207
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1829.clarification
@@ -0,0 +1 @@
+Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key).
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index f18cb9eb..1b3bd7b3 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -1197,11 +1197,12 @@ strings in the general form:
   - the ID as a UTF-8 string
 - the first key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00` or `0x01`, then the current user's own master cross-signing public key
-  - if `0x02`, then the current device's device key
+  - if `0x02`, then the current device's Ed25519 signing key
 - the second key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00`, then what the device thinks the other user's master
     cross-signing key is
-  - if `0x01`, then what the device thinks the other device's device key is
+  - if `0x01`, then what the device thinks the other device's Ed25519 signing
+    key is
   - if `0x02`, then what the device thinks the user's master cross-signing key
     is
 - a random shared secret, as a byte string.  It is suggested to use a secret

From ea781ef7b2c618ebc56124ebfbe867fc5c575d0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 28 May 2024 22:21:46 +0200
Subject: [PATCH 48/82] Spec markup for mathematical messages (#1816)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Spec markup for mathematical messages

As per MSC2191.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add warning box

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Improve warning

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add links

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../newsfragments/1816.clarification          |  1 +
 .../modules/instant_messaging.md              | 61 ++++++++++++++++++-
 2 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1816.clarification

diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.clarification
new file mode 100644
index 00000000..e1b97854
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1816.clarification
@@ -0,0 +1 @@
+Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191).
\ No newline at end of file
diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md
index 5f5f450f..e35a1cdf 100644
--- a/content/client-server-api/modules/instant_messaging.md
+++ b/content/client-server-api/modules/instant_messaging.md
@@ -73,11 +73,12 @@ the tag.
 
 | Tag    | Permitted Attributes                                                                                                                       |
 |--------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages))                                         |
+| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) |
 | `a`    | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) |
 | `img`  | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris))                      |
 | `ol`   | `start`                                                                                                                                    |
 | `code` | `class` (only classes which start with `language-` for syntax highlighting)                                                                |
+| `div` | `data-mx-maths` (see [mathematical messages](#mathematical-messages))                                                                      |
 
 Additionally, web clients should ensure that *all* `a` tags get a
 `rel="noopener"` to prevent the target page from referencing the
@@ -385,6 +386,64 @@ An example of a media message with a caption is:
 Clients MUST render the caption alongside the media and SHOULD prefer its
 formatted representation.
 
+##### Mathematical messages
+
+{{% added-in v="1.11" %}}
+
+Users might want to send mathematical notations in their messages.
+
+To send mathematical notations clients MUST use the `formatted_body` and
+therefore the `org.matrix.custom.html` format, described above. This makes
+mathematical notations valid on any `msgtype` which can support this format
+appropriately.
+
+Mathematical notations themselves use the `span` or `div` tags, depending
+whether the notation should be presented inline or not. The mathematical
+notation is written in [LaTeX](https://www.latex-project.org/) format using the
+`data-mx-maths` attribute.
+
+The contents of the tag should be a fallback representation for clients that
+cannot render the LaTeX format. The fallback representation could be, for
+example, an image, or an HTML approximation, or the raw LaTeX source. When using
+an image as a fallback, the sending client should be aware of issues that may
+arise from the receiving client using a different background colour. The `body`
+should include a textual representation of the notation.
+
+An example of a mathematical notation is:
+
+```json
+{
+  "msgtype": "m.text",
+  "format": "org.matrix.custom.html",
+  "body": "This is an equation: sin(x)=a/b.",
+  "formatted_body": "This is an equation:
+      <span data-mx-maths=\"\\sin(x)=\\frac{a}{b}\">
+        sin(<i>x</i>)=<sup><i>a</i></sup>/<sub><i>b</i></sub>
+      </span>"
+}
+```
+
+The LaTeX format is poorly defined and has several extensions, so if a client
+encounters syntax that it cannot render, it SHOULD present the fallback
+representation instead. Clients SHOULD, however, aim to support, at minimum, the
+basic [LaTeX2e](https://www.latex-project.org/) maths commands and the
+[TeX](https://tug.org/) maths commands, with the possible exception of commands
+that could be security risks.
+
+{{% boxes/warning %}}
+In general, LaTeX places a heavy burden on client authors to ensure that it is
+processed safely. Certain commands, such as [those that can create macros](https://katex.org/docs/supported#macros),
+are potentially dangerous. Clients should either decline to process those
+commands, or should take care to ensure that they are handled in safe ways (such
+as by limiting recursion). In general, LaTeX commands should be filtered by
+allowing known-good commands rather than forbidding known-bad commands.
+
+Therefore, clients should not render mathematics by calling a LaTeX compiler
+without proper sandboxing, as those executables were not written to handle
+untrusted input. Some LaTeX rendering libraries are better suited for that by
+allowing only a subset of LaTeX and enforcing recursion limits.
+{{% /boxes/warning %}}
+
 #### Server behaviour
 
 Homeservers SHOULD reject `m.room.message` events which don't have a

From 49765e0e0a82a13f29aca7f5ed0f94d9ed3ef362 Mon Sep 17 00:00:00 2001
From: Matthias Ahouansou <matthias@ahouansou.cz>
Date: Wed, 29 May 2024 09:42:19 +0100
Subject: [PATCH 49/82] Clarify that redaction events are subject to auth rules
 (#1824)

Signed-off-by: Matthias Ahouansou <matthias@ahouansou.cz>
---
 .../newsfragments/1824.clarification           |  1 +
 content/rooms/fragments/v8-auth-rules.md       | 18 ++++++++++++------
 content/rooms/v10.md                           | 18 ++++++++++++------
 content/rooms/v11.md                           | 18 ++++++++++++------
 content/rooms/v3.md                            | 17 +++++++++++------
 content/rooms/v6.md                            | 18 ++++++++++++------
 content/rooms/v7.md                            | 18 ++++++++++++------
 7 files changed, 72 insertions(+), 36 deletions(-)
 create mode 100644 changelogs/room_versions/newsfragments/1824.clarification

diff --git a/changelogs/room_versions/newsfragments/1824.clarification b/changelogs/room_versions/newsfragments/1824.clarification
new file mode 100644
index 00000000..6f830830
--- /dev/null
+++ b/changelogs/room_versions/newsfragments/1824.clarification
@@ -0,0 +1 @@
+Clarify that redaction events are still subject to all applicable auth rules.
diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md
index 3f1a4558..3571057e 100644
--- a/content/rooms/fragments/v8-auth-rules.md
+++ b/content/rooms/fragments/v8-auth-rules.md
@@ -1,12 +1,6 @@
 
 Events must be signed by the server denoted by the `sender` property.
 
-`m.room.redaction` events are not explicitly part of the auth rules.
-They are still subject to the minimum power level rules, but should always
-fall into "10. Otherwise, allow". Instead of being authorized at the time
-of receipt, they are authorized at a later stage: see the
-[Redactions](#redactions) section below for more information.
-
 The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
@@ -21,6 +15,18 @@ For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling Redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
 The rules are as follows:
 
 1.  If type is `m.room.create`:
diff --git a/content/rooms/v10.md b/content/rooms/v10.md
index ea8c9c94..8ec4832a 100644
--- a/content/rooms/v10.md
+++ b/content/rooms/v10.md
@@ -76,12 +76,6 @@ correctly structured are rejected under the authorization rules below.
 
 Events must be signed by the server denoted by the `sender` property.
 
-`m.room.redaction` events are not explicitly part of the auth rules.
-They are still subject to the minimum power level rules, but should always
-fall into "10. Otherwise, allow". Instead of being authorized at the time
-of receipt, they are authorized at a later stage: see the
-[Redactions](#redactions) section below for more information.
-
 The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
@@ -96,6 +90,18 @@ For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
 The rules are as follows:
 
 1.  If type is `m.room.create`:
diff --git a/content/rooms/v11.md b/content/rooms/v11.md
index 6f5d772d..782edb3e 100644
--- a/content/rooms/v11.md
+++ b/content/rooms/v11.md
@@ -83,12 +83,6 @@ such events over the Client-Server API.
 
 Events must be signed by the server denoted by the `sender` property.
 
-`m.room.redaction` events are not explicitly part of the auth rules.
-They are still subject to the minimum power level rules, but should always
-fall into "10. Otherwise, allow". Instead of being authorized at the time
-of receipt, they are authorized at a later stage: see the
-[Redactions](#redactions) section below for more information.
-
 The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
@@ -103,6 +97,18 @@ For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
 The rules are as follows:
 
 1.  {{< changed-in this="true" >}}
diff --git a/content/rooms/v3.md b/content/rooms/v3.md
index dd2fd144..ad9ff698 100644
--- a/content/rooms/v3.md
+++ b/content/rooms/v3.md
@@ -89,12 +89,17 @@ The complete structure of a event in a v3 room is shown below.
 
 ### Authorization rules
 
-{{< added-in this=true >}} `m.room.redaction` events are no longer
-explicitly part of the auth rules. They are still subject to the
-minimum power level rules, but should always fall into "11. Otherwise,
-allow". Instead of being authorized at the time of receipt, they are
-authorized at a later stage: see the [Handling Redactions](#handling-redactions)
-section below for more information.
+{{% boxes/note %}}
+{{< added-in this=true >}} `m.room.redaction` events are subject to auth rules in
+the same way as any other event. In practice, that means they will normally be allowed
+by the auth rules, unless the `m.room.power_levels` event sets a power level requirement
+for `m.room.redaction`events via the `events` or `events_default` properties. In
+particular, the _redact level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling Redactions](#handling-redactions) section.
+{{% /boxes/note %}}
 
 <!-- set withVersioning=true so we get all the "new in this version" stuff -->
 {{< rver-fragment name="v3-auth-rules" withVersioning=true >}}
diff --git a/content/rooms/v6.md b/content/rooms/v6.md
index b0309254..9761ffdb 100644
--- a/content/rooms/v6.md
+++ b/content/rooms/v6.md
@@ -40,12 +40,6 @@ in [room version 5](/rooms/v5).
 
 ### Authorization rules
 
-`m.room.redaction` events are not explicitly part of the auth rules.
-They are still subject to the minimum power level rules, but should always
-fall into "10. Otherwise, allow". Instead of being authorized at the time
-of receipt, they are authorized at a later stage: see the
-[Handling Redactions](#handling-redactions) section below for more information.
-
 {{< added-in this=true >}} Rule 4, which related specifically to events
 of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
 authorization checks relating to state events.
@@ -71,6 +65,18 @@ For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling Redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
 The rules are as follows:
 
 1.  If type is `m.room.create`:
diff --git a/content/rooms/v7.md b/content/rooms/v7.md
index eda351d0..b5c0f28a 100644
--- a/content/rooms/v7.md
+++ b/content/rooms/v7.md
@@ -37,12 +37,6 @@ new point for `membership=knock` is added.
 
 Events must be signed by the server denoted by the `sender` property.
 
-`m.room.redaction` events are not explicitly part of the auth rules.
-They are still subject to the minimum power level rules, but should always
-fall into "10. Otherwise, allow". Instead of being authorized at the time
-of receipt, they are authorized at a later stage: see the
-[Redactions](#redactions) section below for more information.
-
 The types of state events that affect authorization are:
 
 -   [`m.room.create`](/client-server-api#mroomcreate)
@@ -57,6 +51,18 @@ For example, mentions of the `sender`'s power level can also refer to
 the default power level for users in the room.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+`m.room.redaction` events are subject to auth rules in the same way as any other event.
+In practice, that means they will normally be allowed by the auth rules, unless the
+`m.room.power_levels` event sets a power level requirement for `m.room.redaction`
+events via the `events` or `events_default` properties. In particular, the _redact
+level_ is **not** considered by the auth rules.
+
+The ability to send a redaction event does not mean that the redaction itself should
+be performed. Receiving servers must perform additional checks, as described in
+the [Handling redactions](#handling-redactions) section.
+{{% /boxes/note %}}
+
 The rules are as follows:
 
 1.  If type is `m.room.create`:

From 722c2b1e9ad086f919d7c8710e3ae70f22d0b487 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 31 May 2024 10:02:04 +0100
Subject: [PATCH 50/82] Clean up pull request template (#1831)

As far as I can tell, these header files only encourage people to create
badly-formatted PRs.

Also we only have one template so let's give it the default name.
---
 .../spec-change.md => pull_request_template.md}           | 8 --------
 changelogs/internal/newsfragments/1831.clarification      | 1 +
 2 files changed, 1 insertion(+), 8 deletions(-)
 rename .github/{PULL_REQUEST_TEMPLATE/spec-change.md => pull_request_template.md} (74%)
 create mode 100644 changelogs/internal/newsfragments/1831.clarification

diff --git a/.github/PULL_REQUEST_TEMPLATE/spec-change.md b/.github/pull_request_template.md
similarity index 74%
rename from .github/PULL_REQUEST_TEMPLATE/spec-change.md
rename to .github/pull_request_template.md
index 362c6862..0f4d5ccc 100644
--- a/.github/PULL_REQUEST_TEMPLATE/spec-change.md
+++ b/.github/pull_request_template.md
@@ -1,11 +1,3 @@
----
-name: Spec clarification/not a proposal
-about: A change that's not a spec proposal, such as a clarification to the spec itself.
-title: ''
-labels: ''
-assignees: ''
-
----
 
 ### Pull Request Checklist
 
diff --git a/changelogs/internal/newsfragments/1831.clarification b/changelogs/internal/newsfragments/1831.clarification
new file mode 100644
index 00000000..8ce17713
--- /dev/null
+++ b/changelogs/internal/newsfragments/1831.clarification
@@ -0,0 +1 @@
+Clean up pull request template.

From a17550648cc4d96bf79ed21103fe30503e1a0fae Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Fri, 31 May 2024 12:12:31 +0200
Subject: [PATCH 51/82] Fix typo in moderation policy lists spec (#1832)

---
 changelogs/client_server/newsfragments/1832.clarification | 1 +
 content/client-server-api/modules/moderation_policies.md  | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1832.clarification

diff --git a/changelogs/client_server/newsfragments/1832.clarification b/changelogs/client_server/newsfragments/1832.clarification
new file mode 100644
index 00000000..3ccb2333
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1832.clarification
@@ -0,0 +1 @@
+Fix various typos throughout the specification.
diff --git a/content/client-server-api/modules/moderation_policies.md b/content/client-server-api/modules/moderation_policies.md
index 82a05963..2912d164 100644
--- a/content/client-server-api/modules/moderation_policies.md
+++ b/content/client-server-api/modules/moderation_policies.md
@@ -13,7 +13,7 @@ deciding what content is undesirable for any particular entity and
 should instead be empowering those entities to make their own decisions.
 As such, a generic framework for communicating "moderation policy lists"
 or "moderation policy rooms" is described. Note that this module only
-describes the data structures and not how they should be interpreting:
+describes the data structures and not how they should be interpreted:
 the entity making the decisions on filtering is best positioned to
 interpret the rules how it sees fit.
 

From 7ff785fc38d08c206afae79ec842a46b29eeced5 Mon Sep 17 00:00:00 2001
From: Matthias Ahouansou <matthias@ahouansou.cz>
Date: Mon, 3 Jun 2024 13:09:40 +0000
Subject: [PATCH 52/82] Clarify that the event field of the send_join is only
 required when performing a restricted join (#1834)

---
 changelogs/server_server/newsfragments/1834.clarification | 1 +
 data/api/server-server/joins-v2.yaml                      | 6 +++---
 2 files changed, 4 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1834.clarification

diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification
new file mode 100644
index 00000000..fa927cca
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1834.clarification
@@ -0,0 +1 @@
+Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request.
diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml
index 8dcdaaf0..7804a6f6 100644
--- a/data/api/server-server/joins-v2.yaml
+++ b/data/api/server-server/joins-v2.yaml
@@ -207,9 +207,9 @@ paths:
                     title: SignedMembershipEvent
                     x-addedInMatrixVersion: "1.2"
                     description: |-
-                      Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed
-                      copy of the membership event sent to other servers by the resident server, including the resident
-                      server's signature.
+                      Required if the `content` of the event in the request contained the `join_authorised_via_users_server`
+                        field. The signed copy of the membership event sent to other servers by the resident server,
+                        including the resident server's signature.
                   servers_in_room:
                     type: array
                     x-addedInMatrixVersion: "1.6"

From e15a36b0a1e69d40ffe1a1ebcdc5666b3a7236f0 Mon Sep 17 00:00:00 2001
From: Matthew Hodgson <matthew@matrix.org>
Date: Tue, 4 Jun 2024 16:20:23 +0100
Subject: [PATCH 53/82] MSC4132: deprecate linking to events in rooms
 identified by alias (#1823)

---
 .../appendices/newsfragments/1823.deprecation |  1 +
 content/appendices.md                         | 24 ++++++++++++++-----
 2 files changed, 19 insertions(+), 6 deletions(-)
 create mode 100644 changelogs/appendices/newsfragments/1823.deprecation

diff --git a/changelogs/appendices/newsfragments/1823.deprecation b/changelogs/appendices/newsfragments/1823.deprecation
new file mode 100644
index 00000000..968bdfe4
--- /dev/null
+++ b/changelogs/appendices/newsfragments/1823.deprecation
@@ -0,0 +1 @@
+Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132).
\ No newline at end of file
diff --git a/content/appendices.md b/content/appendices.md
index 8861bbe9..9c7cf82a 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -745,7 +745,7 @@ Specifically, the following mappings are used:
 * `r` for room aliases.
 * `u` for users.
 * `roomid` for room IDs (note the distinction from room aliases).
-* `e` for events, when after a room reference (`r` or `roomid`).
+* `e` for events, when after a room ID (`roomid`). Use of `e` after a room alias (`r`) is deprecated.
 
 {{% boxes/note %}}
 During development of this URI format, types of `user`, `room`, and `event`
@@ -755,6 +755,13 @@ wish to consider handling them as `u`, `r`, and `e` respectively.
 `roomid` was otherwise unchanged.
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{< changed-in v="1.11" >}}
+Referencing event IDs within a room identified by room alias (`r`) rather than room ID
+(`roomid`) is now deprecated.  We are not aware of these ever having been used in
+practice, and are nonsensical given room aliases are mutable.
+{{% /boxes/note %}}
+
 The `id without sigil` is simply the identifier for the entity without the defined
 sigil. For example, `!room:example.org` becomes `room:example.org` (`!` is the sigil
 for room IDs). The sigils are described under the
@@ -799,7 +806,6 @@ Examples of common URIs are:
 <!-- Author's note: These examples should be consistent with the matrix.to counterparts. -->
 * Link to `#somewhere:example.org`: `matrix:r/somewhere:example.org`
 * Link to `!somewhere:example.org`: `matrix:roomid/somewhere:example.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `matrix:r/somewhere:example.org/e/event`
 * Link to `$event` in `!somewhere:example.org`: `matrix:roomid/somewhere:example.org/e/event?via=elsewhere.ca`
 * Link to chat with `@alice:example.org`: `matrix:u/alice:example.org?action=chat`
 
@@ -809,9 +815,9 @@ A suggested client implementation algorithm is available in the
 #### matrix.to navigation
 
 {{% boxes/note %}}
-This namespacing existed prior to a `matrix:` scheme. This is **not**
-meant to be interpreted as an available web service - see below for more
-details.
+matrix.to is a Namespace URI which existed prior to a `matrix:` URI scheme.
+This is **not** meant to be interpreted as an available web service - see
+below for more details.
 {{% /boxes/note %}}
 
 A matrix.to URI has the following format, based upon the specification
@@ -843,10 +849,16 @@ Examples of matrix.to URIs are:
 <!-- Author's note: These examples should be consistent with the matrix scheme counterparts. -->
 * Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere%3Aexample.org`
 * Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org?via=elsewhere.ca`
-* Link to `$event` in `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
 * Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
 * Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
 
+{{% boxes/note %}}
+{{< changed-in v="1.11" >}}
+Referencing event IDs within a room identified by room alias rather than room ID
+is now deprecated.  We are not aware of these ever having been used in
+practice, and are nonsensical given room aliases are mutable.
+{{% /boxes/note %}}
+
 {{% boxes/note %}}
 Historically, clients have not produced URIs which are fully encoded.
 Clients should try to interpret these cases to the best of their

From 1e303b3bbcf46a0be692265d31f4ab6158c6a760 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Thu, 6 Jun 2024 12:06:32 +0200
Subject: [PATCH 54/82] Do not require UIA when first uploading cross-signing
 keys (#1828)

As per MSC3967.
---
 .../client_server/newsfragments/1828.feature      |  1 +
 data/api/client-server/cross_signing.yaml         | 15 +++++++++++++++
 2 files changed, 16 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1828.feature

diff --git a/changelogs/client_server/newsfragments/1828.feature b/changelogs/client_server/newsfragments/1828.feature
new file mode 100644
index 00000000..65d7420b
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1828.feature
@@ -0,0 +1 @@
+Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967).
diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml
index 0f3a46be..8f499d23 100644
--- a/data/api/client-server/cross_signing.yaml
+++ b/data/api/client-server/cross_signing.yaml
@@ -19,11 +19,26 @@ paths:
   /keys/device_signing/upload:
     post:
       x-addedInMatrixVersion: "1.1"
+      x-changedInMatrixVersion:
+        "1.11": UIA is not always required for this endpoint.
       summary: Upload cross-signing keys.
       description: |-
         Publishes cross-signing keys for the user.
 
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+        
+        User-Interactive Authentication MUST be performed, except in these cases:
+        - there is no existing cross-signing master key uploaded to the homeserver, OR
+        - there is an existing cross-signing master key and it exactly matches the
+          cross-signing master key provided in the request body. If there are any additional
+          keys provided in the request (self-signing key, user-signing key) they MUST also
+          match the existing keys stored on the server. In other words, the request contains
+          no new keys.
+        
+        This allows clients to freely upload one set of keys, but not modify/overwrite keys if
+        they already exist. Allowing clients to upload the same set of keys more than once 
+        makes this endpoint idempotent in the case where the response is lost over the network,
+        which would otherwise cause a UIA challenge upon retry.
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

From 5a86e384dd94298764fa36d5a6b52b12ce5f9cdc Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Fri, 7 Jun 2024 10:34:34 +0200
Subject: [PATCH 55/82] Clarify that per-request UIA for /login/get_token is an
 RFC 2119 MUST requirement (#1846)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/client_server/newsfragments/1846.clarification | 1 +
 data/api/client-server/login_token.yaml                   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1846.clarification

diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification
new file mode 100644
index 00000000..6f57eb35
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1846.clarification
@@ -0,0 +1 @@
+Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement.
diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml
index a8ab1248..19fa350e 100644
--- a/data/api/client-server/login_token.yaml
+++ b/data/api/client-server/login_token.yaml
@@ -45,7 +45,7 @@ paths:
         intend to log in multiple devices must generate a token for each.
 
         With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt
-        for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt
+        for verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt
         the user for verification to ensure explicit consent is gained for each additional client.
 
         Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum

From 7d5b5065557ab4f5c964a20126f76d34aedc1122 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Fri, 7 Jun 2024 18:13:32 +0200
Subject: [PATCH 56/82] Remove extra preposition in room version 11 description
 of redactions (#1848)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/room_versions/newsfragments/1848.clarification | 1 +
 content/rooms/v11.md                                      | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/room_versions/newsfragments/1848.clarification

diff --git a/changelogs/room_versions/newsfragments/1848.clarification b/changelogs/room_versions/newsfragments/1848.clarification
new file mode 100644
index 00000000..3ccb2333
--- /dev/null
+++ b/changelogs/room_versions/newsfragments/1848.clarification
@@ -0,0 +1 @@
+Fix various typos throughout the specification.
diff --git a/content/rooms/v11.md b/content/rooms/v11.md
index 782edb3e..d21c76ba 100644
--- a/content/rooms/v11.md
+++ b/content/rooms/v11.md
@@ -72,7 +72,7 @@ The `redacts` property of `m.room.redaction` events is moved from a top-level
 event property to a property under the event `content`.
 
 For backwards-compatibility with older clients, servers should add a `redacts` property
-to the top level of `m.room.redaction` events in when serving such events over the
+to the top level of `m.room.redaction` events when serving such events over the
 Client-Server API.
 
 For improved compatibility with newer clients, servers should add a `redacts` property

From 1b40a7789b4a28857fd53d19bf43914091b2de24 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Mon, 10 Jun 2024 13:26:50 +0200
Subject: [PATCH 57/82] Fix typos around relations recursion (#1853)

---
 changelogs/client_server/newsfragments/1853.clarification | 1 +
 content/client-server-api/_index.md                       | 2 +-
 data/api/client-server/relations.yaml                     | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1853.clarification

diff --git a/changelogs/client_server/newsfragments/1853.clarification b/changelogs/client_server/newsfragments/1853.clarification
new file mode 100644
index 00000000..3ccb2333
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1853.clarification
@@ -0,0 +1 @@
+Fix various typos throughout the specification.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index b0ce7289..71f92bec 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2316,7 +2316,7 @@ following endpoint.
 This endpoint is particularly useful if the client has lost context on the aggregation for
 a parent event and needs to rebuild/verify it.
 
-When using the `recurse` parameter, note that there no way for a client to
+When using the `recurse` parameter, note that there is no way for a client to
 control how far the server recurses. If the client decides that the server's
 recursion level is insufficient, it could, for example, perform the recursion
 itself, or disable whatever feature requires more recursion.
diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml
index b033e88f..3f3d5baa 100644
--- a/data/api/client-server/relations.yaml
+++ b/data/api/client-server/relations.yaml
@@ -312,7 +312,7 @@ components:
         Whether to additionally include events which only relate indirectly to the
         given event, i.e. events related to the given event via two or more direct relationships.
 
-        If set to `false`, only events which have direct a relation with the given
+        If set to `false`, only events which have a direct relation with the given
         event will be included.
 
         If set to `true`, all events which relate to the given event, or relate to

From 96057638ce7e7bbde97fec6373d703b5ebe1dff9 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Mon, 10 Jun 2024 13:17:27 +0100
Subject: [PATCH 58/82] Spec `unsigned.membership` property, per MSC4115
 (#1847)

---
 .../client_server/newsfragments/1847.feature  |  1 +
 .../client_event_without_room_id.yaml         | 21 +++++++++++++++++++
 .../examples/core/room_event.json             |  3 ++-
 3 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1847.feature

diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature
new file mode 100644
index 00000000..25d1914b
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1847.feature
@@ -0,0 +1 @@
+Add the new `unsigned.membership` property to events served over the client-server API, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115).
diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml
index d78dcc68..b12611a2 100644
--- a/data/api/client-server/definitions/client_event_without_room_id.yaml
+++ b/data/api/client-server/definitions/client_event_without_room_id.yaml
@@ -90,6 +90,7 @@ properties:
           "origin_server_ts": 1632491098485,
           "unsigned": {
             "age": 1257,
+            "membership": "leave"
           }
         }
       transaction_id:
@@ -112,3 +113,23 @@ properties:
             this.
         title: EventContent
         type: object
+      membership:
+        description: |
+          The room membership of the user making the request, at the time of the event.
+
+          This property is the value of the `membership` property of the
+          requesting user's [`m.room.member`](/client-server-api#mroommember)
+          state at the point of the event, including any changes caused by the
+          event. If the user had yet to join the room at the time of the event
+          (i.e, they have no `m.room.member` state), this property is set to
+          `leave`.
+
+          Homeservers SHOULD populate this property
+          wherever practical, but they MAY omit it if necessary (for example,
+          if calculating the value is expensive, servers might choose to only
+          implement it in encrypted rooms). The property is *not* normally populated
+          in events pushed to application services via the application service transaction API
+          (where there is no clear definition of "requesting user").
+        type: string
+        example: join
+        x-addedInMatrixVersion: "1.11"
diff --git a/data/event-schemas/examples/core/room_event.json b/data/event-schemas/examples/core/room_event.json
index 521225cc..9bd62e28 100644
--- a/data/event-schemas/examples/core/room_event.json
+++ b/data/event-schemas/examples/core/room_event.json
@@ -5,6 +5,7 @@
     "sender": "@example:example.org",
     "origin_server_ts": 1432735824653,
     "unsigned": {
-      "age": 1234
+      "age": 1234,
+      "membership": "join"
     }
 }

From 57042769819f1fad921f54a8f0cd9ebb112ebb9c Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 10 Jun 2024 12:15:01 -0600
Subject: [PATCH 59/82] Fix issue template for releases

---
 .github/ISSUE_TEMPLATE/release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md
index e46834b9..9093b17c 100644
--- a/.github/ISSUE_TEMPLATE/release.md
+++ b/.github/ISSUE_TEMPLATE/release.md
@@ -1,6 +1,6 @@
 ---
 name: [SCT] Release checklist
-about: Used by the Spec Core Team to create a new release.
+description: Used by the Spec Core Team to create a new release.
 title: 'Matrix 1.X'
 labels: 'release-blocker'
 assignees: ''

From 0a9ab956bdd65606e4aa70e887144deade27dcd3 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 10 Jun 2024 12:16:14 -0600
Subject: [PATCH 60/82] Revert "Fix issue template for releases"

This reverts commit 57042769819f1fad921f54a8f0cd9ebb112ebb9c.
---
 .github/ISSUE_TEMPLATE/release.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md
index 9093b17c..e46834b9 100644
--- a/.github/ISSUE_TEMPLATE/release.md
+++ b/.github/ISSUE_TEMPLATE/release.md
@@ -1,6 +1,6 @@
 ---
 name: [SCT] Release checklist
-description: Used by the Spec Core Team to create a new release.
+about: Used by the Spec Core Team to create a new release.
 title: 'Matrix 1.X'
 labels: 'release-blocker'
 assignees: ''

From 08bc8e8a1f1f12290324e534a920fff054a449d4 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Mon, 10 Jun 2024 12:40:31 -0600
Subject: [PATCH 61/82] Fix YAML syntax in SCT release template (#1856)

* Fix YAML syntax in SCT release template

* changelog
---
 .github/ISSUE_TEMPLATE/release.md                    | 4 ++--
 changelogs/internal/newsfragments/1856.clarification | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1856.clarification

diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md
index e46834b9..4128bb9b 100644
--- a/.github/ISSUE_TEMPLATE/release.md
+++ b/.github/ISSUE_TEMPLATE/release.md
@@ -1,6 +1,6 @@
 ---
-name: [SCT] Release checklist
-about: Used by the Spec Core Team to create a new release.
+name: '[SCT] Release checklist'
+about: 'Used by the Spec Core Team to create a new release.'
 title: 'Matrix 1.X'
 labels: 'release-blocker'
 assignees: ''
diff --git a/changelogs/internal/newsfragments/1856.clarification b/changelogs/internal/newsfragments/1856.clarification
new file mode 100644
index 00000000..838b8af5
--- /dev/null
+++ b/changelogs/internal/newsfragments/1856.clarification
@@ -0,0 +1 @@
+Fix syntax errors in the spec release issue template.
\ No newline at end of file

From 2f528029c9ff77367b84afa7fce8aa0e3582e3af Mon Sep 17 00:00:00 2001
From: reivilibre <olivier@librepush.net>
Date: Tue, 11 Jun 2024 15:22:12 +0100
Subject: [PATCH 62/82] Note that /logout doesn't take a body (#1644)

---
 .../client_server/newsfragments/1644.clarification  |  1 +
 content/client-server-api/_index.md                 | 13 ++++++++++---
 2 files changed, 11 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1644.clarification

diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification
new file mode 100644
index 00000000..78c0919d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1644.clarification
@@ -0,0 +1 @@
+Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 71f92bec..9a6c6a68 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -22,13 +22,20 @@ recommended outside test environments.
 Clients are authenticated using opaque `access_token` strings (see [Client
 Authentication](#client-authentication) for details).
 
-All `POST` and `PUT` endpoints, with the exception of [`POST
-/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT
-/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
+All `POST` and `PUT` endpoints, with the exception of those listed below,
 require the client to supply a request body containing a (potentially empty)
 JSON object.  Clients should supply a `Content-Type` header of
 `application/json` for all requests with JSON bodies, but this is not required.
 
+The exceptions are:
+
+- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and 
+  [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
+  both of which take the uploaded media as the request body.
+- [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and
+  [`POST /_matrix/client/v3/logout/all`](#post_matrixclientv3logoutall),
+  which take an empty request body.
+
 Similarly, all endpoints require the server to return a JSON object,
 with the exception of 200 responses to
 [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid)

From c4b4c896b74a13b0eb0782e7de175f578a9dfe72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 11 Jun 2024 17:59:29 +0200
Subject: [PATCH 63/82] Replace references to RFC7235 and RFC7230 with
 references to RFC9110 (#1844)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../server_server/newsfragments/1844.clarification    |  1 +
 content/server-server-api.md                          | 11 +++++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1844.clarification

diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification
new file mode 100644
index 00000000..81013eb6
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1844.clarification
@@ -0,0 +1 @@
+Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110.
\ No newline at end of file
diff --git a/content/server-server-api.md b/content/server-server-api.md
index e92d871c..365613df 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -349,14 +349,14 @@ def authorization_headers(origin_name, origin_signing_key,
 ```
 
 The format of the Authorization header is given in
-[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In
+[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In
 summary, the header begins with authorization scheme `X-Matrix`, followed by one
 or more spaces, followed by a comma-separated list of parameters written as
 name=value pairs. Zero or more spaces and tabs around each comma are allowed.
 The names are case insensitive and order does not matter. The
 values must be enclosed in quotes if they contain characters that are not
 allowed in `token`s, as defined in
-[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a
+[Section 5.6.2 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2); if a
 value is a valid `token`, it may or may not be enclosed in quotes. Quoted
 values may include backslash-escaped characters. When parsing the header, the
 recipient must unescape the characters. That is, a backslash-character pair is
@@ -388,6 +388,13 @@ The authorization parameters to include are:
 
 Unknown parameters are ignored.
 
+{{% boxes/note %}}
+{{< changed-in v="1.11" >}}
+This section used to reference [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1)
+and [RFC 7230](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2), that
+were obsoleted by RFC 9110 without changes to the sections of interest here.
+{{% /boxes/note %}}
+
 ### Response Authentication
 
 Responses are authenticated by the TLS server certificate. A homeserver

From acec09f567a7bef7e3ac09df15b13f7ce2c920b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 11 Jun 2024 18:03:53 +0200
Subject: [PATCH 64/82] Do not add empty arrays to examples (#1849)

---
 changelogs/internal/newsfragments/1849.clarification | 1 +
 layouts/partials/json-schema/resolve-example.html    | 6 +++---
 2 files changed, 4 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1849.clarification

diff --git a/changelogs/internal/newsfragments/1849.clarification b/changelogs/internal/newsfragments/1849.clarification
new file mode 100644
index 00000000..fc7c5d88
--- /dev/null
+++ b/changelogs/internal/newsfragments/1849.clarification
@@ -0,0 +1 @@
+Do not add empty arrays to examples.
diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html
index 09b4254e..8fa98400 100644
--- a/layouts/partials/json-schema/resolve-example.html
+++ b/layouts/partials/json-schema/resolve-example.html
@@ -35,9 +35,9 @@
         */}}
         {{ if reflect.IsMap $this_object.items }}
             {{ $items_example := partial "json-schema/resolve-example" $this_object.items }}
-            {{ $example = slice $items_example }}
-        {{ else }}
-            {{ $example = slice }}
+            {{ if $items_example }}
+                {{ $example = slice $items_example }}
+            {{ end }}
         {{ end }}
     {{ end }}
 

From a7a7eadf2cad1dbe72f41488b3f9bfcb08ea1c37 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 11 Jun 2024 13:02:46 -0400
Subject: [PATCH 65/82] Clarify when an event is returned from /send_join.
 (#1840)

---
 changelogs/server_server/newsfragments/1834.clarification | 2 +-
 changelogs/server_server/newsfragments/1840.clarification | 1 +
 data/api/server-server/joins-v2.yaml                      | 6 +++---
 3 files changed, 5 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1840.clarification

diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification
index fa927cca..80c2fa48 100644
--- a/changelogs/server_server/newsfragments/1834.clarification
+++ b/changelogs/server_server/newsfragments/1834.clarification
@@ -1 +1 @@
-Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request.
+Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server.
diff --git a/changelogs/server_server/newsfragments/1840.clarification b/changelogs/server_server/newsfragments/1840.clarification
new file mode 100644
index 00000000..80c2fa48
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1840.clarification
@@ -0,0 +1 @@
+Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server.
diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml
index 7804a6f6..465207e9 100644
--- a/data/api/server-server/joins-v2.yaml
+++ b/data/api/server-server/joins-v2.yaml
@@ -207,9 +207,9 @@ paths:
                     title: SignedMembershipEvent
                     x-addedInMatrixVersion: "1.2"
                     description: |-
-                      Required if the `content` of the event in the request contained the `join_authorised_via_users_server`
-                        field. The signed copy of the membership event sent to other servers by the resident server,
-                        including the resident server's signature.
+                      The membership event sent to other servers by the resident server including a signature
+                      from the resident server. Required if the room is [restricted](/client-server-api/#restricted-rooms)
+                      and the joining user is authorised by one of the conditions.
                   servers_in_room:
                     type: array
                     x-addedInMatrixVersion: "1.6"

From 784b8984f36aa3d0317471d858ccbc875a78893e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 11 Jun 2024 23:24:23 +0200
Subject: [PATCH 66/82] Generate ToC with Hugo rather than JavaScript (#1851)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .github/workflows/main.yml                    |   2 +-
 .htmltest.yaml                                |   1 +
 README.md                                     |   2 +-
 .../internal/newsfragments/1851.clarification |   1 +
 config.toml                                   |   6 +-
 content/client-server-api/_index.md           |  78 ++++----
 layouts/partials/sidebar-tree.html            |  83 +++++++++
 layouts/partials/toc.html                     |  15 ++
 layouts/shortcodes/changelog/changelogs.html  |   2 +-
 layouts/shortcodes/cs-module.html             |   2 +-
 static/js/toc.js                              | 170 ------------------
 11 files changed, 148 insertions(+), 214 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1851.clarification
 create mode 100644 layouts/partials/sidebar-tree.html
 create mode 100644 layouts/partials/toc.html

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 09a184a7..cb14a0c1 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -193,7 +193,7 @@ jobs:
       - name: "➕ Setup Hugo"
         uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
         with:
-          hugo-version: '0.113.0'
+          hugo-version: '0.117.0'
           extended: true
       - name: "📥 Source checkout"
         uses: actions/checkout@v4
diff --git a/.htmltest.yaml b/.htmltest.yaml
index 1563408b..52eedee5 100644
--- a/.htmltest.yaml
+++ b/.htmltest.yaml
@@ -4,3 +4,4 @@
 IgnoreDirectoryMissingTrailingSlash: true
 DirectoryPath: spec
 CheckExternal: false
+IgnoreInternalEmptyHash: true
diff --git a/README.md b/README.md
index 17fa5614..a0ba854e 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
 
 1. Install the extended version (often the OS default) of Hugo:
    <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.113.0 is required.
+   v0.117.0 is required.
 
    Alternatively, use the Docker image at
    https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification
new file mode 100644
index 00000000..e89777c5
--- /dev/null
+++ b/changelogs/internal/newsfragments/1851.clarification
@@ -0,0 +1 @@
+Generate ToC with Hugo rather than JavaScript.
diff --git a/config.toml b/config.toml
index a4245d0b..15003eee 100644
--- a/config.toml
+++ b/config.toml
@@ -37,6 +37,10 @@ description = "Home of the Matrix specification for decentralised communication"
     weight = 30
 
 [markup]
+  [markup.tableOfContents]
+    startLevel = 2
+    endLevel = 6
+    ordered = true
   [markup.goldmark]
     [markup.goldmark.renderer]
       # Enables us to render raw HTML
@@ -130,7 +134,7 @@ sidebar_menu_compact = true
 [module]
   [module.hugoVersion]
     extended = true
-    min = "0.113.0"
+    min = "0.117.0"
   [[module.imports]]
     path = "github.com/matrix-org/docsy"
     disable = false
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 9a6c6a68..86dcda1a 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2812,42 +2812,42 @@ operations and run in a resource constrained environment. Like embedded
 applications, they are not intended to be fully-fledged communication
 systems.
 
-{{< cs-module name="instant_messaging" >}}
-{{< cs-module name="rich_replies" >}}
-{{< cs-module name="voip_events" >}}
-{{< cs-module name="typing_notifications" >}}
-{{< cs-module name="receipts" >}}
-{{< cs-module name="read_markers" >}}
-{{< cs-module name="presence" >}}
-{{< cs-module name="content_repo" >}}
-{{< cs-module name="send_to_device" >}}
-{{< cs-module name="device_management" >}}
-{{< cs-module name="end_to_end_encryption" >}}
-{{< cs-module name="secrets" >}}
-{{< cs-module name="history_visibility" >}}
-{{< cs-module name="push" >}}
-{{< cs-module name="third_party_invites" >}}
-{{< cs-module name="search" >}}
-{{< cs-module name="guest_access" >}}
-{{< cs-module name="room_previews" >}}
-{{< cs-module name="tags" >}}
-{{< cs-module name="account_data" >}}
-{{< cs-module name="admin" >}}
-{{< cs-module name="event_context" >}}
-{{< cs-module name="sso_login" >}}
-{{< cs-module name="dm" >}}
-{{< cs-module name="ignore_users" >}}
-{{< cs-module name="stickers" >}}
-{{< cs-module name="report_content" >}}
-{{< cs-module name="third_party_networks" >}}
-{{< cs-module name="openid" >}}
-{{< cs-module name="server_acls" >}}
-{{< cs-module name="mentions" >}}
-{{< cs-module name="room_upgrades" >}}
-{{< cs-module name="server_notices" >}}
-{{< cs-module name="moderation_policies" >}}
-{{< cs-module name="spaces" >}}
-{{< cs-module name="event_replacements" >}}
-{{< cs-module name="event_annotations" >}}
-{{< cs-module name="threading" >}}
-{{< cs-module name="reference_relations" >}}
+{{% cs-module name="instant_messaging" %}}
+{{% cs-module name="rich_replies" %}}
+{{% cs-module name="voip_events" %}}
+{{% cs-module name="typing_notifications" %}}
+{{% cs-module name="receipts" %}}
+{{% cs-module name="read_markers" %}}
+{{% cs-module name="presence" %}}
+{{% cs-module name="content_repo" %}}
+{{% cs-module name="send_to_device" %}}
+{{% cs-module name="device_management" %}}
+{{% cs-module name="end_to_end_encryption" %}}
+{{% cs-module name="secrets" %}}
+{{% cs-module name="history_visibility" %}}
+{{% cs-module name="push" %}}
+{{% cs-module name="third_party_invites" %}}
+{{% cs-module name="search" %}}
+{{% cs-module name="guest_access" %}}
+{{% cs-module name="room_previews" %}}
+{{% cs-module name="tags" %}}
+{{% cs-module name="account_data" %}}
+{{% cs-module name="admin" %}}
+{{% cs-module name="event_context" %}}
+{{% cs-module name="sso_login" %}}
+{{% cs-module name="dm" %}}
+{{% cs-module name="ignore_users" %}}
+{{% cs-module name="stickers" %}}
+{{% cs-module name="report_content" %}}
+{{% cs-module name="third_party_networks" %}}
+{{% cs-module name="openid" %}}
+{{% cs-module name="server_acls" %}}
+{{% cs-module name="mentions" %}}
+{{% cs-module name="room_upgrades" %}}
+{{% cs-module name="server_notices" %}}
+{{% cs-module name="moderation_policies" %}}
+{{% cs-module name="spaces" %}}
+{{% cs-module name="event_replacements" %}}
+{{% cs-module name="event_annotations" %}}
+{{% cs-module name="threading" %}}
+{{% cs-module name="reference_relations" %}}
diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html
new file mode 100644
index 00000000..f5a34b23
--- /dev/null
+++ b/layouts/partials/sidebar-tree.html
@@ -0,0 +1,83 @@
+{{/*
+
+  A modified version of the siderbar-tree.html partial in Docsy, adding:
+  
+  * The "toc.html" partial at L45.
+
+*/}}
+
+{{/* We cache this partial for bigger sites and set the active class client side. */ -}}
+{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}}
+{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}}
+<div id="td-sidebar-menu" class="td-sidebar__inner{{ if $shouldDelayActive }} d-none{{ end }}">
+  {{ if not .Site.Params.ui.sidebar_search_disable -}}
+  <form class="td-sidebar__search d-flex align-items-center">
+    {{ partial "search-input.html" . }}
+    <button class="btn btn-link td-sidebar__toggle d-md-none p-0 ms-3 fas fa-bars" type="button" data-bs-toggle="collapse" data-bs-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    </button>
+  </form>
+  {{ else -}}
+  <div id="content-mobile">
+  <form class="td-sidebar__search d-flex align-items-center">
+    {{ partial "search-input.html" . }}
+    <button class="btn btn-link td-sidebar__toggle d-md-none p-0 ms-3 fas fa-bars" type="button" data-bs-toggle="collapse" data-bs-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
+    </button>
+  </form>
+  </div>
+  <div id="content-desktop"></div>
+  {{ end -}}
+  <nav class="td-sidebar-nav collapse
+      {{- if .Site.Params.ui.sidebar_search_disable }} td-sidebar-nav--search-disabled{{ end -}}
+      {{- if .Site.Params.ui.sidebar_menu_foldable }} foldable-nav{{ end -}}
+      " id="td-section-nav">
+    {{ if  (gt (len .Site.Home.Translations) 0) -}}
+    <div class="td-sidebar-nav__section nav-item dropdown d-block d-lg-none">
+      {{ partial "navbar-lang-selector.html" . }}
+    </div>
+    {{ end -}}
+    {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}}
+    {{ $ulNr := 0 -}}
+    {{ $ulShow := .Site.Params.ui.ul_show | default 1 -}}
+    {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 50 -}}
+    <ul class="td-sidebar-nav__section pe-md-3 ul-{{ $ulNr }}">
+      {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1)) }}
+    </ul>
+    {{ partial "toc.html" . }}
+  </nav>
+</div>
+{{ define "section-tree-nav-section" -}}
+{{ $s := .section -}}
+{{ $p := .page -}}
+{{ $shouldDelayActive := .shouldDelayActive -}}
+{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}}
+{{ $treeRoot := cond (eq .ulNr 0) true false -}}
+{{ $ulNr := .ulNr -}}
+{{ $ulShow := .ulShow -}}
+{{ $active := and (not $shouldDelayActive) (eq $s $p) -}}
+{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}}
+{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}}
+{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
+{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
+{{ $pages := $pages_tmp | first $sidebarMenuTruncate -}}
+{{ $withChild := gt (len $pages) 0 -}}
+{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}}
+{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}}
+<li class="td-sidebar-nav__section-title td-sidebar-nav__section{{ if $withChild }} with-child{{ else }} without-child{{ end }}{{ if $activePath }} active-path{{ end }}{{ if (not (or $show $p.Site.Params.ui.sidebar_menu_foldable )) }} collapse{{ end }}" id="{{ $mid }}-li">
+  {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}
+  <input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
+  <label for="{{ $mid }}-check"><a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left ps-0 {{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a></label>
+  {{ else -}}
+  <a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left ps-0{{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a>
+  {{- end }}
+  {{- if $withChild }}
+  {{- $ulNr := add $ulNr 1 }}
+  <ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
+    {{ range $pages -}}
+    {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}}
+    {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }}
+    {{- end }}
+    {{- end }}
+  </ul>
+  {{- end }}
+</li>
+{{- end }}
\ No newline at end of file
diff --git a/layouts/partials/toc.html b/layouts/partials/toc.html
new file mode 100644
index 00000000..318335f2
--- /dev/null
+++ b/layouts/partials/toc.html
@@ -0,0 +1,15 @@
+{{/*
+
+  A modified version of the toc.html partial in Docsy.
+
+*/}}
+{{ $page := .Params }}
+{{ if not .Params.notoc -}}
+  {{ with .TableOfContents -}}
+    <hr>
+    <div id="toc">
+        <a id="toc-title" href="#">{{ $page.Title }}</a>
+        {{ . }}
+    </div>
+  {{ end -}}
+{{ end -}}
diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html
index 78b5932f..f42963da 100644
--- a/layouts/shortcodes/changelog/changelogs.html
+++ b/layouts/shortcodes/changelog/changelogs.html
@@ -5,6 +5,6 @@
 
 {{ with .Page.Resources.Match "*.md" }}
 {{ range ((sort . "Params.date" "desc")) }}
-{{ .Content }}
+{{ .RenderShortcodes }}
 {{ end }}
 {{ end }}
diff --git a/layouts/shortcodes/cs-module.html b/layouts/shortcodes/cs-module.html
index 475ebd48..52c9a5d9 100644
--- a/layouts/shortcodes/cs-module.html
+++ b/layouts/shortcodes/cs-module.html
@@ -11,6 +11,6 @@
 
 {{ with .Site.GetPage "client-server-api/modules" }}
     {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
-{{ .Content }}
+{{ .RenderShortcodes }}
     {{ end }}
 {{ end }}
diff --git a/static/js/toc.js b/static/js/toc.js
index 6386e40d..786ec6c6 100644
--- a/static/js/toc.js
+++ b/static/js/toc.js
@@ -14,174 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-/*
-Account for id attributes that are in the sidebar nav
-*/
-function populateIds() {
-  const navItems = document.querySelectorAll(".td-sidebar-nav li");
-  return Array.from(navItems).map(item => item.id).filter(id => id != "");
-}
-
-/*
-Given an ID and an array of IDs, return s version of the original ID that's
-not equal to any of the IDs in the array.
-*/
-function uniquifyHeadingId(id, uniqueIDs) {
-  const baseId = id;
-  let counter = 0;
-  while (uniqueIDs.includes(id)) {
-    counter = counter + 1;
-    id = baseId + "-" + counter.toString();
-  }
-  return id;
-}
-
-/*
-Given an array of heading nodes, ensure they all have unique IDs.
-
-We have to do this mostly because of client-server modules, which are
-rendered separately then glued together with a template.
-Because heading IDs are generated in rendering, this means they can and will
-end up with duplicate IDs.
-*/
-function uniquifyHeadingIds(headings) {
-  const uniqueIDs = populateIds();
-  for (let heading of headings) {
-    const uniqueID = uniquifyHeadingId(heading.id, uniqueIDs);
-    uniqueIDs.push(uniqueID);
-    heading.id = uniqueID;
-  }
-}
-
-/*
-The document contains "normal" headings, and these have corresponding items
-in the ToC.
-
-The document might also contain H1 headings that act as titles for blocks of
-rendered data, like HTTP APIs or event schemas. Unlike "normal" headings,
-these headings don't appear in the ToC. But they do have anchor IDs to enable
-links to them. When someone follows a link to one of these "rendered data"
-headings we want to scroll the ToC to the item corresponding to the "normal"
-heading preceding the "rendered data" heading we have visited.
-
-To support this we need to add `data` attributes to ToC items.
-These attributes identify which "rendered data" headings live underneath
-the heading corresponding to that ToC item.
-*/
-function setTocItemChildren(toc, headings) {
-  let tocEntryForHeading  = null;
-  for (const heading of headings) {
-    // H1 headings are rendered-data headings
-    if (heading.tagName !== "H1") {
-      tocEntryForHeading = document.querySelector(`nav li a[href="#${heading.id}"]`);
-    } else {
-      // on the ToC entry for the parent heading,
-      // set a data-* attribute whose name is the child's fragment ID
-      tocEntryForHeading.setAttribute(`data-${heading.id}`, "true");
-    }
-  }
-}
-
-/*
-Generate a table of contents based on the headings in the document.
-*/
-function makeToc() {
-
-  // make the title from the H1
-  const h1 = document.body.querySelector("h1");
-  const title = document.createElement("a");
-  title.id = "toc-title";
-  title.setAttribute("href", "#");
-  title.textContent = h1.textContent;
-
-  // make the content
-  const content = document.body.querySelector(".td-content");
-  let headings = [].slice.call(content.querySelectorAll("h2, h3, h4, h5, h6, .rendered-data > details > summary > h1"));
-
-  // exclude headings that don't have IDs.
-  headings = headings.filter(heading => heading.id);
-  uniquifyHeadingIds(headings);
-
-  // exclude .rendered-data > h1 headings from the ToC
-  const tocTargets = headings.filter(heading => heading.tagName !== "H1");
-
-  // we have to adjust heading IDs to ensure that they are unique
-  const nav = document.createElement("nav");
-  nav.id = "TableOfContents";
-
-  const section = makeTocSection(tocTargets, 0);
-  nav.appendChild(section.content);
-  // build the TOC and append to it title and content
-  const toc = document.createElement("div");
-  toc.id = "toc";
-  toc.appendChild(title);
-  toc.appendChild(nav);
-
-  // append TOC to the section navigation
-  const section_nav = document.body.querySelector("#td-section-nav");
-  let hr = document.createElement("hr");
-  section_nav.appendChild(hr);
-  section_nav.appendChild(toc);
-
-  // tell ToC items about any rendered-data headings they contain
-  setTocItemChildren(section.content, headings);
-}
-
-// create a single ToC entry
-function makeTocEntry(heading) {
-  const li = document.createElement("li");
-  const a = document.createElement("a");
-  a.setAttribute("href", `#${heading.id}`);
-  a.textContent = heading.textContent;
-  li.appendChild(a);
-  return li;
-}
-
-/*
-Each ToC section is an `<ol>` element.
-ToC entries are `<li>` elements and these contain nested ToC sections,
-whenever we go to the next heading level down.
-*/
-function makeTocSection(headings, index) {
-  const ol = document.createElement("ol");
-  let previousHeading = null;
-  let previousLi = null;
-  let i = index;
-  const lis = [];
-  for (i; i < headings.length; i++) {
-    const thisHeading = headings[i];
-    if (previousHeading && (thisHeading.tagName > previousHeading.tagName)) {
-      // we are going down a heading level, create a new nested section
-      const section = makeTocSection(headings, i);
-      previousLi.appendChild(section.content);
-      i = section.index -1;
-    }
-    else if (previousHeading && (previousHeading.tagName > thisHeading.tagName)) {
-      // we have come back up a level, so a section is finished
-      for (let li of lis) {
-        ol.appendChild(li);
-      }
-      return {
-        content: ol,
-        index: i
-      }
-    }
-    else {
-      // we are still processing this section, so add this heading to the current section
-      previousLi = makeTocEntry(thisHeading);
-      lis.push(previousLi);
-      previousHeading = thisHeading;
-    }
-  }
-  for (let li of lis) {
-    ol.appendChild(li);
-  }
-  return  {
-    content: ol,
-    index: i
-  }
-}
-
 /*
 Set a new ToC entry.
 Clear any previously highlighted ToC items, set the new one,
@@ -303,8 +135,6 @@ for the corresponding ToC entry.
 */
 window.addEventListener('DOMContentLoaded', () => {
 
-  makeToc();
-
   const toc = document.querySelector("#toc");
   toc.addEventListener("click", event => {
     if (event.target.tagName === "A") {

From 520b8398d86e8211f237ca0e8c0ef46915bdf9e3 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Tue, 11 Jun 2024 23:36:24 +0200
Subject: [PATCH 67/82] Add missing word header (#1852)

* Add missing word header

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

* Add changelog

---------

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/client_server/newsfragments/1852.clarification | 1 +
 content/client-server-api/_index.md                       | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1852.clarification

diff --git a/changelogs/client_server/newsfragments/1852.clarification b/changelogs/client_server/newsfragments/1852.clarification
new file mode 100644
index 00000000..3ccb2333
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1852.clarification
@@ -0,0 +1 @@
+Fix various typos throughout the specification.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 86dcda1a..126a5103 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -234,7 +234,7 @@ return a standard error response of the form:
 ```
 
 Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after)
-for any response with a 429 status code.
+header for any response with a 429 status code.
 
 The `retry_after_ms` property MAY be included to tell the client how long
 they have to wait in milliseconds before they can try again. This property is

From da3e884aaa388c246944262038f4229d2d354641 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 11 Jun 2024 17:42:46 -0400
Subject: [PATCH 68/82] Fix broken link to push rule condition kinds. (#1841)

---
 changelogs/client_server/newsfragments/1841.clarification | 1 +
 data/api/client-server/definitions/push_condition.yaml    | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1841.clarification

diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification
new file mode 100644
index 00000000..faf8aae9
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1841.clarification
@@ -0,0 +1 @@
+Fix broken link to push rule condition kinds.
diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml
index 4c35cfe4..1e7a8583 100644
--- a/data/api/client-server/definitions/push_condition.yaml
+++ b/data/api/client-server/definitions/push_condition.yaml
@@ -18,7 +18,7 @@ properties:
   kind:
     type: string
     description: |-
-      The kind of condition to apply. See [conditions](/client-server-api/#conditions) for
+      The kind of condition to apply. See [conditions](/client-server-api/#conditions-1) for
       more information on the allowed kinds and how they work.
   key:
     type: string

From 3517846916c83aac01bfcbfd763fd118230d4b87 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 12 Jun 2024 03:38:33 +0200
Subject: [PATCH 69/82] Add missing modules to feature profiles (#1860)

* Add missing modules to feature profiles

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

* Add changelog

---------

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/client_server/newsfragments/1860.clarification | 1 +
 content/client-server-api/_index.md                       | 3 +++
 2 files changed, 4 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1860.clarification

diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification
new file mode 100644
index 00000000..ca6e4117
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1860.clarification
@@ -0,0 +1 @@
+Add missing secrets, third-party invites and room tagging modules to feature profiles table.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 126a5103..851c64cb 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -2764,6 +2764,9 @@ that profile.
 | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional  | Optional | Optional | Optional | Optional |
 | [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
 | [Reference Relations](#reference-relations)                | Optional  | Optional | Optional | Optional | Optional |
+| [Secrets](#secrets)                                        | Optional  | Optional | Optional | Optional | Optional |
+| [Third-party Invites](#third-party-invites)                | Optional  | Required | Optional | Optional | Optional |
+| [Room Tagging](#room-tagging)                              | Optional  | Optional | Optional | Optional | Optional |
 
 *Please see each module for more details on what clients need to
 implement.*

From 7916032a787b4e7bbbb163ff9da2fb5d965514d2 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Wed, 12 Jun 2024 10:11:07 +0200
Subject: [PATCH 70/82] Move size limits for user, room and event IDs into the
 appendix and clarify that the length is to be measured in bytes (#1850)

Fixes: #1826
Relates to: #1001
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 .../appendices/newsfragments/1850.clarification     |  1 +
 .../client_server/newsfragments/1850.clarification  |  1 +
 content/appendices.md                               | 13 +++++++++----
 content/client-server-api/_index.md                 |  9 ++++-----
 4 files changed, 15 insertions(+), 9 deletions(-)
 create mode 100644 changelogs/appendices/newsfragments/1850.clarification
 create mode 100644 changelogs/client_server/newsfragments/1850.clarification

diff --git a/changelogs/appendices/newsfragments/1850.clarification b/changelogs/appendices/newsfragments/1850.clarification
new file mode 100644
index 00000000..cc200bdf
--- /dev/null
+++ b/changelogs/appendices/newsfragments/1850.clarification
@@ -0,0 +1 @@
+Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes.
diff --git a/changelogs/client_server/newsfragments/1850.clarification b/changelogs/client_server/newsfragments/1850.clarification
new file mode 100644
index 00000000..cc200bdf
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1850.clarification
@@ -0,0 +1 @@
+Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes.
diff --git a/content/appendices.md b/content/appendices.md
index 9c7cf82a..f9dbb455 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -556,7 +556,7 @@ The `domain` of a user ID is the [server name](#server-name) of the
 homeserver which allocated the account.
 
 The length of a user ID, including the `@` sigil and the domain, MUST
-NOT exceed 255 characters.
+NOT exceed 255 bytes.
 
 The complete grammar for a legal user ID is:
 
@@ -663,6 +663,9 @@ Room IDs are case-sensitive. They are not meant to be
 human-readable. They are intended to be treated as fully opaque strings
 by clients.
 
+The length of a room ID, including the `!` sigil and the domain, MUST
+NOT exceed 255 bytes.
+
 #### Room Aliases
 
 A room may have zero or more aliases. A room alias has the format:
@@ -673,8 +676,8 @@ The `domain` of a room alias is the [server name](#server-name) of the
 homeserver which created the alias. Other servers may contact this
 homeserver to look up the alias.
 
-Room aliases MUST NOT exceed 255 bytes (including the `#` sigil and the
-domain).
+The length of a room alias, including the `#` sigil and the domain, MUST
+NOT exceed 255 bytes.
 
 #### Event IDs
 
@@ -686,10 +689,12 @@ However, the precise format depends upon the [room version
 specification](/rooms): early room versions included a `domain` component,
 whereas more recent versions omit the domain and use a base64-encoded hash instead.
 
+In addition to the requirements of the room version, the length of an event ID,
+including the `$` sigil and the domain where present, MUST NOT exceed 255 bytes.
+
 Event IDs are case-sensitive. They are not meant to be human-readable. They are
 intended to be treated as fully opaque strings by clients.
 
-
 ### URIs
 
 There are two major kinds of referring to a resource in Matrix: matrix.to
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 851c64cb..c2c01465 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -1849,16 +1849,15 @@ updates not being sent.
 
 The complete event MUST NOT be larger than 65536 bytes, when formatted
 with the [federation event format](#room-event-format), including any
-signatures, and encoded as [Canonical
-JSON](/appendices#canonical-json).
+signatures, and encoded as [Canonical JSON](/appendices#canonical-json).
 
 There are additional restrictions on sizes per key:
 
--   `sender` MUST NOT exceed 255 bytes (including domain).
--   `room_id` MUST NOT exceed 255 bytes.
+-   `sender` MUST NOT exceed the size limit for [user IDs](/appendices/#user-identifiers).
+-   `room_id` MUST NOT exceed the size limit for [room IDs](/appendices/#room-ids).
 -   `state_key` MUST NOT exceed 255 bytes.
 -   `type` MUST NOT exceed 255 bytes.
--   `event_id` MUST NOT exceed 255 bytes.
+-   `event_id` MUST NOT exceed the size limit for [event IDs](/appendices/#event-ids).
 
 Some event types have additional size restrictions which are specified
 in the description of the event. Additional keys have no limit other

From eb49b28ea9f0182931d5dab36492acff188a81e1 Mon Sep 17 00:00:00 2001
From: davidegirardi <16451191+davidegirardi@users.noreply.github.com>
Date: Wed, 12 Jun 2024 15:14:37 +0200
Subject: [PATCH 71/82] Use environment variables in workflow (#1865)

* Use environment variables in workflow

* Add newsfragment
---
 .github/workflows/netlify.yaml                       | 5 ++++-
 changelogs/internal/newsfragments/1865.clarification | 1 +
 2 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/internal/newsfragments/1865.clarification

diff --git a/.github/workflows/netlify.yaml b/.github/workflows/netlify.yaml
index 889d6eed..7c59f64c 100644
--- a/.github/workflows/netlify.yaml
+++ b/.github/workflows/netlify.yaml
@@ -25,8 +25,11 @@ jobs:
         id: readctx
         # we need to find the PR number that corresponds to the branch, which we do by
         # searching the GH API
+        env:
+          OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
         run: |
-          head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}'
+          head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}"
           echo "head branch: $head_branch"
           pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)"
           pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
diff --git a/changelogs/internal/newsfragments/1865.clarification b/changelogs/internal/newsfragments/1865.clarification
new file mode 100644
index 00000000..f50be96f
--- /dev/null
+++ b/changelogs/internal/newsfragments/1865.clarification
@@ -0,0 +1 @@
+Use environment variables for Netlify build job.

From cd8ce97563205ea950b67c95a22d860638205df7 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 12 Jun 2024 22:17:37 +0100
Subject: [PATCH 72/82] Minor clarifications to the "end-to-end encryption"
 module (#1863)

---
 changelogs/client_server/newsfragments/1863.clarification | 1 +
 .../client-server-api/modules/end_to_end_encryption.md    | 8 +++++---
 2 files changed, 6 insertions(+), 3 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1863.clarification

diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification
new file mode 100644
index 00000000..d054d41d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1863.clarification
@@ -0,0 +1 @@
+Minor clarifications to the "end-to-end encryption" module.
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index 1b3bd7b3..c3a801f9 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -1530,9 +1530,11 @@ 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` and the `ed25519` field value
-under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for
-the given user, and must also verify the signature of the keys from the
+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

From 4a280bcd87ae233f0e4e923dea8d5fd1f4b5317e Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Wed, 12 Jun 2024 22:48:50 +0100
Subject: [PATCH 73/82] Clarifications around encoding of data within
 verification QR codes (#1839)

---
 .../newsfragments/1839.clarification          |  1 +
 .../modules/end_to_end_encryption.md          | 26 ++++++++++++-------
 2 files changed, 17 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1839.clarification

diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification
new file mode 100644
index 00000000..eea109b1
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1839.clarification
@@ -0,0 +1 @@
+Specify the encoding to be used when generating QR codes for device verification.
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index c3a801f9..5787205a 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -1179,10 +1179,16 @@ The process between Alice and Bob verifying each other would be:
 
 ###### QR code format
 
-The QR codes to be displayed and scanned using this format will encode binary
-strings in the general form:
+The QR codes to be displayed and scanned MUST be
+compatible with [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) and
+contain a single segment that uses the byte mode encoding.
 
-- the ASCII string `MATRIX`
+The error correction level can be chosen by the device displaying the QR code.
+
+The binary segment MUST be of the following form:
+
+- the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`,
+  `0x41`, `0x54`, `0x52`, `0x49`, `0x58`)
 - one byte indicating the QR code version (must be `0x02`)
 - one byte indicating the QR code verification mode.  Should be one of the
   following values:
@@ -1194,23 +1200,23 @@ strings in the general form:
   request event, encoded as:
   - two bytes in network byte order (big-endian) indicating the length in
     bytes of the ID as a UTF-8 string
-  - the ID as a UTF-8 string
+  - the ID encoded as a UTF-8 string
 - the first key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00` or `0x01`, then the current user's own master cross-signing public key
   - if `0x02`, then the current device's Ed25519 signing key
 - the second key, as 32 bytes.  The key to use depends on the mode field:
   - if `0x00`, then what the device thinks the other user's master
-    cross-signing key is
+    cross-signing public key is
   - if `0x01`, then what the device thinks the other device's Ed25519 signing
+    public key is
+  - if `0x02`, then what the device thinks the user's master cross-signing public
     key is
-  - if `0x02`, then what the device thinks the user's master cross-signing key
-    is
-- a random shared secret, as a byte string.  It is suggested to use a secret
+- a random shared secret, as a sequence of bytes.  It is suggested to use a secret
   that is about 8 bytes long.  Note: as we do not share the length of the
   secret, and it is not a fixed size, clients will just use the remainder of
-  binary string as the shared secret.
+  binary segment as the shared secret.
 
-For example, if Alice displays a QR code encoding the following binary string:
+For example, if Alice displays a QR code encoding the following binary data:
 
 ```
       "MATRIX"    |ver|mode| len   | event ID

From 7a51ae879c4c9274c638d19cd36eda630eb75e41 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 13 Jun 2024 12:08:27 -0600
Subject: [PATCH 74/82] Add authenticated media (MSC3916) (#1858)

* C2S: Deprecate now-legacy endpoints

* C2S: Fix MXC URI code block while we're here

* C2S: Describe the authentication and deprecation requirements

* C2S: Intro the upload/download endpoints differently

* C2S: Literally copy/paste the `content-repo.yaml` spec

* C2S: Drop `/upload` and `/create` because we aren't replacing them today

* C2S: Fix notes while we're here

* C2S: Update metadata for new endpoints

* C2S: Add authentication to new endpoints

* C2S: Drop `allow_remote` and `allow_redirect` on new endpoints

* C2S: Append backwards compatibility notes

* C2S: Decorate old media endpoints with pointers to the new ones

The server-server spec might have a harder time linking to these, but that can be fixed with verbiage.

* C2S: Annotate IdP icon spec with media auth implications

* S2S: Modernize section text

* S2S: Create content repository API

This is largely a copy/paste of the new authed content repo API in the Client-Server API, though some keywords (like "client") have been changed. Paths and response formats have also been changed to support the federation-specific requirements.

* C2S & S2S: Add plethora of changelogs

* Reference RFC 1341

* Upgrade keywords in changed text

* Mention caching

* Cross-reference IdP icons

* Update content/client-server-api/modules/content_repo.md
---
 .../newsfragments/1858.deprecation            |   1 +
 .../newsfragments/1858.feature.1              |   1 +
 .../newsfragments/1858.feature.2              |   1 +
 .../client_server/newsfragments/1858.new.1    |   1 +
 .../client_server/newsfragments/1858.new.2    |   1 +
 .../client_server/newsfragments/1858.new.3    |   1 +
 .../client_server/newsfragments/1858.new.4    |   1 +
 .../client_server/newsfragments/1858.new.5    |   1 +
 .../newsfragments/1858.deprecation            |   1 +
 .../server_server/newsfragments/1858.feature  |   1 +
 .../server_server/newsfragments/1858.new.1    |   1 +
 .../server_server/newsfragments/1858.new.2    |   1 +
 content/client-server-api/_index.md           |   5 +-
 .../client-server-api/modules/content_repo.md |  58 +-
 content/server-server-api.md                  |  23 +-
 .../client-server/authed-content-repo.yaml    | 518 ++++++++++++++++++
 data/api/client-server/content-repo.yaml      |  51 +-
 .../definitions/sso_login_flow.yaml           |  12 +
 .../api/server-server/content_repository.yaml | 303 ++++++++++
 19 files changed, 967 insertions(+), 15 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1858.deprecation
 create mode 100644 changelogs/client_server/newsfragments/1858.feature.1
 create mode 100644 changelogs/client_server/newsfragments/1858.feature.2
 create mode 100644 changelogs/client_server/newsfragments/1858.new.1
 create mode 100644 changelogs/client_server/newsfragments/1858.new.2
 create mode 100644 changelogs/client_server/newsfragments/1858.new.3
 create mode 100644 changelogs/client_server/newsfragments/1858.new.4
 create mode 100644 changelogs/client_server/newsfragments/1858.new.5
 create mode 100644 changelogs/server_server/newsfragments/1858.deprecation
 create mode 100644 changelogs/server_server/newsfragments/1858.feature
 create mode 100644 changelogs/server_server/newsfragments/1858.new.1
 create mode 100644 changelogs/server_server/newsfragments/1858.new.2
 create mode 100644 data/api/client-server/authed-content-repo.yaml
 create mode 100644 data/api/server-server/content_repository.yaml

diff --git a/changelogs/client_server/newsfragments/1858.deprecation b/changelogs/client_server/newsfragments/1858.deprecation
new file mode 100644
index 00000000..6e93dca5
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.deprecation
@@ -0,0 +1 @@
+Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.feature.1 b/changelogs/client_server/newsfragments/1858.feature.1
new file mode 100644
index 00000000..02b9b51e
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.feature.1
@@ -0,0 +1 @@
+Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.feature.2 b/changelogs/client_server/newsfragments/1858.feature.2
new file mode 100644
index 00000000..63dfbb78
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.feature.2
@@ -0,0 +1 @@
+Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.new.1 b/changelogs/client_server/newsfragments/1858.new.1
new file mode 100644
index 00000000..9d02447f
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.new.1
@@ -0,0 +1 @@
+[`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig)
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.new.2 b/changelogs/client_server/newsfragments/1858.new.2
new file mode 100644
index 00000000..07e7763a
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.new.2
@@ -0,0 +1 @@
+[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid)
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.new.3 b/changelogs/client_server/newsfragments/1858.new.3
new file mode 100644
index 00000000..49b67f04
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.new.3
@@ -0,0 +1 @@
+[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename)
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.new.4 b/changelogs/client_server/newsfragments/1858.new.4
new file mode 100644
index 00000000..dda53b33
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.new.4
@@ -0,0 +1 @@
+[`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url)
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1858.new.5 b/changelogs/client_server/newsfragments/1858.new.5
new file mode 100644
index 00000000..021b4023
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1858.new.5
@@ -0,0 +1 @@
+[`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid)
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1858.deprecation b/changelogs/server_server/newsfragments/1858.deprecation
new file mode 100644
index 00000000..fd3d2576
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1858.deprecation
@@ -0,0 +1 @@
+Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1858.feature b/changelogs/server_server/newsfragments/1858.feature
new file mode 100644
index 00000000..02b9b51e
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1858.feature
@@ -0,0 +1 @@
+Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916).
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1858.new.1 b/changelogs/server_server/newsfragments/1858.new.1
new file mode 100644
index 00000000..e50d5fd1
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1858.new.1
@@ -0,0 +1 @@
+[`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid)
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1858.new.2 b/changelogs/server_server/newsfragments/1858.new.2
new file mode 100644
index 00000000..1da2a693
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1858.new.2
@@ -0,0 +1 @@
+[`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid)
\ No newline at end of file
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index c2c01465..3e8a8670 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -37,9 +37,8 @@ The exceptions are:
   which take an empty request body.
 
 Similarly, all endpoints require the server to return a JSON object,
-with the exception of 200 responses to
-[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid)
-and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid).
+with the exception of 200 responses to the media download endpoints in the
+[Content Repository module](#content-repository).
 Servers must include a `Content-Type` header of `application/json` for all JSON responses.
 
 All JSON data, in requests or responses, must be encoded using UTF-8.
diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md
index cef70b3d..a0138156 100644
--- a/content/client-server-api/modules/content_repo.md
+++ b/content/client-server-api/modules/content_repo.md
@@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a
 interacting with the media repository.
 {{% /boxes/added-in-paragraph %}}
 
+{{% boxes/added-in-paragraph %}}
+{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been
+deprecated in favour of newer, authenticated, ones. This change includes updating
+the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`,
+with the exception of the `/upload` and `/create` endpoints. The upload/create
+endpoints are expected to undergo a similar transition in a later version of the
+specification.
+{{% /boxes/added-in-paragraph %}}
+
 #### Matrix Content (`mxc://`) URIs
 
 Content locations are represented as Matrix Content (`mxc://`) URIs. They
 look like:
 
-    mxc://<server-name>/<media-id>
+```
+mxc://<server-name>/<media-id>
 
-    <server-name> : The name of the homeserver where this content originated, e.g. matrix.org
-    <media-id> : An opaque ID which identifies the content.
+<server-name> : The name of the homeserver where this content originated, e.g. matrix.org
+<media-id> : An opaque ID which identifies the content.
+```
 
-#### Client behaviour
+#### Client behaviour {id="content-repo-client-behaviour"}
 
-Clients can upload and download content using the following HTTP APIs.
+Clients can access the content repository using the following endpoints.
+
+{{% boxes/added-in-paragraph %}}
+{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints
+described below. Instead, they SHOULD use the new endpoints which require authentication.
+{{% /boxes/added-in-paragraph %}}
+
+{{% boxes/warning %}}
+By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints
+to prevent newly-uploaded media from being downloaded. This SHOULD mean that any
+media uploaded *before* the freeze remains accessible via the deprecated endpoints,
+and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible
+through the new, authenticated, endpoints. For remote media, "newly-uploaded" is
+determined by the date the cache was populated. This may mean the media is older
+than the freeze, but because the server had to re-download it, it is now considered
+"new".
+
+Clients SHOULD update to support the authenticated endpoints before servers freeze
+unauthenticated access.
+
+Servers SHOULD consider their local ecosystem impact before enacting a freeze.
+This could mean ensuring their users' typical clients support the new endpoints
+when available, or updating bridges to start using media proxies.
+
+In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema)
+from the freeze. See the `m.login.sso` flow schema for details.
+
+An *example* timeline for a server may be:
+
+* Matrix 1.11 release: Clients begin supporting authenticated media.
+* Matrix 1.12 release: Servers freeze unauthenticated media access.
+  * Media uploaded prior to this point still works with the deprecated endpoints.
+  * Newly uploaded (or cached) media *only* works on the authenticated endpoints.
+
+Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter.
+{{% /boxes/warning %}}
+
+{{% http-api spec="client-server" api="authed-content-repo" %}}
 
 {{% http-api spec="client-server" api="content-repo" %}}
 
diff --git a/content/server-server-api.md b/content/server-server-api.md
index 365613df..9e92bfd9 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -1196,15 +1196,26 @@ using the following EDU:
 
 Attachments to events (images, files, etc) are uploaded to a homeserver
 via the Content Repository described in the [Client-Server
-API](/client-server-api). When a server wishes
+API](/client-server-api/#content-repository). When a server wishes
 to serve content originating from a remote server, it needs to ask the
 remote server for the media.
 
-Servers should use the server described in the Matrix Content URI, which
-has the format `mxc://{ServerName}/{MediaID}`. Servers should use the
-download endpoint described in the [Client-Server
-API](/client-server-api), being sure to use
-the `allow_remote` parameter (set to `false`).
+Servers MUST use the server described in the [Matrix Content URI](/client-server-api/#matrix-content-mxc-uris).
+Formatted as `mxc://{ServerName}/{MediaID}`, servers MUST download the media from
+`ServerName` using the below endpoints.
+
+{{% boxes/added-in-paragraph %}}
+{{< changed-in v="1.11" >}} Servers were previously advised to use the `/_matrix/media/*`
+endpoints described by the [Content Repository module in the Client-Server API](/client-server-api/#content-repository),
+however, those endpoints have been deprecated. New endpoints are introduced which
+require authentication. Naturally, as a server is not a user, they cannot provide
+the required access token to those endpoints. Instead, servers MUST try the endpoints
+described below before falling back to the deprecated `/_matrix/media/*` endpoints
+when they receive a `404 M_UNRECOGNIZED` error. When falling back, servers MUST
+be sure to set `allow_remote` to `false`.
+{{% /boxes/added-in-paragraph %}}
+
+{{% http-api spec="server-server" api="content_repository" %}}
 
 ## Server Access Control Lists (ACLs)
 
diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml
new file mode 100644
index 00000000..9741d618
--- /dev/null
+++ b/data/api/client-server/authed-content-repo.yaml
@@ -0,0 +1,518 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2019-2024 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 (Authenticated) Content Repository API
+  version: 1.0.0
+paths:
+  "/media/download/{serverName}/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download content from the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - $ref: '#/components/parameters/timeout_ms'
+      responses:
+        "200":
+          description: The content that was previously uploaded.
+          headers:
+            Content-Type:
+              $ref: '#/components/headers/downloadContentType'
+            Content-Disposition:
+              description: The name of the file that was previously uploaded, if set.
+              schema:
+                type: string
+          content:
+            application/octet-stream:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the uploaded file."
+        "307":
+          $ref: '#/components/responses/downloadRedirect'
+        "308":
+          $ref: '#/components/responses/downloadRedirect'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          $ref: '#/components/responses/downloadTooLarge'
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  "/media/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download content from the content repository overriding the file name.
+      description: |-
+        This will download content from the content repository (same as
+        the previous endpoint) but replaces the target file name with the one
+        provided by the caller.
+
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentOverrideNameAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - in: path
+          name: fileName
+          required: true
+          description: A filename to give in the `Content-Disposition` header.
+          example: filename.jpg
+          schema:
+            type: string
+        - $ref: '#/components/parameters/timeout_ms'
+      responses:
+        "200":
+          description: The content that was previously uploaded.
+          headers:
+            Content-Type:
+              $ref: '#/components/headers/downloadContentType'
+            Content-Disposition:
+              description: |-
+                The `fileName` requested or the name of the file that was previously
+                uploaded, if set.
+              schema:
+                type: string
+          content:
+            application/octet-stream:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the uploaded file."
+        "307":
+          $ref: '#/components/responses/downloadRedirect'
+        "308":
+          $ref: '#/components/responses/downloadRedirect'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          $ref: '#/components/responses/downloadTooLarge'
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  "/media/thumbnail/{serverName}/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download a thumbnail of content from the content repository
+      description: |-
+        Download a thumbnail of content from the content repository.
+        See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
+
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentThumbnailAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - in: query
+          name: width
+          required: true
+          description: |-
+            The *desired* width of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: height
+          required: true
+          description: |-
+            The *desired* height of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: method
+          description: |-
+            The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails)
+            section for more information.
+          example: scale
+          schema:
+            type: string
+            enum:
+              - crop
+              - scale
+        - $ref: '#/components/parameters/timeout_ms'
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server should behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: A thumbnail of the requested content.
+          headers:
+            Content-Type:
+              description: The content type of the thumbnail.
+              schema:
+                type: string
+                enum:
+                  - image/jpeg
+                  - image/png
+                  - image/apng
+                  - image/gif
+                  - image/webp
+          content:
+            image/jpeg:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the thumbnail."
+            image/png:
+              schema:
+                x-changedInMatrixVersion:
+                  "1.11": The PNG may be of the APNG variety if animation is supported and requested.
+                description: |
+                  **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
+                  format if `animated=true`.
+            image/apng:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/gif:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/webp:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+        "307":
+          $ref: '#/components/responses/thumbnailRedirect'
+        "308":
+          $ref: '#/components/responses/thumbnailRedirect'
+        "400":
+          description: |-
+            The request does not make sense to the server, or the server cannot thumbnail
+            the content. For example, the client requested non-integer dimensions or asked
+            for negatively-sized images.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "Cannot generate thumbnails for the requested content"
+                  }
+        "413":
+          description: The local content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          description: The remote content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  /media/preview_url:
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Get information about a URL for a client
+      description: |-
+        Get information about a URL for the client. Typically this is called when a
+        client sees a URL in a message and wants to render a preview for the user.
+
+        {{% boxes/note %}}
+        Clients should consider avoiding this endpoint for URLs posted in encrypted
+        rooms. Encrypted rooms often contain more sensitive information the users
+        do not want to share with the homeserver, and this can mean that the URLs
+        being shared should also not be shared with the homeserver.
+        {{% /boxes/note %}}
+      operationId: getUrlPreviewAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: url
+          description: The URL to get a preview of.
+          required: true
+          example: https://matrix.org
+          schema:
+            type: string
+            format: uri
+        - in: query
+          name: ts
+          description: |-
+            The preferred point in time to return a preview for. The server may
+            return a newer version if it does not have the requested version
+            available.
+          example: 1510610716656
+          schema:
+            type: integer
+            format: int64
+      responses:
+        "200":
+          description: |-
+            The OpenGraph data for the URL, which may be empty. Some values are
+            replaced with matrix equivalents if they are provided in the response.
+            The differences from the OpenGraph protocol are described here.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  matrix:image:size:
+                    type: integer
+                    format: int64
+                    description: The byte-size of the image. Omitted if there is no image attached.
+                  og:image:
+                    type: string
+                    format: uri
+                    description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
+                      the image. Omitted if there is no image.
+              examples:
+                response:
+                  value: {
+                    "og:title": "Matrix Blog Post",
+                    "og:description": "This is a really cool blog post from matrix.org",
+                    "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
+                    "og:image:type": "image/png",
+                    "og:image:height": 48,
+                    "og:image:width": 48,
+                    "matrix:image:size": 102400
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+  /media/config:
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Get the configuration for the content repository.
+      description: |-
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        {{% boxes/note %}}
+        Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+        {{% /boxes/note %}}
+      operationId: getConfigAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The public content repository configuration for the matrix server.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  m.upload.size:
+                    type: integer
+                    format: int64
+                    description: |-
+                      The maximum size an upload can be in bytes.
+                      Clients SHOULD use this as a guide when uploading content.
+                      If not listed or null, the size limit should be treated as unknown.
+              examples:
+                response:
+                  value: {
+                    "m.upload.size": 50000000
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+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
+  parameters:
+    serverName:
+      in: path
+      name: serverName
+      required: true
+      description: |
+        The server name from the `mxc://` URI (the authority component).
+      example: matrix.org
+      schema:
+        type: string
+        format: mx-server-name
+    mediaId:
+      in: path
+      name: mediaId
+      required: true
+      description: |
+        The media ID from the `mxc://` URI (the path component).
+      example: ascERGshawAWawugaAcauga
+      schema:
+        type: string
+    timeout_ms:
+      in: query
+      name: timeout_ms
+      x-addedInMatrixVersion: "1.7"
+      description: |
+        The maximum number of milliseconds that the client is willing to wait to
+        start receiving data, in the case that the content has not yet been
+        uploaded. The default value is 20000 (20 seconds). The content
+        repository can and should impose a maximum value for this parameter. The
+        content repository may also choose to respond before the timeout.
+      example: 5000
+      schema:
+        type: integer
+        format: int64
+        default: 20000
+  responses:
+    rateLimited:
+      description: This request was rate-limited.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/rate_limited.yaml
+    notYetUploaded:
+      description: |-
+        The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
+        will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_NOT_YET_UPLOADED",
+                "error": "Content has not yet been uploaded"
+              }
+    downloadRedirect:
+      description: A redirect to the requested content.
+      headers:
+        Location:
+          description: The URL of the content.
+          schema:
+            type: string
+            format: uri
+    downloadTooLarge:
+      description: The content is too large for the server to serve.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_TOO_LARGE",
+                "error": "Content is too large to serve"
+              }
+    thumbnailRedirect:
+      description: A redirect to the thumbnail of the requested content.
+      headers:
+        Location:
+          description: The URL of the thumbnail content.
+          schema:
+            type: string
+            format: uri
+  headers:
+    downloadContentType:
+      description: The content type of the file that was previously uploaded.
+      schema:
+        type: string
+
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index e6d55b51..1dac8b10 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -217,7 +217,20 @@ paths:
         - Media
   "/media/v3/download/{serverName}/{mediaId}":
     get:
+      deprecated: true
       summary: Download content from the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContent
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -254,11 +267,24 @@ paths:
         - Media
   "/media/v3/download/{serverName}/{mediaId}/{fileName}":
     get:
+      deprecated: true
       summary: Download content from the content repository overriding the file name
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename)
+        (requires authentication).
+        {{% /boxes/note %}}
+
         This will download content from the content repository (same as
         the previous endpoint) but replace the target file name with the one
         provided by the caller.
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContentOverrideName
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -304,10 +330,23 @@ paths:
         - Media
   "/media/v3/thumbnail/{serverName}/{mediaId}":
     get:
+      deprecated: true
       summary: Download a thumbnail of content from the content repository
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
         Download a thumbnail of content from the content repository.
         See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
+
+        {{% boxes/warning %}}
+        {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
       operationId: getContentThumbnail
       parameters:
         - $ref: '#/components/parameters/serverName'
@@ -455,8 +494,13 @@ paths:
         - Media
   /media/v3/preview_url:
     get:
+      deprecated: true
       summary: Get information about a URL for a client
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url).
+        {{% /boxes/note %}}
+
         Get information about a URL for the client. Typically this is called when a
         client sees a URL in a message and wants to render a preview for the user.
 
@@ -525,8 +569,13 @@ paths:
         - Media
   /media/v3/config:
     get:
+      deprecated: true
       summary: Get the configuration for the content repository.
       description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig).
+        {{% /boxes/note %}}
+
         This endpoint allows clients to retrieve the configuration of the content
         repository, such as upload limitations.
         Clients SHOULD use this as a guide when using content repository endpoints.
@@ -625,7 +674,7 @@ components:
         Indicates to the server that it should not attempt to fetch the media if
         it is deemed remote. This is to prevent routing loops where the server
         contacts itself.
-        
+
         Defaults to `true` if not provided.
       example: false
       schema:
diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml
index 3b95e664..0996511e 100644
--- a/data/api/client-server/definitions/sso_login_flow.yaml
+++ b/data/api/client-server/definitions/sso_login_flow.yaml
@@ -53,6 +53,18 @@ properties:
           description: |-
             Optional `mxc://` URI to provide an image/icon representing the IdP.
             Intended to be shown alongside the `name` if provided.
+
+            {{% boxes/note %}}
+            Clients SHOULD use the deprecated [`/download`](/client-server-api/#get_matrixmediav3downloadservernamemediaid)
+            and [`/thumbnail`](/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
+            endpoints to retrieve this media item because clients will not have
+            an access token they can authenticate with yet. Servers SHOULD ensure
+            media used for IdP icons is excluded from the freeze described by the
+            [Content Repository module's Client Behaviour section](/client-server-api/#content-repo-client-behaviour).
+
+            This may be addressed in the future with proposals like [MSC4148](https://github.com/matrix-org/matrix-spec-proposals/pull/4148),
+            or removed entirely through the transition to OIDC.
+            {{% /boxes/note %}}
           example: "mxc://example.org/abc123"
         brand:
           type: string
diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml
new file mode 100644
index 00000000..6c19d6ec
--- /dev/null
+++ b/data/api/server-server/content_repository.yaml
@@ -0,0 +1,303 @@
+# Copyright 2024 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 Federation Content Repository API
+  version: 1.0.0
+paths:
+  "/media/download/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download content from the content repository.
+      operationId: getContent
+      security:
+        - signedRequest: []
+      parameters:
+        - $ref: '#/components/parameters/mediaId'
+        - $ref: '#/components/parameters/timeout_ms'
+      responses:
+        "200":
+          description: The content that was previously uploaded.
+          headers:
+            Content-Type:
+              $ref: '#/components/headers/downloadContentType'
+          content:
+            multipart/mixed:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: |-
+                  **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html))
+                  delineating exactly two parts:
+
+                  The first part has a `Content-Type` header of `application/json`
+                  and describes the media's metadata, if any. Currently, this will
+                  always be an empty object.
+
+                  The second part is either:
+
+                  1. the bytes of the media itself, using `Content-Type` and
+                     `Content-Disposition` headers as appropriate;
+                  2. or a `Location` header to redirect the caller to where the media
+                     can be retrieved. The URL at `Location` SHOULD have appropriate
+                     `Content-Type` and `Content-Disposition` headers which describe
+                     the media.
+
+                     When `Location` is present, servers SHOULD NOT cache the URL.
+                     The remote server may have applied time limits on its validity.
+                     If the caller requires an up-to-date URL, it SHOULD re-request
+                     the media download.
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          description: The content is too large for the server to serve.
+          content:
+            application/json:
+              schema:
+                # XXX: We should move error definitions into a more generic place.
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to serve"
+                  }
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  "/media/thumbnail/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download a thumbnail of content from the content repository
+      description: |-
+        Download a thumbnail of content from the content repository.
+        See the [Client-Server API Thumbnails](/client-server-api/#thumbnails)
+        section for more information.
+      operationId: getContentThumbnail
+      security:
+        - signedRequest: []
+      parameters:
+        - $ref: '#/components/parameters/mediaId'
+        - in: query
+          name: width
+          required: true
+          description: |-
+            The *desired* width of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: height
+          required: true
+          description: |-
+            The *desired* height of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: method
+          description: |-
+            The desired resizing method. See the [Client-Server API Thumbnails](/client-server-api/#thumbnails)
+            section for more information.
+          example: scale
+          schema:
+            type: string
+            enum:
+              - crop
+              - scale
+        - $ref: '#/components/parameters/timeout_ms'
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server should behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: A thumbnail of the requested content.
+          headers:
+            Content-Type:
+              description: Must be `multipart/mixed`.
+              schema:
+                type: string
+          content:
+            multipart/mixed:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: |-
+                  **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html))
+                  delineating exactly two parts:
+
+                  The first part has a `Content-Type` header of `application/json`
+                  and describes the media's metadata, if any. Currently, this will
+                  always be an empty object.
+
+                  The second part is either:
+
+                  1. the bytes of the media itself, using `Content-Type` and
+                     `Content-Disposition` headers as appropriate;
+                  2. or a `Location` header to redirect the caller to where the media
+                     can be retrieved. The URL at `Location` SHOULD have appropriate
+                     `Content-Type` and `Content-Disposition` headers which describe
+                     the media.
+
+                     When `Location` is present, servers SHOULD NOT cache the URL.
+                     The remote server may have applied time limits on its validity.
+                     If the caller requires an up-to-date URL, it SHOULD re-request
+                     the media download.
+
+                  {{% boxes/note %}}
+                  The `Content-Type` for the second part SHOULD be one of:
+                  * `image/png` (possibly of the APNG variety)
+                  * `image/apng`
+                  * `image/jpeg`
+                  * `image/gif`
+                  * `image/webp`
+                  {{% /boxes/note %}}
+        "400":
+          description: |-
+            The request does not make sense to the server, or the server cannot thumbnail
+            the content. For example, the caller requested non-integer dimensions or asked
+            for negatively-sized images.
+          content:
+            application/json:
+              schema:
+                # XXX: We should move error definitions into a more generic place.
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "Cannot generate thumbnails for the requested content"
+                  }
+        "413":
+          description: The local content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                # XXX: We should move error definitions into a more generic place.
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          description: The remote content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                # XXX: We should move error definitions into a more generic place.
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
+  parameters:
+    mediaId:
+      in: path
+      name: mediaId
+      required: true
+      description: |
+        The media ID from the `mxc://` URI (the path component).
+      example: ascERGshawAWawugaAcauga
+      schema:
+        type: string
+    timeout_ms:
+      in: query
+      name: timeout_ms
+      x-addedInMatrixVersion: "1.7"
+      description: |
+        The maximum number of milliseconds that the client is willing to wait to
+        start receiving data, in the case that the content has not yet been
+        uploaded. The default value is 20000 (20 seconds). The content
+        repository can and should impose a maximum value for this parameter. The
+        content repository may also choose to respond before the timeout.
+      example: 5000
+      schema:
+        type: integer
+        format: int64
+        default: 20000
+  responses:
+    rateLimited:
+      description: This request was rate-limited.
+      content:
+        application/json:
+          schema:
+            # XXX: We should move error definitions into a more generic place.
+            $ref: ../client-server/definitions/errors/rate_limited.yaml
+    notYetUploaded:
+      description: |-
+        The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
+        will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
+      content:
+        application/json:
+          schema:
+            # XXX: We should move error definitions into a more generic place.
+            $ref: ../client-server/definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_NOT_YET_UPLOADED",
+                "error": "Content has not yet been uploaded"
+              }
+  headers:
+    downloadContentType:
+      description: |-
+        Must be `multipart/mixed`.
+      schema:
+        type: string

From f38b0525690b7fe331b4156e8fde74484097a228 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 13 Jun 2024 12:27:06 -0600
Subject: [PATCH 75/82] Use RFC 2119 keywords across the content repository
 spec (#1861)

* Use RFC 2119 keywords across the content repository spec

* changelog
---
 changelogs/client_server/newsfragments/1861.clarification | 1 +
 data/api/client-server/authed-content-repo.yaml           | 6 +++---
 data/api/client-server/content-repo.yaml                  | 6 +++---
 data/api/server-server/content_repository.yaml            | 6 +++---
 4 files changed, 10 insertions(+), 9 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1861.clarification

diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification
new file mode 100644
index 00000000..9d877ff5
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1861.clarification
@@ -0,0 +1 @@
+Use RFC 2119 keywords more consistently throughout various parts of the specification.
\ No newline at end of file
diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml
index 9741d618..43cb5881 100644
--- a/data/api/client-server/authed-content-repo.yaml
+++ b/data/api/client-server/authed-content-repo.yaml
@@ -200,7 +200,7 @@ paths:
             Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
 
             When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
-            server should behave as though `animated` is `false`.
+            server SHOULD behave as though `animated` is `false`.
           example: false
           schema:
             type: boolean
@@ -454,8 +454,8 @@ components:
         The maximum number of milliseconds that the client is willing to wait to
         start receiving data, in the case that the content has not yet been
         uploaded. The default value is 20000 (20 seconds). The content
-        repository can and should impose a maximum value for this parameter. The
-        content repository may also choose to respond before the timeout.
+        repository SHOULD impose a maximum value for this parameter. The
+        content repository MAY respond before the timeout.
       example: 5000
       schema:
         type: integer
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index 1dac8b10..038ac618 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -401,7 +401,7 @@ paths:
             Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
 
             When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
-            server should behave as though `animated` is `false`.
+            server SHOULD behave as though `animated` is `false`.
           example: false
           schema:
             type: boolean
@@ -688,8 +688,8 @@ components:
         The maximum number of milliseconds that the client is willing to wait to
         start receiving data, in the case that the content has not yet been
         uploaded. The default value is 20000 (20 seconds). The content
-        repository can and should impose a maximum value for this parameter. The
-        content repository may also choose to respond before the timeout.
+        repository SHOULD impose a maximum value for this parameter. The
+        content repository MAY respond before the timeout.
       example: 5000
       schema:
         type: integer
diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml
index 6c19d6ec..bd07e252 100644
--- a/data/api/server-server/content_repository.yaml
+++ b/data/api/server-server/content_repository.yaml
@@ -137,7 +137,7 @@ paths:
             Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
 
             When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
-            server should behave as though `animated` is `false`.
+            server SHOULD behave as though `animated` is `false`.
           example: false
           schema:
             type: boolean
@@ -265,8 +265,8 @@ components:
         The maximum number of milliseconds that the client is willing to wait to
         start receiving data, in the case that the content has not yet been
         uploaded. The default value is 20000 (20 seconds). The content
-        repository can and should impose a maximum value for this parameter. The
-        content repository may also choose to respond before the timeout.
+        repository SHOULD impose a maximum value for this parameter. The
+        content repository MAY respond before the timeout.
       example: 5000
       schema:
         type: integer

From 672af37cbd2a9b7c78e72e5e847b593154ebc7be Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Thu, 13 Jun 2024 20:34:54 +0200
Subject: [PATCH 76/82] Clarify that relations recursion should be capped at a
 certain depth (#1854)

---
 .../client_server/newsfragments/1854.clarification       | 1 +
 data/api/client-server/relations.yaml                    | 9 ++++-----
 2 files changed, 5 insertions(+), 5 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1854.clarification

diff --git a/changelogs/client_server/newsfragments/1854.clarification b/changelogs/client_server/newsfragments/1854.clarification
new file mode 100644
index 00000000..cb996bd6
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1854.clarification
@@ -0,0 +1 @@
+ Clarify that relations recursion should be capped at a certain depth.
diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml
index 3f3d5baa..c4b0228c 100644
--- a/data/api/client-server/relations.yaml
+++ b/data/api/client-server/relations.yaml
@@ -315,11 +315,10 @@ components:
         If set to `false`, only events which have a direct relation with the given
         event will be included.
 
-        If set to `true`, all events which relate to the given event, or relate to
-        events that relate to the given event, will be included.
-
-        It is recommended that homeservers traverse at least 3 levels of relationships.
-        Implementations may perform more but should be careful to not infinitely recurse.
+        If set to `true`, events which have an indirect relation with the given event
+        will be included additionally up to a certain depth level. Homeservers SHOULD traverse
+        at least 3 levels of relationships. Implementations MAY perform more but MUST be careful
+        to not infinitely recurse.
 
         The default value is `false`.
       schema:

From f434fdfba7c1d0f651e9e002bcfdb5ef9224501f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Thu, 13 Jun 2024 23:37:07 +0200
Subject: [PATCH 77/82] Replace references to obsolete RFC 1341 with RFC 2046
 (#1869)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Replace references to obsolete RFC 1341 with RFC 2046

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 changelogs/server_server/newsfragments/1869.feature | 1 +
 data/api/server-server/content_repository.yaml      | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1869.feature

diff --git a/changelogs/server_server/newsfragments/1869.feature b/changelogs/server_server/newsfragments/1869.feature
new file mode 100644
index 00000000..02b9b51e
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1869.feature
@@ -0,0 +1 @@
+Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916).
\ No newline at end of file
diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml
index bd07e252..66439b79 100644
--- a/data/api/server-server/content_repository.yaml
+++ b/data/api/server-server/content_repository.yaml
@@ -37,7 +37,7 @@ paths:
               schema:
                 # This is a workaround for us not being able to say the response is required.
                 description: |-
-                  **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html))
+                  **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1))
                   delineating exactly two parts:
 
                   The first part has a `Content-Type` header of `application/json`
@@ -154,7 +154,7 @@ paths:
               schema:
                 # This is a workaround for us not being able to say the response is required.
                 description: |-
-                  **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html))
+                  **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1))
                   delineating exactly two parts:
 
                   The first part has a `Content-Type` header of `application/json`

From 5f47b9624088a94518b735c90c082bcff762d913 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Fri, 14 Jun 2024 12:34:35 +0100
Subject: [PATCH 78/82] Clarify when server name is used and link to definition
 (#1862)

* Clarify when server name is used and link to definition

* Changelog
---
 changelogs/client_server/newsfragments/1862.clarification | 1 +
 content/client-server-api/_index.md                       | 4 ++--
 content/client-server-api/modules/sso_login.md            | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1862.clarification

diff --git a/changelogs/client_server/newsfragments/1862.clarification b/changelogs/client_server/newsfragments/1862.clarification
new file mode 100644
index 00000000..021b117c
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1862.clarification
@@ -0,0 +1 @@
+Clarify when server name is used and link to the definition.
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 3e8a8670..8b40fe99 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -355,9 +355,9 @@ as per the [CORS](#web-browser-clients) section in this specification.
 The `.well-known` method uses a JSON file at a predetermined location to
 specify parameter values. The flow for this method is as follows:
 
-1.  Extract the server name from the user's Matrix ID by splitting the
+1.  Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
     Matrix ID at the first colon.
-2.  Extract the hostname from the server name.
+2.  Extract the hostname from the server name as described by the [grammar](/appendices/#server-name).
 3.  Make a GET request to `https://hostname/.well-known/matrix/client`.
     1.  If the returned status code is 404, then `IGNORE`.
     2.  If the returned status code is not 200, or the response body is
diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md
index 1a46c84d..f50a2eb1 100644
--- a/content/client-server-api/modules/sso_login.md
+++ b/content/client-server-api/modules/sso_login.md
@@ -123,8 +123,8 @@ authentication is successful, the browser will be redirected to that
 
     For example, consider a web-based client at
     `https://client.example.com`, which wants to initiate SSO login on
-    the homeserver at `server.example.org`. It does this by storing the
-    homeserver name in a query parameter for the `redirectUrl`: it
+    the homeserver with [server name](/appendices/#server-name) `server.example.org`. It does this by storing the
+    server name in a query parameter for the `redirectUrl`: it
     redirects to
     `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`.
 

From 7773716d189b16c1d5fa1dd2bfb8a1685bfb1108 Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Fri, 14 Jun 2024 16:44:01 +0200
Subject: [PATCH 79/82] Clarify that asynchronous media upload requires
 authentication (#1872)

Fixes: #1554
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/client_server/newsfragments/1872.clarification | 1 +
 data/api/client-server/content-repo.yaml                  | 3 +++
 2 files changed, 4 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1872.clarification

diff --git a/changelogs/client_server/newsfragments/1872.clarification b/changelogs/client_server/newsfragments/1872.clarification
new file mode 100644
index 00000000..4bcea39e
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1872.clarification
@@ -0,0 +1 @@
+Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication.
diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml
index 038ac618..d0a6e5bb 100644
--- a/data/api/client-server/content-repo.yaml
+++ b/data/api/client-server/content-repo.yaml
@@ -81,6 +81,9 @@ paths:
         earlier via [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create).
       operationId: uploadContentToMXC
       x-addedInMatrixVersion: "1.7"
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
       parameters:
         - $ref: '#/components/parameters/serverName'
           description: |

From 6dfab46268d68e139255c6cd74260a17cf1f69ab Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Tue, 18 Jun 2024 16:20:57 +0200
Subject: [PATCH 80/82] Fix typo in SRV delegation (#1877)

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
---
 changelogs/server_server/newsfragments/1877.clarification | 1 +
 content/server-server-api.md                              | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/server_server/newsfragments/1877.clarification

diff --git a/changelogs/server_server/newsfragments/1877.clarification b/changelogs/server_server/newsfragments/1877.clarification
new file mode 100644
index 00000000..3ccb2333
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1877.clarification
@@ -0,0 +1 @@
+Fix various typos throughout the specification.
diff --git a/content/server-server-api.md b/content/server-server-api.md
index 9e92bfd9..5c9bd31e 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -166,7 +166,7 @@ to send. The process overall is as follows:
         target server must present a valid certificate for
         `<delegated_hostname>`.
     5.   If no SRV record is found, an IP address is resolved using CNAME, AAAA
-        or A records. Requests are then made to the resolve IP address
+        or A records. Requests are then made to the resolved IP address
         and a port of 8448, using a `Host` header of
         `<delegated_hostname>`. The target server must present a valid
         certificate for `<delegated_hostname>`.

From 4e32fca05fd89492a3acb82b7a2a922d155ee824 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 18 Jun 2024 17:59:26 +0200
Subject: [PATCH 81/82] Clarify that an access token is optional on
 `/account/password` and `/account/deactivate` (#1843)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---
 changelogs/client_server/newsfragments/1843.clarification | 1 +
 data/api/client-server/registration.yaml                  | 2 ++
 2 files changed, 3 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1843.clarification

diff --git a/changelogs/client_server/newsfragments/1843.clarification b/changelogs/client_server/newsfragments/1843.clarification
new file mode 100644
index 00000000..7ccfe4a7
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1843.clarification
@@ -0,0 +1 @@
+Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints.
\ No newline at end of file
diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml
index afd30459..84aef5b1 100644
--- a/data/api/client-server/registration.yaml
+++ b/data/api/client-server/registration.yaml
@@ -387,6 +387,7 @@ paths:
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
       security:
+        - {}
         - accessTokenQuery: []
         - accessTokenBearer: []
       operationId: changePassword
@@ -592,6 +593,7 @@ paths:
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
       security:
+        - {}
         - accessTokenQuery: []
         - accessTokenBearer: []
       operationId: deactivateAccount

From 9c46fa3f35f5e1517c401b7654a2faad1fbf65d7 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Wed, 19 Jun 2024 21:52:21 -0600
Subject: [PATCH 82/82] Normalize the changelog for Matrix 1.11

---
 changelogs/application_service/newsfragments/1810.clarification | 2 +-
 changelogs/client_server/newsfragments/1644.clarification       | 2 +-
 .../newsfragments/{1755.clarification => 1755.feature}          | 0
 changelogs/client_server/newsfragments/1757.feature             | 2 +-
 changelogs/client_server/newsfragments/1772.clarification       | 1 -
 changelogs/client_server/newsfragments/1808.clarification       | 1 -
 changelogs/client_server/newsfragments/1808.deprecation         | 1 +
 changelogs/client_server/newsfragments/1813.clarification       | 2 +-
 .../newsfragments/{1816.clarification => 1816.feature}          | 0
 changelogs/client_server/newsfragments/1841.clarification       | 2 +-
 changelogs/client_server/newsfragments/1846.clarification       | 2 +-
 changelogs/client_server/newsfragments/1847.feature             | 2 +-
 changelogs/client_server/newsfragments/1861.clarification       | 2 +-
 changelogs/client_server/newsfragments/1863.clarification       | 2 +-
 changelogs/identity_service/newsfragments/1772.clarification    | 1 -
 changelogs/identity_service/newsfragments/1808.clarification    | 1 -
 changelogs/identity_service/newsfragments/1808.deprecation      | 1 +
 changelogs/internal/newsfragments/1769.clarification            | 2 +-
 changelogs/internal/newsfragments/1770.clarification            | 2 +-
 changelogs/internal/newsfragments/1771.clarification            | 2 +-
 .../newsfragments/1772.clarification                            | 0
 changelogs/internal/newsfragments/1781.clarification            | 2 +-
 changelogs/internal/newsfragments/1786.clarification            | 2 +-
 .../internal/newsfragments/{1793.misc => 1793.clarification}    | 0
 changelogs/internal/newsfragments/1803.clarification            | 2 +-
 changelogs/internal/newsfragments/1804.clarification            | 2 +-
 changelogs/internal/newsfragments/1813.clarification            | 1 +
 .../newsfragments/1822.clarification                            | 0
 changelogs/room_versions/newsfragments/1827.clarification       | 2 +-
 changelogs/server_server/newsfragments/1772.clarification       | 1 -
 changelogs/server_server/newsfragments/1813.clarification       | 2 +-
 31 files changed, 21 insertions(+), 23 deletions(-)
 rename changelogs/client_server/newsfragments/{1755.clarification => 1755.feature} (100%)
 delete mode 100644 changelogs/client_server/newsfragments/1772.clarification
 delete mode 100644 changelogs/client_server/newsfragments/1808.clarification
 create mode 100644 changelogs/client_server/newsfragments/1808.deprecation
 rename changelogs/client_server/newsfragments/{1816.clarification => 1816.feature} (100%)
 delete mode 100644 changelogs/identity_service/newsfragments/1772.clarification
 delete mode 100644 changelogs/identity_service/newsfragments/1808.clarification
 create mode 100644 changelogs/identity_service/newsfragments/1808.deprecation
 rename changelogs/{application_service => internal}/newsfragments/1772.clarification (100%)
 rename changelogs/internal/newsfragments/{1793.misc => 1793.clarification} (100%)
 create mode 100644 changelogs/internal/newsfragments/1813.clarification
 rename changelogs/{client_server => internal}/newsfragments/1822.clarification (100%)
 delete mode 100644 changelogs/server_server/newsfragments/1772.clarification

diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification
index 66dab495..fd21375c 100644
--- a/changelogs/application_service/newsfragments/1810.clarification
+++ b/changelogs/application_service/newsfragments/1810.clarification
@@ -1 +1 @@
-Clarify that appservices should be notified of events relating to the sender_localpart user.
+Clarify that appservices should be notified of events relating to the `sender_localpart` user.
diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification
index 78c0919d..279c4312 100644
--- a/changelogs/client_server/newsfragments/1644.clarification
+++ b/changelogs/client_server/newsfragments/1644.clarification
@@ -1 +1 @@
-Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body.
+Add `/logout` and clarify the endpoints which do not take a JSON request body.
diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.feature
similarity index 100%
rename from changelogs/client_server/newsfragments/1755.clarification
rename to changelogs/client_server/newsfragments/1755.feature
diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature
index 3471c1b9..f65d48ba 100644
--- a/changelogs/client_server/newsfragments/1757.feature
+++ b/changelogs/client_server/newsfragments/1757.feature
@@ -1 +1 @@
-Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).
\ No newline at end of file
+Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705).
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1772.clarification b/changelogs/client_server/newsfragments/1772.clarification
deleted file mode 100644
index b2aafa0d..00000000
--- a/changelogs/client_server/newsfragments/1772.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/client_server/newsfragments/1808.clarification b/changelogs/client_server/newsfragments/1808.clarification
deleted file mode 100644
index ff2c1651..00000000
--- a/changelogs/client_server/newsfragments/1808.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
diff --git a/changelogs/client_server/newsfragments/1808.deprecation b/changelogs/client_server/newsfragments/1808.deprecation
new file mode 100644
index 00000000..ae9f620d
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1808.deprecation
@@ -0,0 +1 @@
+Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead.
diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification
index af643e2e..fa76c2a1 100644
--- a/changelogs/client_server/newsfragments/1813.clarification
+++ b/changelogs/client_server/newsfragments/1813.clarification
@@ -1 +1 @@
-Use `patternProperties` in more places with supported formats.
+Link to existing grammar where possible in types.
diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.feature
similarity index 100%
rename from changelogs/client_server/newsfragments/1816.clarification
rename to changelogs/client_server/newsfragments/1816.feature
diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification
index faf8aae9..3ccb2333 100644
--- a/changelogs/client_server/newsfragments/1841.clarification
+++ b/changelogs/client_server/newsfragments/1841.clarification
@@ -1 +1 @@
-Fix broken link to push rule condition kinds.
+Fix various typos throughout the specification.
diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification
index 6f57eb35..ee5387a8 100644
--- a/changelogs/client_server/newsfragments/1846.clarification
+++ b/changelogs/client_server/newsfragments/1846.clarification
@@ -1 +1 @@
-Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement.
+Use RFC 2119 keywords more consistently.
diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature
index 25d1914b..ab3dbc34 100644
--- a/changelogs/client_server/newsfragments/1847.feature
+++ b/changelogs/client_server/newsfragments/1847.feature
@@ -1 +1 @@
-Add the new `unsigned.membership` property to events served over the client-server API, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115).
+Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115).
diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification
index 9d877ff5..ee5387a8 100644
--- a/changelogs/client_server/newsfragments/1861.clarification
+++ b/changelogs/client_server/newsfragments/1861.clarification
@@ -1 +1 @@
-Use RFC 2119 keywords more consistently throughout various parts of the specification.
\ No newline at end of file
+Use RFC 2119 keywords more consistently.
diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification
index d054d41d..688288cf 100644
--- a/changelogs/client_server/newsfragments/1863.clarification
+++ b/changelogs/client_server/newsfragments/1863.clarification
@@ -1 +1 @@
-Minor clarifications to the "end-to-end encryption" module.
+Clarify where keys reside when checking an `m.room.encrypted` event.
diff --git a/changelogs/identity_service/newsfragments/1772.clarification b/changelogs/identity_service/newsfragments/1772.clarification
deleted file mode 100644
index b2aafa0d..00000000
--- a/changelogs/identity_service/newsfragments/1772.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/identity_service/newsfragments/1808.clarification b/changelogs/identity_service/newsfragments/1808.clarification
deleted file mode 100644
index ff2c1651..00000000
--- a/changelogs/identity_service/newsfragments/1808.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126).
diff --git a/changelogs/identity_service/newsfragments/1808.deprecation b/changelogs/identity_service/newsfragments/1808.deprecation
new file mode 100644
index 00000000..ae9f620d
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1808.deprecation
@@ -0,0 +1 @@
+Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead.
diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification
index ebf8030d..c092b8f7 100644
--- a/changelogs/internal/newsfragments/1769.clarification
+++ b/changelogs/internal/newsfragments/1769.clarification
@@ -1 +1 @@
-Formatting fixes in CONTRIBUTING.rst.
+Formatting fixes in `CONTRIBUTING.rst`.
diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification
index e5fb516f..0eb57682 100644
--- a/changelogs/internal/newsfragments/1770.clarification
+++ b/changelogs/internal/newsfragments/1770.clarification
@@ -1 +1 @@
-Reduce whitespace on mobile viewports
+Improve rendering on mobile devices.
\ No newline at end of file
diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification
index b1941e18..0eb57682 100644
--- a/changelogs/internal/newsfragments/1771.clarification
+++ b/changelogs/internal/newsfragments/1771.clarification
@@ -1 +1 @@
-Arrange rows in `.basic-info` tables vertically when horizontal space is constrained.
+Improve rendering on mobile devices.
\ No newline at end of file
diff --git a/changelogs/application_service/newsfragments/1772.clarification b/changelogs/internal/newsfragments/1772.clarification
similarity index 100%
rename from changelogs/application_service/newsfragments/1772.clarification
rename to changelogs/internal/newsfragments/1772.clarification
diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification
index 4fb58650..8776d77b 100644
--- a/changelogs/internal/newsfragments/1781.clarification
+++ b/changelogs/internal/newsfragments/1781.clarification
@@ -1 +1 @@
-Fix `github-labels.rst`
+Fix `github-labels.rst`.
diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification
index 1810c632..c66e15e3 100644
--- a/changelogs/internal/newsfragments/1786.clarification
+++ b/changelogs/internal/newsfragments/1786.clarification
@@ -1 +1 @@
-Upgrade jsonschema and python-jsonpath CI scripts dependencies.
+Update dependencies.
\ No newline at end of file
diff --git a/changelogs/internal/newsfragments/1793.misc b/changelogs/internal/newsfragments/1793.clarification
similarity index 100%
rename from changelogs/internal/newsfragments/1793.misc
rename to changelogs/internal/newsfragments/1793.clarification
diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification
index dbfaa8c9..c66e15e3 100644
--- a/changelogs/internal/newsfragments/1803.clarification
+++ b/changelogs/internal/newsfragments/1803.clarification
@@ -1 +1 @@
-Update most CI actions.
+Update dependencies.
\ No newline at end of file
diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification
index 39249cb8..c66e15e3 100644
--- a/changelogs/internal/newsfragments/1804.clarification
+++ b/changelogs/internal/newsfragments/1804.clarification
@@ -1 +1 @@
-Update typos CI action.
+Update dependencies.
\ No newline at end of file
diff --git a/changelogs/internal/newsfragments/1813.clarification b/changelogs/internal/newsfragments/1813.clarification
new file mode 100644
index 00000000..af643e2e
--- /dev/null
+++ b/changelogs/internal/newsfragments/1813.clarification
@@ -0,0 +1 @@
+Use `patternProperties` in more places with supported formats.
diff --git a/changelogs/client_server/newsfragments/1822.clarification b/changelogs/internal/newsfragments/1822.clarification
similarity index 100%
rename from changelogs/client_server/newsfragments/1822.clarification
rename to changelogs/internal/newsfragments/1822.clarification
diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification
index c122052d..ca5f3aea 100644
--- a/changelogs/room_versions/newsfragments/1827.clarification
+++ b/changelogs/room_versions/newsfragments/1827.clarification
@@ -1 +1 @@
-Fix minor spelling mistake of object being spelt "obiect".
+Fix various typos throughout the specification.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1772.clarification b/changelogs/server_server/newsfragments/1772.clarification
deleted file mode 100644
index b2aafa0d..00000000
--- a/changelogs/server_server/newsfragments/1772.clarification
+++ /dev/null
@@ -1 +0,0 @@
-Fix the OpenAPI definition of the security schemes.
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification
index af643e2e..fa76c2a1 100644
--- a/changelogs/server_server/newsfragments/1813.clarification
+++ b/changelogs/server_server/newsfragments/1813.clarification
@@ -1 +1 @@
-Use `patternProperties` in more places with supported formats.
+Link to existing grammar where possible in types.