Merge 8947eaf0b2 into 486a8f8764

* Clarify string formats of event endpoints and schemas

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

* Fix links to endpoints

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

@@ -28,7 +28,7 @@ jobs:
 
       # Ensure npm 11.5.1 or later is installed
       - name: Update npm
-        run: npm install -g npm@latest
+        run: sudo npm install -g npm@latest
 
       - name: 🔨 Install dependencies
         run: "yarn install --frozen-lockfile"

changelogs/appendices/newsfragments/2307.clarification

@@ -1 +0,0 @@
-Add identifier pronunciation guidelines. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2270.feature

@@ -1 +0,0 @@
-Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).

changelogs/client_server/newsfragments/2272.feature

@@ -1 +0,0 @@
-Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824).

changelogs/client_server/newsfragments/2277.clarification

@@ -1,3 +0,0 @@
-The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request
-and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`,
-as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/client_server/newsfragments/2278.feature

@@ -1 +0,0 @@
-Add administrator endpoints to lock and suspend server-local users and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.1

@@ -1 +0,0 @@
-Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.2

@@ -1 +0,0 @@
-Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.3

@@ -1 +0,0 @@
-Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2278.new.4

@@ -1 +0,0 @@
-Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323).

changelogs/client_server/newsfragments/2280.clarification

@@ -1 +0,0 @@
-Update non-historic mentions of matrix-doc repo to matrix-spec/-proposals. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2283.clarification

@@ -1 +0,0 @@
-Remove unintended TeX formatting. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2291.feature

@@ -1 +0,0 @@
-Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356).

changelogs/client_server/newsfragments/2292.feature

@@ -1 +0,0 @@
-Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267).

changelogs/client_server/newsfragments/2298.feature

@@ -1 +0,0 @@
-Add support for `m.room.redaction` events at the `PUT /rooms/{roomId}/send/{eventType}/{txnId}` endpoint, as per [MSC4169](https://github.com/matrix-org/matrix-spec-proposals/pull/4169).

changelogs/client_server/newsfragments/2299.feature

@@ -1 +0,0 @@
-Clients supporting the `ol` HTML element must also support the `start` attribute, as per [MSC4313](https://github.com/matrix-org/matrix-spec-proposals/pull/4313).

changelogs/client_server/newsfragments/2301.feature

@@ -1 +0,0 @@
-Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).

changelogs/client_server/newsfragments/2304.clarification

@@ -1 +0,0 @@
-Clarify the requiredness of `event_id` in `predecessor`.

changelogs/client_server/newsfragments/2305.feature

@@ -1 +0,0 @@
-Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380).

changelogs/client_server/newsfragments/2306.clarification

@@ -1 +0,0 @@
-Clarify terminology for keys in cross-signing module.

changelogs/client_server/newsfragments/2316.clarification

@@ -1 +0,0 @@
-Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI.

changelogs/client_server/newsfragments/2344.clarification

@@ -0,0 +1 @@
+Clarify SAS commitment calculation for `m.key.verification.accept` messages.

changelogs/client_server/newsfragments/2347.clarification

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

changelogs/client_server/newsfragments/2348.clarification

@@ -0,0 +1 @@
+Fix ordering of common error codes.

changelogs/client_server/newsfragments/2349.clarification

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

changelogs/identity_service/newsfragments/2277.clarification

@@ -1,3 +0,0 @@
-Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken`
-and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT`
-error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183).

changelogs/internal/newsfragments/2222.clarification

@@ -1 +0,0 @@
-Clarify vendor prefixing requirements.

changelogs/internal/newsfragments/2275.clarification

@@ -1 +0,0 @@
-Auto-create draft releases when building release tags.

changelogs/internal/newsfragments/2276.feature

@@ -1 +0,0 @@
-Include the spec release version in the filenames in the tarballs generated by CI.

changelogs/internal/newsfragments/2282.clarification

@@ -1 +0,0 @@
-Replace the Twitter link in the footer with our BlueSky and Mastodon socials.

changelogs/internal/newsfragments/2287.clarification

@@ -1 +0,0 @@
-Upgrade to docsy v0.13.0.

changelogs/internal/newsfragments/2289.clarification

@@ -1 +0,0 @@
-Updates to the release documentation.

changelogs/internal/newsfragments/2290.clarification

@@ -1 +0,0 @@
-Remove unused leftover CSS files.

changelogs/internal/newsfragments/2317.clarification

@@ -1 +0,0 @@
-Update the footer social links to match matrix.org. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2343.clarification

@@ -0,0 +1 @@
+Update and fix GitHub Actions.

changelogs/room_versions/newsfragments/2297.clarification

@@ -1 +0,0 @@
-Clarify meaning of floating-point powerlevels.

changelogs/room_versions/newsfragments/2303.clarification

@@ -1 +0,0 @@
-Remove the post-1.16 release note for room version 12.

changelogs/server_server/newsfragments/2191.clarification

@@ -1 +0,0 @@
-Clarify what the `minimum_valid_until_ts` field means when it is set in key queries.

changelogs/server_server/newsfragments/2284.clarification

@@ -1 +0,0 @@
-Specify validation for PDUs passed to and returned from federation membership endpoints.

changelogs/server_server/newsfragments/2288.clarification

@@ -1 +0,0 @@
-Specify that callers of `/_matrix/federation/v1/openid/userinfo` must validate the returned user ID.

changelogs/server_server/newsfragments/2300.clarification

@@ -1 +0,0 @@
-Change `m.signing_update` typo to `m.signing_key_update`. Contributed by @velikopter

changelogs/server_server/newsfragments/2319.removal

@@ -1 +0,0 @@
-Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376).

config/_default/hugo.toml

@@ -65,7 +65,7 @@ description = "Home of the Matrix specification for decentralised communication"
 # Everything below this are Site Params
 
 [params]
-copyright = "The Matrix.org Foundation CIC"
+copyright = "The Matrix.org Foundation C.I.C."
 
 [params.version]
 # must be one of "unstable", "current", "historical"
@@ -76,7 +76,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 #major = "1"
-#minor = "17"
+#minor = "18"
 
 [[params.versions]]
 # We must include this parameter to enable docsy's version picker in the navbar. The picker

content/application-service-api.md

@@ -84,7 +84,7 @@ For the `users` namespace, application services can only register interest in
 homeserver). Events affecting users on other homeservers are not sent to an application
 service, even if the user happens to match the one of the `users` namespaces (unless,
 of course, the event affects a room that the application service is interested in
-for another room - for example, because there is another user in the room that the
+for another reason - for example, because there is another user in the room that the
 application service is interested in).
 
 For the `rooms` and `aliases` namespaces, all events in a matching room will be

content/changelog/v1.18.md

@@ -0,0 +1,127 @@
+---
+title: v1.18 Changelog
+linkTitle: v1.18
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2026-03-25
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
+- Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
+- Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
+- Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
+
+**Removed Endpoints**
+
+- The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277). ([#2311](https://github.com/matrix-org/matrix-spec/issues/2311))
+
+**Backwards Compatible Changes**
+
+- Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191). ([#2270](https://github.com/matrix-org/matrix-spec/issues/2270))
+- Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824). ([#2272](https://github.com/matrix-org/matrix-spec/issues/2272))
+- Add administrator endpoints to lock and suspend server-local users and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
+- Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356). ([#2291](https://github.com/matrix-org/matrix-spec/issues/2291))
+- Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267). ([#2292](https://github.com/matrix-org/matrix-spec/issues/2292))
+- Add support for `m.room.redaction` events at the `PUT /rooms/{roomId}/send/{eventType}/{txnId}` endpoint, as per [MSC4169](https://github.com/matrix-org/matrix-spec-proposals/pull/4169). ([#2298](https://github.com/matrix-org/matrix-spec/issues/2298))
+- Clients supporting the `ol` HTML element must also support the `start` attribute, as per [MSC4313](https://github.com/matrix-org/matrix-spec-proposals/pull/4313). ([#2299](https://github.com/matrix-org/matrix-spec/issues/2299))
+- Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153). ([#2301](https://github.com/matrix-org/matrix-spec/issues/2301))
+- Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380). ([#2305](https://github.com/matrix-org/matrix-spec/issues/2305))
+- `/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277). ([#2311](https://github.com/matrix-org/matrix-spec/issues/2311))
+- Add `M_USER_LIMIT_EXCEEDED` common error code, as per [MSC4335](https://github.com/matrix-org/matrix-spec-proposals/pull/4335). ([#2315](https://github.com/matrix-org/matrix-spec/issues/2315))
+- Add the OAuth 2.0 Device Authorization Grant (RFC 8628) as a supported grant type, as per [MSC4341](https://github.com/matrix-org/matrix-spec-proposals/pull/4341). ([#2320](https://github.com/matrix-org/matrix-spec/issues/2320))
+- Add the `is_animated` flag to the `info` object of the `m.image` msgtype and the `m.sticker` event, as per [MSC4230](https://github.com/matrix-org/matrix-spec-proposals/pull/4230). ([#2328](https://github.com/matrix-org/matrix-spec/issues/2328), [#2338](https://github.com/matrix-org/matrix-spec/issues/2338))
+- Add a "Policy Servers" module, as per [MSC4284](https://github.com/matrix-org/matrix-spec-proposals/pull/4284). ([#2332](https://github.com/matrix-org/matrix-spec/issues/2332))
+
+**Spec Clarifications**
+
+- The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). ([#2277](https://github.com/matrix-org/matrix-spec/issues/2277))
+- Update non-historic mentions of matrix-doc repo to matrix-spec/-proposals. Contributed by @HarHarLinks. ([#2280](https://github.com/matrix-org/matrix-spec/issues/2280))
+- Remove unintended TeX formatting. Contributed by @HarHarLinks. ([#2283](https://github.com/matrix-org/matrix-spec/issues/2283))
+- Clarify the requiredness of `event_id` in `predecessor`. ([#2304](https://github.com/matrix-org/matrix-spec/issues/2304))
+- Clarify terminology for keys in cross-signing module. ([#2306](https://github.com/matrix-org/matrix-spec/issues/2306))
+- Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI. ([#2316](https://github.com/matrix-org/matrix-spec/issues/2316))
+- Fix various typos throughout the specification. Contributed by @HarHarLinks. ([#2318](https://github.com/matrix-org/matrix-spec/issues/2318))
+- Clarified attachment encryption to require secure generation of keys and hash verification. ([#2324](https://github.com/matrix-org/matrix-spec/issues/2324))
+- Order the common and other error codes alphabetically and remove duplicate `M_THREEPID_IN_USE` definition. ([#2336](https://github.com/matrix-org/matrix-spec/issues/2336))
+- Fix various typos throughout the specification. ([#2337](https://github.com/matrix-org/matrix-spec/issues/2337))
+
+
+## Server-Server API
+
+**Removed Endpoints**
+
+- Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376). ([#2319](https://github.com/matrix-org/matrix-spec/issues/2319))
+
+**Backwards Compatible Changes**
+
+- Add a concept of "Policy Servers", as per [MSC4284](https://github.com/matrix-org/matrix-spec-proposals/pull/4284). ([#2332](https://github.com/matrix-org/matrix-spec/issues/2332))
+
+**Spec Clarifications**
+
+- Clarify what the `minimum_valid_until_ts` field means when it is set in key queries. ([#2191](https://github.com/matrix-org/matrix-spec/issues/2191))
+- Specify validation for PDUs passed to and returned from federation membership endpoints. ([#2284](https://github.com/matrix-org/matrix-spec/issues/2284))
+- Specify that callers of `/_matrix/federation/v1/openid/userinfo` must validate the returned user ID. ([#2288](https://github.com/matrix-org/matrix-spec/issues/2288))
+- Change `m.signing_update` typo to `m.signing_key_update`. Contributed by @velikopter ([#2300](https://github.com/matrix-org/matrix-spec/issues/2300))
+- Add link to JSON signing algorithm in server-server auth section for clarity. Contributed by @thetayloredman. ([#2329](https://github.com/matrix-org/matrix-spec/issues/2329))
+- Fix various typos throughout the specification. ([#2338](https://github.com/matrix-org/matrix-spec/issues/2338))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Fix various typos throughout the specification. ([#2330](https://github.com/matrix-org/matrix-spec/issues/2330))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken` and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT` error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). ([#2277](https://github.com/matrix-org/matrix-spec/issues/2277))
+- Order the standard error codes alphabetically. ([#2336](https://github.com/matrix-org/matrix-spec/issues/2336))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- Clarify meaning of floating-point powerlevels. ([#2297](https://github.com/matrix-org/matrix-spec/issues/2297))
+- Remove the post-1.16 release note for room version 12. ([#2303](https://github.com/matrix-org/matrix-spec/issues/2303))
+
+
+## Appendices
+
+**Spec Clarifications**
+
+- Add identifier pronunciation guidelines. Contributed by @HarHarLinks. ([#2307](https://github.com/matrix-org/matrix-spec/issues/2307))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Include the spec release version in the filenames in the tarballs generated by CI. ([#2276](https://github.com/matrix-org/matrix-spec/issues/2276))
+
+**Spec Clarifications**
+
+- Clarify vendor prefixing requirements. ([#2222](https://github.com/matrix-org/matrix-spec/issues/2222))
+- Auto-create draft releases when building release tags. ([#2275](https://github.com/matrix-org/matrix-spec/issues/2275))
+- Replace the Twitter link in the footer with our BlueSky and Mastodon socials. ([#2282](https://github.com/matrix-org/matrix-spec/issues/2282))
+- Upgrade to docsy v0.13.0. ([#2287](https://github.com/matrix-org/matrix-spec/issues/2287))
+- Updates to the release documentation. ([#2289](https://github.com/matrix-org/matrix-spec/issues/2289))
+- Remove unused leftover CSS files. ([#2290](https://github.com/matrix-org/matrix-spec/issues/2290))
+- Update the footer social links to match matrix.org. Contributed by @HarHarLinks. ([#2317](https://github.com/matrix-org/matrix-spec/issues/2317))
+- Fix various typos throughout the specification. Contributed by @HarHarLinks. ([#2318](https://github.com/matrix-org/matrix-spec/issues/2318))
+- Render error code sections as definition lists to improve readability. ([#2323](https://github.com/matrix-org/matrix-spec/issues/2323))

content/client-server-api/_index.md

@@ -93,51 +93,30 @@ request being made was invalid.
 
 These error codes can be returned by any API endpoint:
 
-`M_FORBIDDEN`
-Forbidden access, e.g. joining a room without permission, failed login.
-
-`M_UNKNOWN_TOKEN`
-The access or refresh token specified was not recognised.
-
-An additional response parameter, `soft_logout`, might be present on the
-response for 401 HTTP status codes. See [the soft logout
-section](#soft-logout) for more information.
-
-`M_MISSING_TOKEN`
-No access token was specified for the request.
-
-`M_USER_LOCKED`
-The account has been [locked](#account-locking) and cannot be used at this time.
-
-`M_USER_SUSPENDED`
-The account has been [suspended](#account-suspension) and can only be used for
-limited actions at this time.
+<!-- Please keep the error codes below in alphabetical order -->
 
 `M_BAD_JSON`
-Request contained valid JSON, but it was malformed in some way, e.g.
+: Request contained valid JSON, but it was malformed in some way, e.g.
 missing required keys, invalid values for keys.
 
-`M_NOT_JSON`
-Request did not contain valid JSON.
-
-`M_NOT_FOUND`
-No resource was found for this request.
+`M_FORBIDDEN`
+: Forbidden access, e.g. joining a room without permission, failed login.
 
 `M_LIMIT_EXCEEDED`
-Too many requests have been sent in a short period of time. Wait a while
+: Too many requests have been sent in a short period of time. Wait a while
 then try again. See [Rate limiting](#rate-limiting).
 
-`M_UNRECOGNIZED`
-The server did not understand the request. This is expected to be returned with
-a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
-code if the endpoint is implemented, but the incorrect HTTP method is used.
+`M_MISSING_TOKEN`
+: No access token was specified for the request.
 
-`M_UNKNOWN_DEVICE`
-{{% added-in v="1.17" %}} The device ID supplied by the application service does
-not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+`M_NOT_FOUND`
+: No resource was found for this request.
+
+`M_NOT_JSON`
+: Request did not contain valid JSON.
 
 `M_RESOURCE_LIMIT_EXCEEDED`
-The request cannot be completed because the homeserver has reached a
+: The request cannot be completed because the homeserver has reached a
 resource limit imposed on it. For example, a homeserver held in a shared
 hosting environment may reach a resource limit if it starts using too
 much memory or disk space. The error MUST have an `admin_contact` field
@@ -148,7 +127,63 @@ only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
 `M_UNKNOWN`
-An unknown error has occurred.
+: An unknown error has occurred.
+
+`M_UNKNOWN_DEVICE`
+: {{% added-in v="1.17" %}} The device ID supplied by the application service does
+not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+
+`M_UNKNOWN_TOKEN`
+: The access or refresh token specified was not recognised.
+
+: An additional response parameter, `soft_logout`, might be present on the
+response for 401 HTTP status codes. See [the soft logout
+section](#soft-logout) for more information.
+
+`M_UNRECOGNIZED`
+: The server did not understand the request. This is expected to be returned with
+a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
+code if the endpoint is implemented, but the incorrect HTTP method is used.
+
+`M_USER_LIMIT_EXCEEDED`
+: {{% added-in v="1.18" %}} The request cannot be completed because the user has
+exceeded (or the request would cause them to exceed) a limit associated with
+their account. For example, a user may have reached their allocated storage
+quota, reached a maximum number of allowed rooms, devices, or other
+account-scoped resources, or exceeded usage limits for specific features.
+
+: The error response MUST have an `info_uri` field (string), which is a URI
+that the client can present to the user to provide more context on the
+encountered limit and, if applicable, guidance on how to increase the limit.
+The homeserver MAY return different values for `info_uri` depending on the type
+of limit reached.
+
+: The error response MAY include a `can_upgrade` field (boolean, default `false`).
+If `true`, it indicates that the specific limit encountered can be increased,
+for example by upgrading the user's account tier. If absent or `false`, the
+limit is a hard limit that cannot be increased.
+
+: The HTTP status code will depend on depend on the particular endpoint.
+
+: Example response:
+
+  ```json
+  {
+    "errcode": "M_USER_LIMIT_EXCEEDED",
+    "error": "You have exceeded your storage quota of 10GB",
+    "info_uri": "https://example.com/homeserver/about?limit_type=quota",
+    "can_upgrade": true
+  }
+  ```
+
+`M_USER_LOCKED`
+: The account has been [locked](#account-locking) and cannot be used at this time.
+
+`M_USER_SUSPENDED`
+: The account has been [suspended](#account-suspension) and can only be used for
+limited actions at this time.
+
+<!-- Please keep the error codes above in alphabetical order -->
 
 #### Other error codes
 
@@ -156,93 +191,93 @@ The following error codes are specific to certain endpoints.
 
 <!-- TODO: move them to the endpoints that return them -->
 
-`M_UNAUTHORIZED`
-The request was not correctly authorized. Usually due to login failures.
+<!-- Please keep the error codes below in alphabetical order -->
 
-`M_USER_DEACTIVATED`
-The user ID associated with the request has been deactivated. Typically
-for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
+`M_BAD_STATE`
+: The state change requested cannot be performed, such as attempting to
+unban a user who is not banned.
 
-`M_USER_IN_USE`
-Encountered when trying to register a user ID which has been taken.
+`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
+: The user is unable to reject an invite to join the server notices room.
+See the [Server Notices](#server-notices) module for more information.
 
-`M_INVALID_USERNAME`
-Encountered when trying to register a user ID which is not valid.
+`M_CAPTCHA_INVALID`
+: The Captcha provided did not match what was expected.
 
-`M_ROOM_IN_USE`
-Sent when the room alias given to the `createRoom` API is already in
-use.
+`M_CAPTCHA_NEEDED`
+: A Captcha is required to complete the request.
 
-`M_INVALID_ROOM_STATE`
-Sent when the initial state given to the `createRoom` API is invalid.
+`M_EXCLUSIVE`
+: The resource being requested is reserved by an application service, or
+the application service making the request has not created the resource.
 
-`M_THREEPID_IN_USE`
-Sent when a threepid given to an API cannot be used because the same
-threepid is already in use.
-
-`M_THREEPID_NOT_FOUND`
-Sent when a threepid given to an API cannot be used because no record
-matching the threepid was found.
-
-`M_THREEPID_AUTH_FAILED`
-Authentication could not be performed on the third-party identifier.
-
-`M_THREEPID_DENIED`
-The server does not permit this third-party identifier. This may happen
-if the server only permits, for example, email addresses from a
-particular domain.
-
-`M_SERVER_NOT_TRUSTED`
-The client's request used a third-party server, e.g. identity server,
-that this server does not trust.
-
-`M_UNSUPPORTED_ROOM_VERSION`
-The client's request to create a room used a room version that the
-server does not support.
+`M_GUEST_ACCESS_FORBIDDEN`
+: The room or resource does not permit guests to access it.
 
 `M_INCOMPATIBLE_ROOM_VERSION`
-The client attempted to join a room that has a version the server does
+: The client attempted to join a room that has a version the server does
 not support. Inspect the `room_version` property of the error response
 for the room's version.
 
-`M_BAD_STATE`
-The state change requested cannot be performed, such as attempting to
-unban a user who is not banned.
-
-`M_GUEST_ACCESS_FORBIDDEN`
-The room or resource does not permit guests to access it.
-
-`M_CAPTCHA_NEEDED`
-A Captcha is required to complete the request.
-
-`M_CAPTCHA_INVALID`
-The Captcha provided did not match what was expected.
-
-`M_MISSING_PARAM`
-A required parameter was missing from the request.
-
 `M_INVALID_PARAM`
-A parameter that was specified has the wrong value. For example, the
+: A parameter that was specified has the wrong value. For example, the
 server expected an integer and instead received a string.
 
-`M_TOO_LARGE`
-The request or entity was too large.
+`M_INVALID_ROOM_STATE`
+: Sent when the initial state given to the `createRoom` API is invalid.
 
-`M_EXCLUSIVE`
-The resource being requested is reserved by an application service, or
-the application service making the request has not created the resource.
+`M_INVALID_USERNAME`
+: Encountered when trying to register a user ID which is not valid.
 
-`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
-The user is unable to reject an invite to join the server notices room.
-See the [Server Notices](#server-notices) module for more information.
+`M_MISSING_PARAM`
+: A required parameter was missing from the request.
 
-`M_THREEPID_MEDIUM_NOT_SUPPORTED`
-The homeserver does not support adding a third party identifier of the given medium.
+`M_ROOM_IN_USE`
+: Sent when the room alias given to the `createRoom` API is already in
+use.
+
+`M_SERVER_NOT_TRUSTED`
+: The client's request used a third-party server, e.g. identity server,
+that this server does not trust.
+
+`M_THREEPID_AUTH_FAILED`
+: Authentication could not be performed on the third-party identifier.
+
+`M_THREEPID_DENIED`
+: The server does not permit this third-party identifier. This may happen
+if the server only permits, for example, email addresses from a
+particular domain.
 
 `M_THREEPID_IN_USE`
-The third party identifier specified by the client is not acceptable because it is
+: The third party identifier specified by the client is not acceptable because it is
 already in use in some way.
 
+`M_THREEPID_MEDIUM_NOT_SUPPORTED`
+: The homeserver does not support adding a third party identifier of the given medium.
+
+`M_THREEPID_NOT_FOUND`
+: Sent when a threepid given to an API cannot be used because no record
+matching the threepid was found.
+
+`M_TOO_LARGE`
+: The request or entity was too large.
+
+`M_UNAUTHORIZED`
+: The request was not correctly authorized. Usually due to login failures.
+
+`M_UNSUPPORTED_ROOM_VERSION`
+: The client's request to create a room used a room version that the
+server does not support.
+
+`M_USER_DEACTIVATED`
+: The user ID associated with the request has been deactivated. Typically
+for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
+
+`M_USER_IN_USE`
+: Encountered when trying to register a user ID which has been taken.
+
+<!-- Please keep the error codes above in alphabetical order -->
+
 #### Rate limiting
 
 Homeservers SHOULD implement rate limiting to reduce the risk of being
@@ -434,6 +469,8 @@ The flow for auto-discovery is as follows:
 
 {{% http-api spec="client-server" api="support" %}}
 
+{{% http-api spec="client-server" api="policy_server" %}}
+
 ### API Versions
 
 Upon connecting, the Matrix client and server need to negotiate which version of the specification
@@ -523,7 +560,7 @@ endpoint.
 
 With the OAuth 2.0 API, a client can obtain an access token by using one of the
 [grant types](#grant-types) supported by the homeserver and authorizing the
-proper [scope](#scope), as demonstrated in the [login flow](#login-flow). To
+proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
 invalidate the access token the client must use [token revocation](#token-revocation).
 
 ### Using access tokens
@@ -1650,7 +1687,7 @@ For a client to be considered fully OAuth 2.0 aware it MUST:
   then the client MUST redirect users to manage their account at the [account
   management URL](#oauth-20-account-management), if available, instead of
   providing a native UI using the legacy API endpoints.
-  
+
   * If the user wishes to deactivate their account then the client MUST refer
     them to the account management URL.
   * If the user wishes to sign out a device other than its own then the client
@@ -1720,19 +1757,31 @@ authentication type.
 
 1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
 2. [Register the client with the homeserver](#client-registration).
-3. [Obtain an access token](#login-flow) by authorizing a [scope](#scope) for the client with the [authorization code grant](#authorization-code-grant).
+3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
+   the client with the [authorization code grant](#authorization-code-grant) or
+   [device authorization grant](#device-authorization-grant).
 4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
 5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
 
-#### Login flow
+#### Login flows
 
-Logging in with the OAuth 2.0 API should be done with the [authorization code
-grant](#authorization-code-grant). In the context of the Matrix specification,
-this means requesting a [scope](#scope) including full client-server API
-read/write access and allocating a device ID.
+Logging in and obtaining an access token with the OAuth 2.0 API should be done
+using either the [authorization code grant](#authorization-code-grant) or
+[device authorization grant](#device-authorization-grant). In the context of the
+Matrix specification, this means requesting a [scope](#scope) including full
+client-server API read/write access and allocating a device ID.
 
-Once the client has retrieved the [server metadata](#server-metadata-discovery),
-it needs to generate the following values:
+##### Authorization code flow
+
+This login flow uses the [authorization code grant](#authorization-code-grant)
+and is suitable for clients where the following criteria are met:
+
+- There is a web browser available for the user to complete authentication and
+  authorization.
+- The client can receive the callback via a redirect from the web browser.
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate the following values:
 
 - `device_id`: a unique identifier for this device; see the
   [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
@@ -1873,6 +1922,143 @@ Sample response:
 Finally, the client can call the  [`/whoami`](#get_matrixclientv3accountwhoami)
 endpoint to get the user ID that owns the access token.
 
+##### Device authorization flow
+
+{{% added-in v="1.18" %}}
+
+This flow uses the [device authorization grant](#device-authorization-grant) to
+allow clients to obtain an access token without needing to directly interact
+with a web browser. Instead, the user completes authorization on a web browser
+that can be a separate device.
+
+This is useful for devices with limited input
+capabilities (such as CLI applications or embedded devices) or where the
+redirect handling may be unreliable (such as a desktop applications).
+
+Once the client has retrieved the [server metadata](#server-metadata-discovery)
+the client needs to generate following value:
+
+- `device_id`: a unique identifier for this device; see the
+  [`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
+
+**Device authorization request**
+
+The client sends a `application/x-www-form-urlencoded` encoded `POST` request to
+the `device_authorization_endpoint` as defined in
+[RFC 8628 section 3.1](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1):
+
+| Parameter   | Value                                                          |
+|-------------|----------------------------------------------------------------|
+| `client_id` | The client ID returned from client registration.               |
+| `scope`     | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
+
+Sample device authorization request:
+
+```
+POST /oauth2/device HTTP/1.1
+Host: account.example.com
+Content-Type: application/x-www-form-urlencoded
+
+client_id=s6BhdRkqt3&scope=urn%3Amatrix%3Aclient%3Aapi%3A%2A%20urn%3Amatrix%3Aclient%3Adevice%3AAABBBCCCDDD
+```
+
+**Device authorization response**
+
+The server responds with a JSON object as defined in
+[RFC 8628 section 3.2](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2),
+containing:
+
+| Parameter                    |                                                                                                                                               |
+|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `device_code`                | The device verification code.                                                                                                                 |
+| `user_code`                  | An end-user verification code.                                                                                                                |
+| `verification_uri`           | The end-user verification URI on the authorization server.                                                                                    |
+| `verification_uri_complete`  | Optionally, the URI which doesn't require the user to manually type the `user_code`, designed for non-textual transmission.                   |
+| `expires_in`                 | The lifetime in seconds of the `device_code` and `user_code`.                                                                                 |
+| `interval`                   | The minimum number of seconds the client should wait between polling requests to the token endpoint. If omitted, clients should default to 5. |
+
+It is RECOMMENDED that the server provides a `verification_uri_complete` such
+that the user does not need to type in the `user_code`.
+
+Sample response:
+
+```json
+{
+  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
+  "user_code": "WDJB-MJHT",
+  "verification_uri": "https://account.example.com/link",
+  "verification_uri_complete": "https://account.example.com/link?user_code=WDJB-MJHT",
+  "expires_in": 1800,
+  "interval": 5
+}
+```
+
+**User interaction**
+
+The client conveys the `verification_uri_complete` (and/or `verification_uri`
+and `user_code`) to the user. How the client does this depends on the
+specific device characteristics and use case. For example:
+
+- A CLI application could display the `verification_uri` and `user_code` as text
+  for the user to type into their browser on another device.
+- An embedded device with a screen could encode the `verification_uri_complete`
+  (with fallback to `verification_uri`) as a QR code for the user to scan with
+  their phone.
+- A desktop application running on a platform that does not support callbacks
+  could launch the `verification_uri_complete` (with fallback to
+  `verification_uri`) in the system browser.
+
+The user opens the verification URI in a web browser, which may be on another
+device, and completes authentication and authorization.
+
+**Token polling**
+
+While the user is completing authorization, the client polls the
+`token_endpoint` for the outcome, at intervals no shorter than the `interval`
+value from the device authorization response.
+
+The poll request is a `POST` to the `token_endpoint` with the following
+parameters, encoded as `application/x-www-form-urlencoded` in the body:
+
+| Parameter     | Value                                                          |
+|---------------|----------------------------------------------------------------|
+| `grant_type`  | `urn:ietf:params:oauth:grant-type:device_code`                 |
+| `device_code` | The `device_code` from the device authorization response.      |
+| `client_id`   | The client ID returned from client registration.               |
+
+Sample token polling request:
+
+```
+POST /oauth2/token HTTP/1.1
+Host: account.example.com
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&client_id=s6BhdRkqt3
+```
+
+The server responds as defined in [RFC 8628 section
+3.5](https://datatracker.ietf.org/doc/html/rfc8628#section-3.5):
+
+- While authorization is pending, the server returns an `authorization_pending`
+  error (or `slow_down` if the client is polling too frequently).
+- If authorization is denied, the server returns an `access_denied` error.
+- If the device code expires, the server returns an `expired_token` error.
+- On successful authorization, the server returns a JSON object containing the
+  access token, token type, expiration time, refresh token, and scope:
+
+```json
+{
+  "access_token": "2YotnFZFEjr1zCsicMWpAA",
+  "token_type": "Bearer",
+  "expires_in": 299,
+  "refresh_token": "tGz3JOkF0XG5Qx2TlKWIA",
+  "scope": "urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD"
+}
+```
+
+Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
+endpoint to get the user ID that owns the access token.
+
 #### Token refresh flow
 
 Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
@@ -2203,6 +2389,7 @@ The client must also have obtained a `client_id` by [registering with the server
 
 This specification supports the following grant types:
 - [Authorization code grant](#authorization-code-grant)
+- {{% added-in v="1.18" %}} [Device authorization grant](#device-authorization-grant)
 - [Refresh token grant](#refresh-token-grant)
 
 ##### Authorization code grant
@@ -2227,18 +2414,34 @@ To use this grant, homeservers and clients MUST:
   Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
   for clients with an HTTPS redirect URI.
 
-###### User registration
+##### Device authorization grant
 
-Clients can signal to the server that the user desires to register a new account
-by initiating the authorization code grant with the `prompt=create` parameter
-set in the authorization request as defined in [Initiating User Registration via
-OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+{{% added-in v="1.18" %}}
 
-Whether the homeserver supports this parameter is advertised by the
-`prompt_values_supported` authorization server metadata.
+As per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), the device
+authorization grant lets clients on devices with limited input capabilities
+obtain an access token by having the user complete authorization on a separate
+device with a web browser.
 
-Servers that support this parameter SHOULD show the account registration UI in
-the browser.
+This grant requires the client to know the following [authorization server
+metadata](#server-metadata-discovery):
+
+- `device_authorization_endpoint`
+
+To use this grant, homeservers and clients MUST:
+
+- Support the device authorization grant as per
+  [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628).
+- Support the [refresh token grant](#refresh-token-grant).
+
+As with the [authorization code grant](#authorization-code-grant), when
+authorization is granted to a client, the homeserver MUST issue a refresh token
+to the client in addition to the access token. The access token and refresh
+token have the same lifetime constraints as described in the [refresh token
+grant](#refresh-token-grant) section.
+
+The full flow for using this grant is described in the
+[device authorization flow](#device-authorization-flow).
 
 ##### Refresh token grant
 
@@ -2345,6 +2548,22 @@ The server SHOULD return one of the following responses:
 - For other errors, the server returns a `400 Bad Request` response with error
   details
 
+#### User registration
+
+Clients can signal to the server that the user desires to register a new account
+by initiating the [authorization code grant](#authorization-code-grant) with the `prompt=create` parameter
+set in the authorization request as defined in [Initiating User Registration via
+OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
+
+Whether the homeserver supports this parameter is advertised by the
+`prompt_values_supported` authorization server metadata.
+
+Servers that support this parameter SHOULD show the account registration UI in
+the browser.
+
+The `prompt=create` parameter is not supported when using the [device
+authorization grant](#device-authorization-grant).
+
 #### Account management {id="oauth-20-account-management"}
 
 {{% added-in v="1.18" %}}
@@ -2901,19 +3120,20 @@ events they have already been sent, and choose to skip sending membership
 events for members whose membership has not changed. These are called
 'redundant membership events'. Clients may request that redundant membership
 events are always included in responses by setting `include_redundant_members`
-to true in the filter.
+to `true` in the filter.
 
 The expected pattern for using lazy-loading is currently:
 
--   Client performs an initial /sync with lazy-loading enabled, and
+-   Client performs an initial `/sync` with lazy-loading enabled, and
     receives only the membership events which relate to the senders of
     the events it receives.
 -   Clients which support display-name tab-completion or other
     operations which require rapid access to all members in a room
-    should call /members for the currently selected room, with an `?at`
-    parameter set to the /sync response's from token. The member list
-    for the room is then maintained by the state in subsequent
-    incremental /sync responses.
+    should call [`/members`](#get_matrixclientv3roomsroomidmembers) for
+    the currently selected room, with an `?at` parameter set to the
+    `/sync` response's `from` token. The member list for the room is
+    then maintained by the state in subsequent incremental `/sync`
+    responses.
 -   Clients which do not support tab-completion may instead pull in
     profiles for arbitrary users (e.g. read receipts, typing
     notifications) on demand by querying the room state or [`/profile`](#get_matrixclientv3profileuserid).
@@ -3128,8 +3348,8 @@ room at the start of the returned timeline. The response also includes a
 `next_batch` field, which should be used as the value of the `since`
 parameter in the next call to `/sync`. Finally, the response includes,
 for each room, a `prev_batch` field, which can be passed as a `from`/`to`
-parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier
-messages.
+parameter to the [`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
+API to retrieve earlier messages.
 
 For example, a `/sync` request might return a range of four events
 `E2`, `E3`, `E4` and `E5` within a given room, omitting two prior events
@@ -3148,7 +3368,8 @@ response to the previous call as the `since` parameter. The client
 should also pass a `timeout` parameter. The server will then hold open
 the HTTP connection for a short period of time waiting for new events,
 returning early if an event occurs. Only the `/sync` API (and the
-deprecated `/events` API) support long-polling in this way.
+deprecated [`/events`](#get_matrixclientv3events) API) support
+long-polling in this way.
 
 Continuing the example above, an incremental sync might report
 a single new event `E6`. The response can be visualised as:
@@ -3168,7 +3389,7 @@ containing only the most recent message events. A state "delta" is also
 returned, summarising any state changes in the omitted part of the
 timeline. The client may therefore end up with "gaps" in its knowledge
 of the message timeline. The client can fill these gaps using the
-[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API.
+[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages) API.
 
 Continuing our example, suppose we make a third `/sync` request asking for
 events since the last sync, by passing the `next_batch` token `x-y-z` as
@@ -3191,7 +3412,7 @@ The limited response includes a state delta which describes how the state
 of the room changes over the gap. This delta explains how to build the state
 prior to returned timeline (i.e. at `E7`) from the state the client knows
 (i.e. at `E6`). To close the gap, the client should make a request to
-[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
+[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
 with the query parameters `from=x-y-z` and `to=d-e-f`.
 
 {{% boxes/warning %}}
@@ -3320,7 +3541,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color
 ### Redactions
 
 Since events are extensible it is possible for malicious users and/or
-servers to add keys that are, for example offensive or illegal. Since
+servers to add keys that are, for example, offensive or illegal. Since
 some events cannot be simply deleted, e.g. membership events, we instead
 'redact' events. This involves removing all keys from an event that are
 not required by the protocol. This stripped down event is thereafter
@@ -3418,7 +3639,7 @@ This specification describes the following relationship types:
 * [Event replacements](#event-replacements).
 * [Event annotations](#event-annotations-and-reactions).
 * [Threads](#threading).
-* [References](#reference-relations)
+* [References](#reference-relations).
 
 #### Aggregations of child events
 
@@ -4058,6 +4279,7 @@ that profile.
 | [Read and Unread Markers](#read-and-unread-markers)        | Optional  | Optional | Optional | Optional | Optional |
 | [Guest Access](#guest-access)                              | Optional  | Optional | Optional | Optional | Optional |
 | [Moderation Policy Lists](#moderation-policy-lists)        | Optional  | Optional | Optional | Optional | Optional |
+| [Policy Servers](#policy-servers)                          | Optional  | Optional | Optional | Optional | Optional |
 | [OpenID](#openid)                                          | Optional  | Optional | Optional | Optional | Optional |
 | [Recently used emoji](#recently-used-emoji)                | Optional  | Optional | Optional | Optional | Optional |
 | [Reference Relations](#reference-relations)                | Optional  | Optional | Optional | Optional | Optional |
@@ -4160,6 +4382,7 @@ systems.
 {{% cs-module name="Room Upgrades" filename="room_upgrades" %}}
 {{% cs-module name="Server Notices" filename="server_notices" %}}
 {{% cs-module name="Moderation policy lists" filename="moderation_policies" %}}
+{{% cs-module name="Policy Servers" filename="policy_servers" %}}
 {{% cs-module name="Spaces" filename="spaces" %}}
 {{% cs-module name="Event replacements" filename="event_replacements" %}}
 {{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}

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

@@ -350,11 +350,14 @@ field, and as a result should remove her from its list of tracked users.
 When encryption is enabled in a room, files should be uploaded encrypted
 on the homeserver.
 
-In order to achieve this, a client should generate a single-use 256-bit
-AES key, and encrypt the file using AES-CTR. The counter should be
-64-bit long, starting at 0 and prefixed by a random 64-bit
-Initialization Vector (IV), which together form a 128-bit unique counter
-block.
+In order to achieve this, the client generates a single-use 256-bit AES
+key, and encrypts the file using AES-CTR. The counter is 64 bits long,
+starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
+which together form a 128-bit unique counter block.
+
+Clients MUST generate both the AES key and IV using a cryptographically 
+secure random source and MUST NOT use the same key or IV multiple
+times. The latter 64 bits of the 128-bit counter block MUST start at zero.
 
 {{% boxes/warning %}}
 An IV must never be used multiple times with the same key. This implies
@@ -364,13 +367,14 @@ same key and IV.
 {{% /boxes/warning %}}
 
 Then, the encrypted file can be uploaded to the homeserver. The key and
-the IV must be included in the room event along with the resulting
-`mxc://` in order to allow recipients to decrypt the file. As the event
+the IV are included in the room event along with the resulting `mxc://`
+in order to allow recipients to decrypt the file. As the event
 containing those will be Megolm encrypted, the server will never have
 access to the decrypted file.
 
-A hash of the ciphertext must also be included, in order to prevent the
-homeserver from changing the file content.
+A hash of the ciphertext MUST also be included, in order to prevent the
+homeserver from changing the file content. Clients MUST verify the hash
+before using the file contents.
 
 A client should send the data as an encrypted `m.room.message` event,
 using either `m.file` as the msgtype, or the appropriate msgtype for the
@@ -392,7 +396,7 @@ properties.
 | url       | string           | **Required.** The URL to the file.                                                             |
 | key       | JWK              | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.       |
 | iv        | string           | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.    |
-| hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
+| hashes    | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
 | v         | string           | **Required.** Version of the encrypted attachment's protocol. Must be `v2`.                    |
 
 `JWK`
@@ -633,7 +637,7 @@ request.
 
 The prompt for Bob to accept/reject Alice's request (or the unsupported method
 prompt) should be automatically dismissed 10 minutes after the `timestamp` (in
-the case of to-device messages) or `origin_ts` (in the case of in-room
+the case of to-device messages) or `origin_server_ts` (in the case of in-room
 messages) field or 2 minutes after Bob's client receives the message, whichever
 comes first, if Bob does not interact with the prompt. The prompt should
 additionally be hidden if an appropriate `m.key.verification.cancel` message is

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

@@ -0,0 +1,98 @@
+### Policy Servers
+
+{{% added-in v="1.18" %}}
+
+A Policy Server is a homeserver in the room designated to proactively check events
+before they are sent to the room/users. Rooms are not required to use a Policy
+Server (PS). Rooms which do use a Policy Server can prevent unwanted events from
+reaching users.
+
+{{% boxes/note %}}
+Room operators might prefer to use a "moderation bot" instead of a Policy Server.
+Moderation bots are reactive because they typically [redact](#redactions) events
+after they've already been sent.
+
+Room operators might also prefer to layer a moderation bot with a Policy Server
+for added protection.
+{{% /boxes/note %}}
+
+A room's Policy Server is designated by the [`m.room.policy`](#mroompolicy) state
+event described below. If the state event is not set in the room or is missing
+required fields, the room does *not* use a Policy Server. Similarly, if the server name in the state
+event has zero joined users in the room, the room also does *not* use a Policy
+Server.
+
+When the room is using a Policy Server, *all* events except for the `m.room.policy`
+state event itself are checked by that Policy Server. This includes membership
+events, power level changes, events from before the Policy Server was enabled,
+and non-state or non-empty `state_key` `m.room.policy` events.
+
+What a Policy Server checks for on an event is left as an implementation detail.
+
+{{% boxes/note %}}
+More information about how a Policy Server operates precisely is available in
+the [Server-Server API](/server-server-api/#policy-servers). Most notably, not
+every homeserver is a Policy Server, and not every Policy Server is a full
+homeserver.
+{{% /boxes/note %}}
+
+{{% event event="m.room.policy" %}}
+
+#### Client behaviour
+
+Clients do not interact with the Policy Server directly, but may need enough
+information to be able to set the `m.room.policy` state event. For this, a client
+can attempt to call [`/.well-known/matrix/policy_server`](#getwell-knownmatrixpolicy_server)
+on a user-provided server name. The returned information can then be used to
+populate the `m.room.policy` state event.
+
+{{% boxes/note %}}
+Clients are *not* required to use `/.well-known/matrix/policy_server` to populate the
+`m.room.policy` state event. If they have the required information from elsewhere,
+they can simply send the state event.
+{{% /boxes/note %}}
+
+#### Server behaviour
+
+See the [Policy Servers section of the Server-Server API](/server-server-api/#policy-servers).
+
+{{% boxes/note %}}
+If implementing your own Policy Server, see [MSC4284: Policy Servers](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4284-policy-servers.md)
+for additional security, implementation, and safety considerations.
+{{% /boxes/note %}}
+
+#### Security considerations
+
+{{% boxes/note %}}
+Portions of this section rely on context from the [Policy Servers section of the Server-Server API](/server-server-api/#policy-servers).
+{{% /boxes/note %}}
+
+By nature of being a proactive tool for a room, Policy Server can expect to be
+Denial of Service (DoS) targets. Policy Servers MUST be tolerant to DoS attacks.
+The scale of attack they need to tolerate is left as an implementation/deployment
+detail. A Policy Server dedicated to a small community might not have the same
+requirements as a Policy Server available for many communities to use.
+
+To help ensure that rooms can be used when their chosen Policy Server is inaccessible,
+the `m.room.policy` state event can be set *without* consulting the Policy Server.
+This in effect allows users with appropriate power levels to wipe the content of
+`m.room.policy`, disabling the Policy Server immediately.
+
+Policy Servers MUST have a joined user in the room to prevent rooms overloading
+or forcing a given server to act as a Policy Server. The Policy Server can evict
+itself from the room to also disable usage immediately.
+
+Events sent "before" the Policy Server was enabled can end up being recommended
+for exclusion by the Policy Server. This is expected behaviour to ensure new policies
+apply to events which took a while to send.
+
+Homeservers might not ask a Policy Server for a signature on an event before sending
+it to the room. Other compliant homeservers will request that signature instead,
+and layered tooling (like "moderation bots") can help remove events which bypass
+the room's Policy Server, if desirable.
+
+Homeservers might request and receive a valid signature for an event, but delay
+or never send the event. "Moderation bots" can monitor for clock drift on signed
+events, if desirable. A Policy Server implementation might also monitor for clock
+drift, though does need to consider that events can be backdated in ways beyond
+`origin_server_ts`.

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

@@ -107,7 +107,7 @@ flag to `true`.
 ```
 
 {{% boxes/note %}}
-Clients which are acutely aware of threads (they do not render threads, but are otherwise
+Clients which are aware of threads (they do not render threads, but are otherwise
 aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
 of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.
 

content/identity-service-api.md

@@ -70,54 +70,58 @@ the keys `error` and `errcode` MUST always be present.
 
 Some standard error codes are below:
 
-`M_NOT_FOUND`
-The resource requested could not be located.
-
-`M_MISSING_PARAMS`
-The request was missing one or more parameters.
-
-`M_INVALID_PARAM`
-The request contained one or more invalid parameters.
-
-`M_SESSION_NOT_VALIDATED`
-The session has not been validated.
-
-`M_NO_VALID_SESSION`
-A session could not be located for the given parameters.
-
-`M_SESSION_EXPIRED`
-The session has expired and must be renewed.
-
-`M_INVALID_EMAIL`
-The email address provided was not valid.
+<!-- Please keep the error codes below in alphabetical order -->
 
 `M_EMAIL_SEND_ERROR`
-There was an error sending an email. Typically seen when attempting to
+: There was an error sending an email. Typically seen when attempting to
 verify ownership of a given email address.
 
 `M_INVALID_ADDRESS`
-The provided third-party address was not valid.
+: The provided third-party address was not valid.
+
+`M_INVALID_EMAIL`
+: The email address provided was not valid.
+
+`M_INVALID_PARAM`
+: The request contained one or more invalid parameters.
+
+`M_MISSING_PARAMS`
+: The request was missing one or more parameters.
+
+`M_NO_VALID_SESSION`
+: A session could not be located for the given parameters.
+
+`M_NOT_FOUND`
+: The resource requested could not be located.
 
 `M_SEND_ERROR`
-There was an error sending a notification. Typically seen when
+: There was an error sending a notification. Typically seen when
 attempting to verify ownership of a given third-party address.
 
-`M_UNRECOGNIZED`
-The request contained an unrecognised value, such as an unknown token or
-medium.
+`M_SESSION_EXPIRED`
+: The session has expired and must be renewed.
 
-This is also used as the response if a server did not understand the request.
-This is expected to be returned with a 404 HTTP status code if the endpoint is
-not implemented or a 405 HTTP status code if the endpoint is implemented, but
-the incorrect HTTP method is used.
+`M_SESSION_NOT_VALIDATED`
+: The session has not been validated.
 
 `M_THREEPID_IN_USE`
-The third-party identifier is already in use by another user. Typically
+: The third-party identifier is already in use by another user. Typically
 this error will have an additional `mxid` property to indicate who owns
 the third-party identifier.
 
 `M_UNKNOWN`
-An unknown error has occurred.
+: An unknown error has occurred.
+
+`M_UNRECOGNIZED`
+: The request contained an unrecognised value, such as an unknown token or
+medium.
+
+: This is also used as the response if a server did not understand the request.
+This is expected to be returned with a 404 HTTP status code if the endpoint is
+not implemented or a 405 HTTP status code if the endpoint is implemented, but
+the incorrect HTTP method is used.
+
+<!-- Please keep the error codes above in alphabetical order -->
 
 ## Privacy
 

content/server-server-api.md

@@ -277,12 +277,12 @@ queried from multiple servers to mitigate against DNS spoofing.
 
 Every HTTP request made by a homeserver is authenticated using public
 key digital signatures. The request method, target and body are signed
-by wrapping them in a JSON object and signing it using the JSON signing
-algorithm. The resulting signatures are added as an Authorization header
-with an auth scheme of `X-Matrix`. Note that the target field should
-include the full path starting with `/_matrix/...`, including the `?`
-and any query parameters if present, but should not include the leading
-`https:`, nor the destination server's hostname.
+by wrapping them in a JSON object and signing it using the [JSON signing
+algorithm](/appendices#signing-json). The resulting signatures are added
+as an Authorization header with an auth scheme of `X-Matrix`. Note that
+the target field should include the full path starting with `/_matrix/...`,
+including the `?` and any query parameters if present, but should not
+include the leading `https:`, nor the destination server's hostname.
 
 Step 1 sign JSON:
 
@@ -473,6 +473,9 @@ server must ensure that the event:
     otherwise it is rejected.
 6.  Passes authorization rules based on the current state of the room,
     otherwise it is "soft failed".
+7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
+   by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
+   otherwise it is "soft failed".
 
 Further details of these checks, and how to handle failures, are
 described below.
@@ -689,6 +692,11 @@ then any new event `D'` will not reference `C`:
     |
     D'
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
+{{% /boxes/note %}}
+
 #### Retrieving event authorization information
 
 The homeserver may be missing event authorization information, or wish
@@ -1277,6 +1285,171 @@ endpoint MUST be protected as follows:
         room ID MUST be ignored if the sending server is denied access to
         the room identified by that ID.
 
+The following endpoints MAY be protected:
+
+-   [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - {{< added-in v="1.18" >}}
+    Protected if the server is tracking the DAG and chooses to enforce the ACL.
+
+
+## Policy Servers
+
+{{% added-in v="1.18" %}}
+
+Policy Servers are an available tool for rooms to add proactive protections. Rooms
+which use a Policy Server (PS) can prevent unwanted events from reaching users. Rooms
+are not required to use a Policy Server, and can disable it any time after enabling
+it.
+
+For a homeserver to be a Policy Server, it MUST implement the following functionality
+of the Server-Server API:
+
+* [Normal server name resolution](#resolving-server-names).
+* [Publishing a signing key](#publishing-keys).
+* [Request authentication](#authentication).
+* Being able to [make and send join requests](#joining-rooms).
+* Receiving and processing [`POST /_matrix/policy/v1/sign`](#post_matrixpolicyv1sign)
+  requests.
+
+All other functionality and endpoints are optional for a Policy Server.
+
+{{% boxes/note %}}
+Though a Policy Server is not required to implement the full Server-Server API
+surface, some functionality may be desirable to implement anyway:
+
+* Receiving [invites](#inviting-to-a-room) can make it easier to add the Policy
+  Server to a room.
+* Receiving [transactions](#transactions) is recommended to avoid remote servers
+  flagging the Policy Server as "offline", even if the contents are discarded.
+* Receiving [device lookups](#get_matrixfederationv1userdevicesuserid) can also
+  help reduce remote servers flagging the Policy Server as "offline".
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+Policy Servers are *not* required to track the DAG for a room. Policy Servers
+might be optimized for content moderation and therefore do not need knowledge of
+the DAG.
+{{% /boxes/note %}}
+
+### Determining if a Policy Server is enabled in a room
+
+For a room to be considered as "using" a Policy Server, *all* of the following
+conditions MUST be true:
+
+* The *current state* for the room has a valid [`m.room.policy`](/client-server-api/#mroompolicy)
+  state event with empty state key. Valid means `content` contains at least:
+  * A string value for `via`.
+  * An object value for `public_keys` containing at least a string value for
+    `ed25519`.
+* The server name denoted by the `m.room.policy` state event's `via` has at least
+  one joined user in the room in *current state*. The user does not need any
+  special permissions or power levels in the room.
+
+If a room has enabled a Policy Server, *all* servers in that room MUST [ask that
+Policy Server](#asking-for-a-policy-server-signature-on-an-event) for a signature
+before sending an event. If the Policy Server refuses to sign the event being
+sent, servers SHOULD fail to send that event as per the [validation rules](#validating-policy-server-signatures).
+
+{{% boxes/note %}}
+"Current state" shares the same definition as [soft failure](#soft-failure).
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+Policy Servers MUST have at least one joined user in the room to give the Policy
+Server agency in whether it serves that role for the room. Otherwise, a room
+would be able to force a Policy Server to participate and then overwhelm it.
+{{% /boxes/note %}}
+
+### Validating Policy Server signatures
+
+Policy Servers use signatures to indicate whether an event was checked and is
+recommended for inclusion in a room. The Policy Server's recommendation does *not*
+affect the authorization rules for an event, but does affect whether homeservers
+[soft fail](#soft-failure) or refuse to actually go forward with sending an event.
+
+If a room has disabled (or never enabled) a Policy Server, events are recommended
+for inclusion and subject to normal authorization rules.
+
+{{% boxes/note %}}
+Because the Policy Server is not asked to sign [`m.room.policy`](/client-server-api/#mroompolicy)
+state events with empty string `state_key`s, those events will not have a Policy
+Server signature. Those events are by default recommended for inclusion and still
+subject to normal authorization rules.
+
+All other events SHOULD have a valid Policy Server signature when a Policy Server
+is enabled in the room, including non-state `m.room.policy` events and `m.room.policy`
+state events with non-empty `state_key`s. This also includes state events like
+membership and power level changes.
+{{% /boxes/note %}}
+
+If a room has enabled a Policy Server, the Policy Server's signature appears
+alongside the normal [event signatures](#signing-events), though uses a public
+key from the room's `m.room.policy` state event.
+
+{{% boxes/note %}}
+Currently, only Ed25519 keys are supported by homeservers. The Key ID for the
+`ed25519` key in `m.room.policy` is *always* `ed25519:policy_server`.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+By embedding the Policy Server's public key into room state, the Policy Server
+does not need to be online or have its keys cached by a notary in order to validate
+an event.
+{{% /boxes/note %}}
+
+{{% boxes/warning %}}
+The Policy Server's [published signing key](#publishing-keys) SHOULD NOT be the
+same key contained in the `m.room.policy` state event. This is to keep "can send
+federation traffic" and "can recommend events for inclusion" separate, and to
+allow rooms to revoke the Policy Server's key without cooperation of the Policy
+Server.
+
+If the Policy Server is acting as a normal homeserver and attempting to send an
+event, that event will require a signature from the server's published signing
+key alongside the Policy Server signature described in this section.
+{{% /boxes/warning %}}
+
+If the Policy Server's signature is valid, the event is recommended for inclusion
+in the room, and is still subject to normal authorization rules.
+
+If the Policy Server's signature is invalid or missing, the homeserver SHOULD
+[ask for a new signature](#asking-for-a-policy-server-signature-on-an-event). If
+the event still does not have a valid Policy Server signature, the event is *not*
+recommended for inclusion and the homeserver SHOULD:
+
+* If applicable, reject the Client-Server API request which was generating the
+  event. If the Policy Server returned an error, that error SHOULD be provided
+  to the client verbatim. The event the client was attempting to send SHOULD be
+  discarded and not processed/sent any further.
+* If the event was received over federation or the homeserver sends a local client's
+  event anyway, [soft fail](#soft-failure) the event.
+
+{{% boxes/note %}}
+For clarity, an event which lacks a valid Policy Server signature is still subject
+to normal authorization rules.
+{{% /boxes/note %}}
+
+{{% boxes/note %}}
+When a Policy Server's signature is invalid, a new one is requested because the
+Policy Server's key may have rotated between the event being signed and the event
+being checked.
+
+Because the key is contained in the `m.room.policy` state event, if the Policy
+Server rotates its key without the room also updating the state event, events
+will be flagged as not recommended for inclusion. This is expected behaviour.
+{{% /boxes/note %}}
+
+### Asking for a Policy Server signature on an event
+
+Per [above](#determining-if-a-policy-server-is-enabled-in-a-room), if a room has
+a Policy Server enabled, *all* servers in the room MUST ask the Policy Server to
+sign their events before sending them to clients and servers.
+
+After asking for a signature, homeservers SHOULD [validate](#validating-policy-server-signatures)
+the returned signature before continuing to send events. If the Policy Server
+returns an error, the event SHOULD NOT be sent to clients and servers.
+
+{{% http-api spec="server-server" api="room_policy" %}}
+
 ## Signing Events
 
 Signing events is complicated by the fact that servers can choose to
@@ -1300,6 +1473,12 @@ The signature is then copied back to the original event object.
 For an example of a signed event, see the [room version
 specification](/rooms).
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) MUST [ask](#asking-for-a-policy-server-signature-on-an-event)
+the Policy Server for a signature too.
+{{% /boxes/note %}}
+
 ### Validating hashes and signatures on received events
 
 When a server receives an event over federation from another server, the
@@ -1334,6 +1513,12 @@ only been given a redacted version of the event. To enforce this, the
 receiving server should use the redacted copy it calculated rather than
 the full copy it received.
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) have [additional](#validating-policy-server-signatures)
+signature validation requirements.
+{{% /boxes/note %}}
+
 ### Calculating the reference hash for an event
 
 The *reference hash* of an event covers the essential fields of an

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

@@ -24,8 +24,9 @@ allOf:
       room_id:
         description: The ID of the room associated with this event.
         type: string
+        format: mx-room-id
+        pattern: "^!"
         example: '!jEsUZKDJdhlrceRyVU:example.org'
-
       unsigned:
         properties:
             redacted_because:
@@ -43,6 +44,6 @@ allOf:
                 "unsigned": {
                   "age": 1257,
                 }
-            }
+              }
     required:
       - room_id

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

@@ -28,6 +28,8 @@ properties:
   event_id:
     description: The globally unique identifier for this event.
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
     example: '$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45'
   type:
     description: The type of the event.
@@ -47,6 +49,8 @@ properties:
   sender:
     description: Contains the fully-qualified ID of the user who sent this event.
     type: string
+    format: mx-user-id
+    pattern: "^@"
     example: "@example:example.org"
   origin_server_ts:
     description: |-

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

@@ -23,14 +23,16 @@ properties:
   not_senders:
     description: A list of sender IDs to exclude. If this list is absent then no senders
       are excluded. A matching sender will be excluded even if it is listed in the
-      `'senders'` filter.
+      `senders` filter.
     items:
       type: string
+      format: mx-user-id
+      pattern: "^@"
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
       event types are excluded. A matching type will be excluded even if it is listed
-      in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
+      in the `types` filter. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
@@ -40,10 +42,12 @@ properties:
       senders are included.
     items:
       type: string
+      format: mx-user-id
+      pattern: "^@"
     type: array
   types:
     description: A list of event types to include. If this list is absent then all
-      event types are included. A `'*'` can be used as a wildcard to match any sequence
+      event types are included. A `*` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

data/api/client-server/definitions/m.relates_to.yaml

@@ -39,5 +39,7 @@ properties:
       such.
   event_id:
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
     description: The event ID of the event that this event relates to.
 required: ['rel_type', 'event_id']

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

@@ -39,16 +39,20 @@ allOf:
         for more information. Defaults to `false`.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
-        are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+        are excluded. A matching room will be excluded even if it is listed in the `rooms`
         filter.
       items:
         type: string
+        format: mx-room-id
+        pattern: "^!"
       type: array
     rooms:
       description: A list of room IDs to include. If this list is absent then all rooms
         are included.
       items:
         type: string
+        format: mx-room-id
+        pattern: "^!"
       type: array
     contains_url:
       type: boolean

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

@@ -17,15 +17,15 @@ properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
       fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
-      to include. So ['content.body'] will include the 'body' field of the 'content' object.
+      to include. So `['content.body']` will include the `body` field of the `content` object.
       A server may include more fields than were requested.
     items:
       type: string
     type: array
   event_format:
-    description: The format to use for events. 'client' will return the events in
-      a format suitable for clients. 'federation' will return the raw event as received
-      over federation. The default is 'client'.
+    description: The format to use for events. `client` will return the events in
+      a format suitable for clients. `federation` will return the raw event as received
+      over federation. The default is `client`.
     enum:
     - client
     - federation
@@ -45,11 +45,13 @@ properties:
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
-          are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+          are excluded. A matching room will be excluded even if it is listed in the `rooms`
           filter. This filter is applied before the filters in `ephemeral`,
           `state`, `timeline` or `account_data`
         items:
           type: string
+          format: mx-room-id
+          pattern: "^!"
         type: array
       rooms:
         description: A list of room IDs to include. If this list is absent then all rooms
@@ -57,6 +59,8 @@ properties:
           `state`, `timeline` or `account_data`
         items:
           type: string
+          format: mx-room-id
+          pattern: "^!"
         type: array
       ephemeral:
         allOf:
@@ -65,7 +69,7 @@ properties:
           events that appear in the `ephemeral` property in the `/sync`
           response.
       include_leave:
-        description: Include rooms that the user has left in the sync, default false
+        description: Include rooms that the user has left in the sync. Defaults to `false`.
         type: boolean
       state:
         type: object

data/api/client-server/filter.yaml

@@ -36,6 +36,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
       requestBody:
         content:
           application/json:
@@ -130,6 +132,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: filterId
           description: The filter ID to download.

data/api/client-server/list_public_rooms.yaml

@@ -226,7 +226,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string
@@ -277,4 +277,4 @@ components:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery
     accessTokenBearer:
-      $ref: definitions/security.yaml#/accessTokenBearer
+      $ref: definitions/security.yaml#/accessTokenBearer

data/api/client-server/login.yaml

@@ -163,7 +163,7 @@ paths:
                     known client device, a new device will be created. The given
                     device ID must not be the same as a
                     [cross-signing](/client-server-api/#cross-signing) key ID.
-                    The server will auto-generate a device_id
+                    The server will auto-generate a `device_id`
                     if this is not specified.
                 initial_device_display_name:
                   type: string

data/api/client-server/message_pagination.yaml

@@ -37,6 +37,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: from
           x-changedInMatrixVersion:

data/api/client-server/oauth_server_metadata.yaml

@@ -67,8 +67,7 @@ paths:
                     type: string
                     format: uri
                     description: |-
-                      URL of the token endpoint, necessary to use the authorization code grant and
-                      the refresh token grant.
+                      URL of the token endpoint, used by the grants.
                   revocation_endpoint:
                     type: string
                     format: uri
@@ -101,6 +100,10 @@ paths:
                       This array MUST contain at least the `authorization_code` and `refresh_token`
                       values, for clients to be able to use the authorization code grant and refresh
                       token grant, respectively.
+
+                      {{% added-in v="1.18" %}} It MAY also contain
+                      `urn:ietf:params:oauth:grant-type:device_code` to indicate support for the
+                      [device authorization grant](/client-server-api/#device-authorization-grant).
                     items:
                       type: string
                       description: A grant type that the server supports.
@@ -165,6 +168,14 @@ paths:
                         - "org.matrix.account_deactivate"
                         - "org.matrix.cross_signing_reset"
                       description: An action that the account management URL supports.
+                  device_authorization_endpoint:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the device authorization endpoint, as defined in
+                      [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use
+                      the [device authorization grant](/client-server-api/#device-authorization-grant).
                 required:
                   - issuer
                   - authorization_endpoint
@@ -180,9 +191,10 @@ paths:
                   "authorization_endpoint": "https://account.example.com/oauth2/auth",
                   "token_endpoint": "https://account.example.com/oauth2/token",
                   "registration_endpoint": "https://account.example.com/oauth2/clients/register",
+                  "device_authorization_endpoint": "https://account.example.com/oauth2/device",
                   "revocation_endpoint": "https://account.example.com/oauth2/revoke",
                   "response_types_supported": ["code"],
-                  "grant_types_supported": ["authorization_code", "refresh_token"],
+                  "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
                   "response_modes_supported": ["query", "fragment"],
                   "code_challenge_methods_supported": ["S256"],
                   "account_management_uri": "https://account.example.com/manage",

data/api/client-server/old_sync.yaml

@@ -148,6 +148,8 @@ paths:
                       properties:
                         room_id:
                           type: string
+                          format: mx-room-id
+                          pattern: "^!"
                           description: The ID of this room.
                         membership:
                           type: string
@@ -337,6 +339,8 @@ paths:
           example: $asfDuShaf7Gafaw:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
       responses:
         "200":
           description: The full event.

data/api/client-server/password_management.yaml

@@ -57,7 +57,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether the user's other access tokens, and their associated devices, should be
-                    revoked if the request succeeds. Defaults to true.
+                    revoked if the request succeeds. Defaults to `true`.
 
                     When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
                     for the user's remaining devices.

data/api/client-server/policy_server.yaml

@@ -0,0 +1,82 @@
+# Copyright 2026 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 Policy Server Discovery API
+  version: 1.0.0
+paths:
+  /matrix/policy_server:
+    get:
+      summary: Gets information about a Policy Server's configuration, if available.
+      description: |-
+        Gets public key information for a [Policy Server](/client-server-api/#policy-servers).
+
+        {{% boxes/note %}}
+        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this endpoint should be accessed with the hostname of the Policy Server's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/policy_server`.
+        {{% /boxes/note %}}
+
+        Note that this endpoint is not necessarily handled by the homeserver or
+        Policy Server. It may be served by another webserver.
+      operationId: getWellknownPolicy
+      x-addedInMatrixVersion: "1.18"
+      responses:
+        "200":
+          description: |-
+            Public keys for the Policy Server. Can be supplied to the [`m.room.policy`](/client-server-api/#mroompolicy)
+            state event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  public_keys:
+                    type: object
+                    description: |-
+                      The unpadded base64-encoded public keys for the Policy Server. MUST contain
+                      at least `ed25519`.
+                    properties:
+                      ed25519:
+                        type: string
+                        description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+                    required: ['ed25519']
+                    additionalProperties:
+                      type: string
+                      description: The unpadded base64-encoded public key for the key algorithm.
+                required: ["public_keys"]
+              examples:
+                response:
+                  value:
+                    {
+                      "public_keys": {
+                        "ed25519": "6yhHGKhCiXTSEN2ksjV7kX_N6rBQZ3Xb-M7LlC6NS-s"
+                      }
+                    }
+        "404":
+          description: No policy server information available.
+      tags:
+        - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /.well-known

data/api/client-server/redaction.yaml

@@ -43,13 +43,17 @@ paths:
           example: "!637q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventId
-          description: The ID of the event to redact
+          description: The ID of the event to redact.
           required: true
-          example: bai2b1i9:matrix.org
+          example: $bai2b1i9:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
         - in: path
           name: txnId
           description: |-
@@ -82,6 +86,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
               examples:
                 response:

data/api/client-server/registration.yaml

@@ -126,7 +126,7 @@ paths:
                   description: |-
                     ID of the client device. If this does not correspond to a
                     known client device, a new device will be created. The server
-                    will auto-generate a device_id if this is not specified.
+                    will auto-generate a `device_id` if this is not specified.
                   example: GHTYAJCE
                 initial_device_display_name:
                   type: string
@@ -139,11 +139,11 @@ paths:
                   description: |-
                     If true, an `access_token` and `device_id` should not be
                     returned from this call, therefore preventing an automatic
-                    login. Defaults to false.
+                    login. Defaults to `false`.
                   example: false
                 refresh_token:
                   type: boolean
-                  description: If true, the client supports refresh tokens.
+                  description: If `true`, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
         required: true
       responses:

data/api/client-server/relations.yaml

@@ -233,6 +233,8 @@ components:
       example: "!636q39766251:matrix.org"
       schema:
         type: string
+        format: mx-room-id
+        pattern: "^!"
     eventId:
       in: path
       name: eventId
@@ -241,6 +243,8 @@ components:
       example: $asfDuShaf7Gafaw
       schema:
         type: string
+        format: mx-event-id
+        pattern: "^\\$"
     from:
       in: query
       name: from

data/api/client-server/report_content.yaml

@@ -25,6 +25,15 @@ paths:
         the appropriate people. How such information is delivered is left up to
         implementations. The caller is not required to be joined to the room to
         report it.
+
+        Clients could infer whether a reported room exists based on the 404 response.
+        Homeservers that wish to conceal this information MAY return 200 responses
+        regardless of the existence of the reported room.
+
+        Furthermore, it might be possible for clients to deduce whether a reported
+        room exists by timing the response. This is because only a report for an
+        existing room will require the homeserver to do further processing. To
+        combat this, homeservers MAY add a random delay when generating a response.
       operationId: reportRoom
       parameters:
         - in: path
@@ -52,6 +61,11 @@ paths:
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
+      x-changedInMatrixVersion:
+        1.18: |
+          Servers MAY prevent room ID enumeration by using the 200 response
+          regardless of the existence of the reported room and/or by adding
+          a random delay when generating responses.
       responses:
         "200":
           description: The room has been reported successfully.
@@ -91,6 +105,10 @@ paths:
         the appropriate people. The caller must be joined to the room to report
         it.
 
+        Clients could infer whether a reported event or room exists based on the 404
+        response. Homeservers that wish to conceal this information MAY return 200
+        responses regardless of the existence of the reported event or room.
+
         Furthermore, it might be possible for clients to deduce whether a reported
         event exists by timing the response. This is because only a report for an
         existing event will require the homeserver to do further processing. To
@@ -117,15 +135,9 @@ paths:
             schema:
               type: object
               example: {
-                "score": -100,
                 "reason": "this makes me sad"
               }
               properties:
-                score:
-                  type: integer
-                  description: |-
-                    The score to rate this content as where -100 is most offensive
-                    and 0 is inoffensive.
                 reason:
                   type: string
                   description: The reason the content is being reported.
@@ -136,6 +148,10 @@ paths:
       x-changedInMatrixVersion:
         1.8: |
           This endpoint now requires the user to be joined to the room.
+        1.18: |
+          The `score` request parameter was removed. Additionally, servers
+          may prevent event/room ID enumeration by using the 200 response
+          regardless of the existence of the reported event/room.
       responses:
         "200":
           description: The event has been reported successfully.

data/api/client-server/room_event_by_timestamp.yaml

@@ -56,6 +56,8 @@ paths:
           example: "!636q39766251:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: ts
           description: |-
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: The ID of the event found
                   origin_server_ts:
                     type: integer

data/api/client-server/room_initial_sync.yaml

@@ -27,6 +27,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The current state of the room
@@ -38,6 +40,8 @@ paths:
                 properties:
                   room_id:
                     type: string
+                    format: mx-room-id
+                    pattern: "^!"
                     description: The ID of this room.
                   membership:
                     type: string

data/api/client-server/room_send.yaml

@@ -31,7 +31,7 @@ paths:
 
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
-        [Room Events](/client-server-api/#room-events) for the m. event specification.
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
 
         Homeservers MUST allow clients to send `m.room.redaction` events with this
         endpoint for all room versions. In rooms with a version older than 11 they
@@ -49,6 +49,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of event to send.
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
                 required:
                   - event_id

data/api/client-server/room_state.yaml

@@ -49,6 +49,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of event to send.
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
                 required:
                   - event_id

data/api/client-server/rooms.yaml

@@ -34,6 +34,8 @@ paths:
           example: "!636q39766251:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventId
           description: The event ID to get.
@@ -41,6 +43,8 @@ paths:
           example: $asfDuShaf7Gafaw:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
       responses:
         "200":
           description: The full event.
@@ -89,6 +93,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of state to look up.
@@ -158,6 +164,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The current state of the room
@@ -211,6 +219,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: at
           description: |-
@@ -305,6 +315,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []

data/api/client-server/sync.yaml

@@ -209,6 +209,8 @@ paths:
                                       field may be omitted.
                                     items:
                                       type: string
+                                      format: mx-user-id
+                                      pattern: "^@"
                                   m.joined_member_count:
                                     type: integer
                                     description: |-

data/api/server-server/public_rooms.yaml

@@ -49,7 +49,7 @@ paths:
           name: include_all_networks
           description: |-
             Whether or not to include all networks/protocols defined by application
-            services on the homeserver. Defaults to false.
+            services on the homeserver. Defaults to `false`.
           example: false
           schema:
             type: boolean
@@ -121,7 +121,7 @@ paths:
                   type: boolean
                   description: |-
                     Whether or not to include all known networks/protocols from
-                    application services on the homeserver. Defaults to false.
+                    application services on the homeserver. Defaults to `false`.
                   example: false
                 third_party_instance_id:
                   type: string

data/api/server-server/room_policy.yaml

@@ -0,0 +1,172 @@
+# Copyright 2026 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 Room Policy API
+  version: 1.0.0
+paths:
+  "/sign":
+    post:
+      summary: Asks the Policy Server to sign an event.
+      description: |-
+        A server is a Policy Server if it implements this endpoint, among
+        [other requirements](/server-server-api/#policy-servers). This endpoint
+        is otherwise optional. See [Unsupported Endpoints](/server-server-api/#unsupported-endpoints)
+        for details on how to exclude implementation of this endpoint.
+
+        This endpoint MUST NOT be called for events which have a type of `m.room.policy`
+        and an empty string `state_key`. All other events, including state events,
+        non-state `m.room.policy` events, and `m.room.policy` state events with
+        non-empty string `state_key`s are processed by this endpoint.
+
+        Whether a signature is required by a Policy Server further depends on whether
+        the room has [enabled a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room).
+
+        {{% boxes/note %}}
+        The Policy Server MAY respond with *any* of the defined errors to indicate
+        failure. For example, if it wishes to hide whether it knows about a room,
+        it MAY return `400 M_FORBIDDEN` instead (or, it MAY sign the event anyway).
+        {{% /boxes/note %}}
+
+        What the Policy Server checks for when calling this endpoint is left as an
+        implementation detail.
+      operationId: askPolicyServerToSign
+      security:
+        - signedRequest: []
+      parameters: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              title: PDU
+              description: |-
+                The [PDU](/server-server-api/#pdus) to request a signature for. The event format
+                varies depending on the room version - check the [room version specification](/rooms)
+                for precise event formats.
+              properties: {}
+              example:
+                $ref: examples/minimal_pdu.json
+        required: true
+      responses:
+        "200":
+          description: |-
+            The Policy Server has signed the event, indicating that it recommends the event for
+            inclusion in the room. Only the Policy Server's signature is returned. This signature
+            is to be added to the event before sending or processing the event further.
+
+            `ed25519:policy_server` is *always* used for Ed25519 signatures.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                required: []
+                example: {
+                  "policy.example.org": {
+                    "ed25519:policy_server": "zLFxllD0pbBuBpfHh8NuHNaICpReF/PAOpUQTsw+bFGKiGfDNAsnhcP7pbrmhhpfbOAxIdLraQLeeiXBryLmBw"
+                  }
+                }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "400":
+          description: |-
+            The request is invalid or the Policy Server refuses to sign the event.
+
+            Error codes include:
+            * `M_BAD_JSON` - The supplied PDU-formatted event was improperly formatted. For example,
+              missing keys required for the room version.
+            * `M_NOT_JSON` - The body wasn't JSON.
+            * `M_FORBIDDEN` - The Policy Server refuses to sign the event.
+          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_FORBIDDEN",
+                    "error": "The message appears to contain possible spam"
+                  }
+        "403":
+          description: |-
+            The calling server is [ACL'd](/server-server-api/#server-access-control-lists-acls).
+
+            {{% boxes/note %}}
+            This endpoint is optionally affected by server ACLs. The Policy Server
+            MAY NOT apply an ACL to the request, especially if the Policy Server
+            is not tracking the room DAG.
+            {{% /boxes/note %}}
+          content:
+            application/json:
+              schema:
+                allOf:
+                    # XXX: We should move error definitions into a more generic place.
+                  - $ref: ../client-server/definitions/errors/error.yaml
+                  - type: object
+                    properties:
+                      errcode:
+                        description: "The `M_FORBIDDEN` error code."
+                    required: [errcode]
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Your server is not allowed to request a signature."
+                  }
+        "404":
+          description: |-
+            The server is not a Policy Server, or the room is unknown/not protected by the Policy Server.
+
+            Error codes include:
+            * `M_NOT_FOUND` - The room is not known or is not protected by the Policy Server.
+            * `M_UNRECOGNIZED` - The server is not a Policy Server. See [Unsupported Endpoints](/server-server-api/#unsupported-endpoints)
+              for more detail.
+          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_FOUND",
+                    "error": "Unknown room"
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/policy/v1
+components:
+  securitySchemes:
+    signedRequest:
+      $ref: definitions/security.yaml#/signedRequest
+  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
+

data/event-schemas/examples/m.room.message$m.image.yaml

@@ -7,7 +7,8 @@
         "h": 398,
         "w": 394,
         "mimetype": "image/jpeg",
-        "size": 31037
+        "size": 31037,
+        "is_animated": false
     },
     "url": "mxc://example.org/JWEIFJgwEIhweiWJE",
     "msgtype": "m.image"

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

@@ -0,0 +1,11 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.room.policy",
+  "state_key": "",
+  "content": {
+    "via": "policy.example.org",
+    "public_keys": {
+      "ed25519": "6yhHGKhCiXTSEN2ksjV7kX_N6rBQZ3Xb-M7LlC6NS-s"
+    }
+  }
+}

data/event-schemas/examples/m.sticker.yaml

@@ -9,7 +9,8 @@
         "mimetype": "image/png",
         "h": 200,
         "w": 140,
-        "size": 73602
+        "size": 73602,
+        "is_animated": true
       },
       "h": 200,
       "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP",

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

@@ -20,10 +20,13 @@ properties:
       The signatures are calculated using the process described at
       [Signing JSON](/appendices/#signing-json).
     type: object
-    additionalProperties:
-      type: object
-      additionalProperties:
-        type: string
+    patternProperties:
+      "":
+        x-pattern-format: mx-server-name
+        type: object
+        additionalProperties:
+          type: string
+          format: mx-unpadded-base64
     example: {
       "magic.forest": {
         "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"

data/event-schemas/schema/core-event-schema/event.yaml

@@ -7,8 +7,7 @@ properties:
       When interacting with the REST API, this is the HTTP body.
     type: object
   type:
-    description: The type of event. This SHOULD be namespaced similar to Java package
-      naming conventions e.g. 'com.example.subdomain.event.type'
+    description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
     type: string
 required:
   - type

data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -34,5 +34,19 @@ properties:
     allOf:
       - $ref: thumbnail_info.yaml
     description: Metadata about the image referred to in `thumbnail_url`.
+  is_animated:
+    x-addedInMatrixVersion: "1.18"
+    description: |-
+      If this flag is `true`, the original image SHOULD be assumed to be
+      animated. If this flag is `false`, the original image SHOULD be assumed to
+      NOT be animated.
+
+      If a sending client is unable to determine whether an image is animated,
+      it SHOULD leave the flag unset.
+
+      Receiving clients MAY use this flag to optimize whether to download the
+      original image rather than a thumbnail if it is animated, but they SHOULD
+      NOT trust this flag.
+    type: boolean
 title: ImageInfo
 type: object

data/event-schemas/schema/core-event-schema/room_event.yaml

@@ -11,5 +11,7 @@ allOf:
         The ID of the room associated with this event. Will not be present on events
         that arrive through `/sync`, despite being required everywhere else.
       type: string
+      format: mx-room-id
+      pattern: "^!"
   required:
   - room_id

data/event-schemas/schema/core-event-schema/stripped_state.yaml

@@ -39,6 +39,8 @@ properties:
   sender:
     description: The `sender` for the event.
     type: string
+    format: mx-user-id
+    pattern: "^@"
 required:
   - type
   - state_key

data/event-schemas/schema/core-event-schema/sync_room_event.yaml

@@ -29,9 +29,13 @@ allOf:
     event_id:
       description: The globally unique event identifier.
       type: string
+      format: mx-event-id
+      pattern: "^\\$"
     sender:
       description: Contains the fully-qualified ID of the user who sent this event.
       type: string
+      format: mx-user-id
+      pattern: "^@"
     origin_server_ts:
       description: Timestamp in milliseconds on originating homeserver
         when this event was sent.

data/event-schemas/schema/m.key.verification.accept.yaml

@@ -44,7 +44,8 @@ properties:
         description: |-
           The hash (encoded as unpadded base64) of the concatenation of the device's
           ephemeral public key (encoded as unpadded base64) and the canonical JSON
-          representation of the `m.key.verification.start` message.
+          representation of the `content` object of the `m.key.verification.start`
+          message.
       m.relates_to:
         $ref: m.key.verification.m.relates_to.yaml
     required:

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

@@ -16,6 +16,8 @@ properties:
           The canonical alias for the room. If not present, null, or empty the
           room should be considered to have no canonical alias.
         type: string
+        format: mx-room-alias
+        pattern: "^#"
       alt_aliases:
         description: |
           Alternative aliases the room advertises. This list can have aliases
@@ -23,6 +25,8 @@ properties:
         type: array
         items:
           type: string
+          format: mx-room-alias
+          pattern: "^#"
     type: object
   state_key:
     description: A zero-length string.

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

@@ -12,6 +12,8 @@ properties:
           The `user_id` of the room creator. **Required** for, and only present in, room versions 1 - 10. Starting with
           room version 11 the event `sender` should be used instead.
         type: string
+        format: mx-user-id
+        pattern: "^@"
       m.federate:
         description: Whether users on other servers can join this room. Defaults to `true` if key does not exist.
         type: boolean
@@ -32,9 +34,13 @@ properties:
         properties:
           room_id:
             type: string
+            format: mx-room-id
+            pattern: "^!"
             description: The ID of the old room.
           event_id:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
             deprecated: true
             x-changedInMatrixVersion:
               "1.16": |-
@@ -51,6 +57,8 @@ properties:
         type: array
         items:
           type: string
+          format: mx-user-id
+          pattern: "^@"
           description: Additional user ID to consider a creator of the room, if supported by the room version.
         x-addedInMatrixVersion: "1.16"
         description: |-

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

@@ -55,6 +55,8 @@ properties:
               enum: ['m.room_membership']
             room_id:
               type: string
+              format: mx-room-id
+              pattern: "^!"
               description: |-
                 Required if `type` is `m.room_membership`. The room ID to check the
                 user's membership against. If the user is joined to this room, they

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

@@ -76,6 +76,8 @@ properties:
       join_authorised_via_users_server:
         x-addedInMatrixVersion: "1.2"
         type: string
+        format: mx-user-id
+        pattern: "^@"
         description: |-
           Usually found on `join` events, this field is used to denote which homeserver (through
           representation of a user with sufficient power level) authorised the user's join. More
@@ -127,6 +129,8 @@ properties:
       `join`, the user ID sending the event does not need to match the user ID in the `state_key`,
       unlike other events. Regular authorisation rules still apply.
     type: string
+    format: mx-user-id
+    pattern: "^@"
   type:
     enum:
       - m.room.member

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

@@ -0,0 +1,41 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: |-
+  A [Policy Server](/client-server-api/#policy-servers) configuration. If invalid
+  or not set, the room does not use a Policy Server.
+properties:
+  content:
+    properties:
+      via:
+        description: |-
+          The server name to use as a Policy Server. MUST have a joined user in
+          the room.
+        type: string
+      public_keys:
+        description: |-
+          The unpadded base64-encoded public keys for the Policy Server. MUST contain at
+          least `ed25519`.
+        type: object
+        properties:
+          ed25519:
+            type: string
+            description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+        required: ['ed25519']
+        additionalProperties:
+          description: The unpadded base64-encoded public key for the key algorithm.
+          type: string
+    type: object
+    required:
+      - via
+      - public_keys
+  state_key:
+    description: An empty string.
+    type: string
+  type:
+    enum:
+      - m.room.policy
+    type: string
+type: object

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

@@ -10,6 +10,8 @@ properties:
       redacts:
         description: The event ID that was redacted. Required for, and present starting in, room version 11.
         type: string
+        format: mx-event-id
+        pattern: "^\\$"
       reason:
         description: 'The reason for the redaction, if any.'
         type: string
@@ -17,6 +19,8 @@ properties:
   redacts:
     description: Required for, and only present in, room versions 1 - 10. The event ID that was redacted.
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
   type:
     enum:
       - m.room.redaction

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

@@ -54,7 +54,7 @@ properties:
         type: boolean
         description: |-
           True to allow server names that are IP address literals. False to
-          deny. Defaults to true if missing or otherwise not a boolean.
+          deny. Defaults to `true` if missing or otherwise not a boolean.
 
           This is strongly recommended to be set to `false` as servers running
           with IP literal names are strongly discouraged in order to require

data/string-formats.yaml

@@ -66,6 +66,11 @@ mx-mxc-uri:
   url: client-server-api#matrix-content-mxc-uris
   # regex: "^mxc:\\/\\/"
 
+mx-unpadded-base64:
+  title: Unpadded Base64
+  url: appendices#unpadded-base64
+  # no regex
+
 uri:
   title: URI
   url: https://datatracker.ietf.org/doc/html/rfc3986

layouts/_partials/events/render-event.html

@@ -49,7 +49,7 @@
   </tr>
 {{ if $state_key }}
   <tr>
-   <th>State key</th>
+   <th>State key:</th>
    <td>{{ $state_key.description | markdownify }}</td>
  </tr>
 {{ end }}