Merge 205fa06076 into fda3be5ee3

Fixes: #1753

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

changelogs/appendices/newsfragments/2193.feature

@@ -1 +0,0 @@
-Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).

changelogs/application_service/newsfragments/2213.clarification

@@ -0,0 +1 @@
+Fix JSON formatting in the "Server admin style permissions" examples.

changelogs/application_service/newsfragments/2221.feature

@@ -0,0 +1 @@
+Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).

changelogs/client_server/newsfragments/2071.deprecation

@@ -1 +0,0 @@
-Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

changelogs/client_server/newsfragments/2071.feature

@@ -1 +0,0 @@
-Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133).

changelogs/client_server/newsfragments/2167.clarification

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

changelogs/client_server/newsfragments/2169.clarification

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

changelogs/client_server/newsfragments/2175.feature

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

changelogs/client_server/newsfragments/2177.clarification

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

changelogs/client_server/newsfragments/2179.clarification

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

changelogs/client_server/newsfragments/2186.removal

@@ -0,0 +1 @@
+Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).

changelogs/client_server/newsfragments/2187.feature

@@ -1 +0,0 @@
-Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222).

changelogs/client_server/newsfragments/2190.clarification

@@ -1 +0,0 @@
-Clarify that clients should replace events with the most recent replacement by `origin_server_ts`.

changelogs/client_server/newsfragments/2193.feature.1

@@ -1 +0,0 @@
-When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).

changelogs/client_server/newsfragments/2193.feature.2

@@ -1 +0,0 @@
-When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).

changelogs/client_server/newsfragments/2193.feature.3

@@ -1 +0,0 @@
-In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).

changelogs/client_server/newsfragments/2193.feature.4

@@ -1 +0,0 @@
-In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).

changelogs/client_server/newsfragments/2193.feature.5

@@ -1 +0,0 @@
-When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).

changelogs/client_server/newsfragments/2195.clarification

@@ -1 +0,0 @@
-Fix `/sync` flow referencing incorrect parameter to use with `/messages`.

changelogs/client_server/newsfragments/2204.clarification

@@ -1 +0,0 @@
-Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2206.feature

@@ -1 +0,0 @@
-Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175).

changelogs/client_server/newsfragments/2207.feature

@@ -1 +0,0 @@
-Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).

changelogs/client_server/newsfragments/2210.removal

@@ -1 +0,0 @@
-Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142).

changelogs/client_server/newsfragments/2214.clarification

@@ -0,0 +1 @@
+Push rule IDs are globally unique within their kind.

changelogs/client_server/newsfragments/2215.clarification

@@ -0,0 +1 @@
+Don't advertise `creator` field in description of room creation.

changelogs/client_server/newsfragments/2216.clarification

@@ -0,0 +1 @@
+`room_id` is required for peeking via `/_matrix/client/v3/events`.

changelogs/client_server/newsfragments/2217.clarification

@@ -0,0 +1 @@
+The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.

changelogs/client_server/newsfragments/2221.feature

@@ -0,0 +1 @@
+Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).

changelogs/client_server/newsfragments/2223.clarification

@@ -0,0 +1 @@
+Add note to each endpoint that uses capability negotiation.

changelogs/client_server/newsfragments/2225.clarification

@@ -0,0 +1 @@
+Additional OpenGraph properties can be present in URL previews.

changelogs/internal/newsfragments/2132.clarification.1

@@ -1 +0,0 @@
-Declare the Application Service Registration schema to follow JSON Schema spec 2020-12.

changelogs/internal/newsfragments/2132.clarification.2

@@ -1 +0,0 @@
-Declare the event schemas to follow JSON Schema spec 2020-12.

changelogs/internal/newsfragments/2157.feature

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

changelogs/internal/newsfragments/2160.clarification

@@ -1 +0,0 @@
-Upgrade the docsy theme to version 0.12.0.

changelogs/internal/newsfragments/2172.clarification

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

changelogs/internal/newsfragments/2182.clarification

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

changelogs/internal/newsfragments/2189.clarification

@@ -1 +0,0 @@
-Specify a correct spelling for "display name".

changelogs/internal/newsfragments/2205.clarification

@@ -1 +0,0 @@
-Fix a grammatical typo on the Matrix Spec Process documentation page.

changelogs/internal/newsfragments/2219.clarification

@@ -0,0 +1 @@
+Swapped icon for X (fka. twitter) to updated logo in footer.

changelogs/room_versions/newsfragments/2193.clarification

@@ -1 +0,0 @@
-In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307).

changelogs/room_versions/newsfragments/2193.feature.1

@@ -1 +0,0 @@
-Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).

changelogs/room_versions/newsfragments/2193.feature.2

@@ -1 +0,0 @@
-Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291).

changelogs/room_versions/newsfragments/2193.feature.3

@@ -1 +0,0 @@
-Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289).

changelogs/room_versions/newsfragments/2193.feature.4

@@ -1 +0,0 @@
-State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297).

changelogs/room_versions/newsfragments/2193.feature.5

@@ -1 +0,0 @@
-The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).

changelogs/room_versions/newsfragments/2199.feature

@@ -1 +0,0 @@
-Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304).

changelogs/room_versions/newsfragments/2220.clarification

@@ -0,0 +1 @@
+In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room.

changelogs/server_server/newsfragments/2207.feature

@@ -1 +0,0 @@
-`invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311).

config/_default/hugo.toml

@@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
 # major = "1"
-# minor = "15"
+# minor = "16"
 
 # User interface configuration
 [params.ui]
@@ -110,7 +110,7 @@ sidebar_menu_compact = true
 [[params.links.bottom]]
 	name = "Twitter"
 	url = "https://twitter.com/matrixdotorg"
-	icon = "fab fa-twitter"
+	icon = "fab fa-x-twitter"
   desc = "Matrix on Twitter"
 
 

content/application-service-api.md

@@ -356,6 +356,7 @@ service would like to masquerade as.
 Inputs:
 -   Application service token (`as_token`)
 -   User ID in the AS namespace to act as.
+-   Device ID belonging to the User ID to act with.
 
 Notes:
 -   This applies to all aspects of the Client-Server API, except for
@@ -375,9 +376,19 @@ service's `user` namespaces. If the parameter is missing, the homeserver
 is to assume the application service intends to act as the user implied
 by the `sender_localpart` property of the registration.
 
+{{% added-in v="1.17" %}} Application services MAY similarly masquerade
+as a specific device ID belonging the user ID through use of the `device_id`
+query string parameter on the request. If the given device ID is not known
+to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
+If no `user_id` is supplied, the `device_id` MUST belong to the user implied
+by the `sender_localpart` property of the application service's registration.
+If no `device_id` is supplied, the homeserver is to assume the request is
+being made without a device ID and will fail to complete operations which
+require a device ID (such as uploading one-time keys).
+
 An example request would be:
 
-    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
+    GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
     Authorization: Bearer YourApplicationServiceTokenHere
 
 #### Timestamp massaging
@@ -438,8 +449,8 @@ user ID without a password.
 
     Content:
     {
-      type: "m.login.application_service",
+      "type": "m.login.application_service",
-      username: "_irc_example"
+      "username": "_irc_example"
     }
 
 Similarly, logging in as users needs API changes in order to allow the AS to
@@ -454,7 +465,7 @@ log in without needing the user's password. This is achieved by including the
 
     Content:
     {
-      type: "m.login.application_service",
+      "type": "m.login.application_service",
       "identifier": {
         "type": "m.id.user",
         "user": "_irc_example"

content/changelog/v1.16.md

@@ -0,0 +1,103 @@
+---
+title: v1.16 Changelog
+linkTitle: v1.16
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-09-17
+---
+
+## Client-Server API
+
+**Deprecations**
+
+- Deprecate `m.set_avatar_url` and `m.set_displayname` capabilities, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+
+**Removed Endpoints**
+
+- Remove unintentional intentional mentions in replies, as per [MSC4142](https://github.com/matrix-org/matrix-spec-proposals/pull/4142). ([#2210](https://github.com/matrix-org/matrix-spec/issues/2210))
+
+**Backwards Compatible Changes**
+
+- Update user profile endpoints to handle custom fields, and add a new `m.profile_fields` capability, as per [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133). ([#2071](https://github.com/matrix-org/matrix-spec/issues/2071))
+- Add `format` query parameter to `GET /state/{eventType}/{stateKey}` to allow fetching metadata of a specific state event. ([#2175](https://github.com/matrix-org/matrix-spec/issues/2175))
+- Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222). ([#2187](https://github.com/matrix-org/matrix-spec/issues/2187))
+- When upgrading rooms to [room version 12](/rooms/v12), `additional_creators` may be specified on the [`POST /_matrix/client/v3/rooms/{roomId}/upgrade`](/client-server-api/#post_matrixclientv3roomsroomidupgrade) endpoint, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the `trusted_private_chat` preset should merge the invitees into the supplied `content.additional_creators` in the resulting room, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), the power level of room creators is now infinitely high as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- In [room version 12](/rooms/v12), room IDs no longer have a domain component as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- When creating rooms with [room version 12](/rooms/v12), the initial power levels will restrict the ability to upgrade rooms by default, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add a profile field for a user's time zone, as per [MSC4175](https://github.com/matrix-org/matrix-spec-proposals/pull/4175). ([#2206](https://github.com/matrix-org/matrix-spec/issues/2206))
+- Invites and knocks are now expected to contain the `m.room.create` event in their stripped state entries, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+**Spec Clarifications**
+
+- Clarify that `format` is required if `formatted_body` is specified. ([#2167](https://github.com/matrix-org/matrix-spec/issues/2167))
+- The `latest_event` in an aggregated set of thread events uses the same format as the event itself. ([#2169](https://github.com/matrix-org/matrix-spec/issues/2169))
+- Fix various typos throughout the specification. ([#2171](https://github.com/matrix-org/matrix-spec/issues/2171), [#2177](https://github.com/matrix-org/matrix-spec/issues/2177), [#2179](https://github.com/matrix-org/matrix-spec/issues/2179))
+- Clarify that clients should replace events with the most recent replacement by `origin_server_ts`. ([#2190](https://github.com/matrix-org/matrix-spec/issues/2190))
+- Fix `/sync` flow referencing incorrect parameter to use with `/messages`. ([#2195](https://github.com/matrix-org/matrix-spec/issues/2195))
+- Clarify wording around the `world_readable` history visibility setting. Contributed by @HarHarLinks. ([#2204](https://github.com/matrix-org/matrix-spec/issues/2204))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- `invite_room_state` and `knock_room_state` now have additional requirements and validation depending on the room version, as per [MSC4311](https://github.com/matrix-org/matrix-spec-proposals/pull/4311). ([#2207](https://github.com/matrix-org/matrix-spec/issues/2207))
+
+
+## Application Service API
+
+No significant changes.
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Backwards Compatible Changes**
+
+- Room IDs in room version 12 are now the event ID of the create event with the normal room ID sigil (`!`), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Room creators are formalized in room version 12 and have infinitely high power level, as per [MSC4289](https://github.com/matrix-org/matrix-spec-proposals/pull/4289). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- State Resolution is updated in room version 12 to reduce the opportunity for "state resets", as per [MSC4297](https://github.com/matrix-org/matrix-spec-proposals/pull/4297). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- The default room version is now room version 12, though servers SHOULD keep using room version 11 for a little while, as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+- Add [room version 12](/rooms/v12) as per [MSC4304](https://github.com/matrix-org/matrix-spec-proposals/pull/4304). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193), [#2199](https://github.com/matrix-org/matrix-spec/issues/2199))
+
+**Spec Clarifications**
+
+- In room versions 1 through 12, an event's `auth_events` have always needed to belong to the same room as per [MSC4307](https://github.com/matrix-org/matrix-spec-proposals/pull/4307). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Appendices
+
+**Backwards Compatible Changes**
+
+- Room IDs can now appear without a domain component in [room version 12](/rooms/v12), as per [MSC4291](https://github.com/matrix-org/matrix-spec-proposals/pull/4291). ([#2193](https://github.com/matrix-org/matrix-spec/issues/2193))
+
+
+## Internal Changes/Tooling
+
+**Backwards Compatible Changes**
+
+- Add "placeholder MSC" process definition. ([#2157](https://github.com/matrix-org/matrix-spec/issues/2157))
+
+**Spec Clarifications**
+
+- Declare the Application Service Registration schema to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Declare the event schemas to follow JSON Schema spec 2020-12. ([#2132](https://github.com/matrix-org/matrix-spec/issues/2132))
+- Upgrade the docsy theme to version 0.12.0. ([#2160](https://github.com/matrix-org/matrix-spec/issues/2160))
+- GitHub actions are now building the OpenAPI `spec/identity-service-api/api.json` file. ([#2172](https://github.com/matrix-org/matrix-spec/issues/2172))
+- Minor fixes to JSON schemas. ([#2182](https://github.com/matrix-org/matrix-spec/issues/2182))
+- Specify a correct spelling for "display name". ([#2189](https://github.com/matrix-org/matrix-spec/issues/2189))
+- Fix a grammatical typo on the Matrix Spec Process documentation page. ([#2205](https://github.com/matrix-org/matrix-spec/issues/2205))

content/client-server-api/_index.md

@@ -132,6 +132,10 @@ 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_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`
 An unknown error has occurred.
 
@@ -3386,10 +3390,10 @@ Unspecified room types are permitted through the use of
 ### Creation
 
 The homeserver will create an `m.room.create` event when a room is
-created, which serves as the root of the event graph for this room. This
+created, which serves as the root of the event graph for this room. The
-event also has a `creator` key which contains the user ID of the room
+event `sender` is the user ID of the room creator. The server will also
-creator. It will also generate several other events in order to manage
+generate several other events in order to manage permissions in this room.
-permissions in this room. This includes:
+This includes:
 
 -   `m.room.power_levels` : Sets the power levels of users and required power
     levels for various actions within the room such as sending events.

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

@@ -134,9 +134,14 @@ entity isn't in the room.
 `mxc://` URIs are vulnerable to directory traversal attacks such as
 `mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
 target homeserver to try to access and return this file. As such,
-homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
+homeservers MUST sanitise `mxc://` URIs by:
-(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
+
-`media-id` values. This set of whitelisted characters allows URL-safe
+-   restricting the `server-name` segment to valid
+    [server names](/appendices/#server-name)
+-   allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
+    the `media-id` segment
+
+The resulting set of whitelisted characters allows URL-safe
 base64 encodings specified in RFC 4648. Applying this character
 whitelist is preferable to blacklisting `.` and `/` as there are
 techniques around blacklisted characters (percent-encoded characters,

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

@@ -3,6 +3,9 @@
 
 {{% changed-in v="1.7" %}}
 
+{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
+the `body` of the event were removed.
+
 This module allows users to "mention" other users and rooms within a room event.
 This is primarily used as an indicator that the recipient should receive a notification
 about the event.
@@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
 must be decrypted first. See [receiving notifications](#receiving-notifications).
 {{% /boxes/warning %}}
 
-Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
+{{% boxes/note %}}
-[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
-[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to  match if the `body` of
-the event contains the user's display name or ID. To avoid unintentional notifications,
-**it is recommended that clients include a `m.mentions` property on each event**.
-(If there are no mentions to include it can be an empty object.)
-
-{{% boxes/rationale %}}
 In previous versions of the specification, mentioning users was done by
 including the user's display name or the localpart of their Matrix ID and room
 mentions were done by including the string "@room" in the plaintext `body` of
-the event. This was prone to confusing and buggy behaviour.
+the event. When the `m.mentions` field was introduced, those push rules were
-{{% /boxes/rationale %}}
+disabled if the `m.mentions` field was present.
+
+To avoid unintentional notifications with clients and servers that still use
+those push rules, **it is recommended that clients still include a `m.mentions`
+property on each event**. (If there are no mentions to include it can be an
+empty object.)
+{{% /boxes/note %}}
 
 #### Client behaviour
 

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

@@ -83,7 +83,7 @@ Push Ruleset
 :   A push ruleset *scopes a set of rules according to some criteria*. For
     example, some rules may only be applied for messages from a particular
     sender, a particular room, or by default. The push ruleset contains the
-    entire set of scopes and rules.
+    entire set of rules.
 
 #### Push Rules
 
@@ -91,10 +91,8 @@ A push rule is a single rule that states under what *conditions* an
 event should be passed onto a push gateway and *how* the notification
 should be presented. There are different "kinds" of push rules and each
 rule has an associated priority. Every push rule MUST have a `kind` and
-`rule_id`. The `rule_id` is a unique string within the kind of rule and
+`rule_id`. The `rule_id` is a unique string within the kind of rule.
-its' scope: `rule_ids` do not need to be unique between rules of the
+Rules may have extra keys depending on the value of `kind`.
-same kind on different devices. Rules may have extra keys depending on
-the value of `kind`.
 
 The different `kind`s of rule, in the order that they are checked, are:
 
@@ -382,6 +380,9 @@ The following `alt_aliases` values will NOT match:
 
 **`contains_display_name`**
 
+{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
+used in new push rules**.
+
 This matches messages where `content.body` contains the owner's display name in
 that room. This is a separate condition because display names may change and as such
 it would be hard to maintain a rule that matched the user's display name. This
@@ -413,6 +414,9 @@ Parameters:
 
 #### Predefined Rules
 
+{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
+mentions in the `body` of the event were removed.
+
 Homeservers can specify "server-default rules". They operate at a lower
 priority than "user-defined rules", except for the `.m.rule.master` rule
 which has always a higher priority than any other rule. The `rule_id`
@@ -557,41 +561,6 @@ Definition:
 }
 ```
 
-<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the user's current display name
-in the room in which it was sent.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.contains_display_name",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "contains_display_name"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 <a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
 
 {{% added-in v="1.7" %}}
@@ -626,44 +595,6 @@ Definition:
 }
 ```
 
-<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message from a sender with the proper power level whose content
-contains the text `@room`, signifying the whole room should be notified of
-the event.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.roomnotif",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "event_match",
-            "key": "content.body",
-            "pattern": "@room"
-        },
-        {
-            "kind": "sender_notification_permission",
-            "key": "room"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 **<a id="mruletombstone"></a>`.m.rule.tombstone`**
 
 Matches any state event whose type is `m.room.tombstone`. This is
@@ -776,39 +707,6 @@ Definition:
 }
 ```
 
-##### Default Content Rules
-
-<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the local part of the user's
-Matrix ID, separated by word boundaries.
-
-Definition (as a `content` rule):
-
-```json
-{
-    "rule_id": ".m.rule.contains_user_name",
-    "default": true,
-    "enabled": true,
-    "pattern": "[the local part of the user's Matrix ID]",
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 ##### Default Underride Rules
 
 **`.m.rule.call`**

content/rooms/fragments/v8-auth-rules.md

@@ -74,7 +74,7 @@ The rules are as follows:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
                 is not a user with sufficient permission to invite other
-                users, reject.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

content/rooms/v10.md

@@ -150,7 +150,7 @@ The rules are as follows:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
                 is not a user with sufficient permission to invite other
-                users, reject.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

content/rooms/v11.md

@@ -157,7 +157,7 @@ The rules are as follows:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
                 is not a user with sufficient permission to invite other
-                users, reject.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

content/rooms/v12.md

@@ -141,7 +141,7 @@ The rules are as follows:
             1.  If membership state is `join` or `invite`, allow.
             2.  If the `join_authorised_via_users_server` key in `content`
                 is not a user with sufficient permission to invite other
-                users, reject.
+                users or is not a joined member of the room, reject.
             3.  Otherwise, allow.
         6.  If the `join_rule` is `public`, allow.
         7.  Otherwise, reject.

data/api/client-server/administrative_contact.yaml

@@ -99,6 +99,10 @@ paths:
         has been removed, making this endpoint behave as though it was `false`.
         This results in this endpoint being an equivalent to `/3pid/bind` rather
         than dual-purpose.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: post3PIDs
       deprecated: true
       security:
@@ -214,6 +218,10 @@ paths:
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
 
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+
         {{% boxes/warning %}}
         Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
@@ -355,6 +363,10 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: delete3pidFromAccount
       security:
         - accessTokenQuery: []

data/api/client-server/authed-content-repo.yaml

@@ -379,7 +379,8 @@ paths:
           description: |-
             The OpenGraph data for the URL, which may be empty. Some values are
             replaced with matrix equivalents if they are provided in the response.
-            The differences from the OpenGraph protocol are described here.
+            The differences from the [OpenGraph protocol](https://ogp.me/) are
+            described here.
           content:
             application/json:
               schema:
@@ -394,6 +395,9 @@ paths:
                     format: uri
                     description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
                       the image. Omitted if there is no image.
+                additionalProperties:
+                    description: |-
+                      Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
               examples:
                 response:
                   value: {

data/api/client-server/content-repo.yaml

@@ -605,7 +605,8 @@ paths:
           description: |-
             The OpenGraph data for the URL, which may be empty. Some values are
             replaced with matrix equivalents if they are provided in the response.
-            The differences from the OpenGraph protocol are described here.
+            The differences from the [OpenGraph](https://ogp.me/) protocol are
+            described here.
           content:
             application/json:
               schema:
@@ -620,6 +621,9 @@ paths:
                     format: uri
                     description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
                       the image. Omitted if there is no image.
+                additionalProperties:
+                    description: |-
+                      Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
               examples:
                 response:
                   value: {

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

@@ -34,24 +34,6 @@ properties:
     type: array
 type: object
 example: {
-  "content": [
-    {
-      "actions": [
-        "notify",
-        {
-          "set_tweak": "sound",
-          "value": "default"
-        },
-        {
-          "set_tweak": "highlight"
-        }
-      ],
-      "default": true,
-      "enabled": true,
-      "pattern": "alice",
-      "rule_id": ".m.rule.contains_user_name"
-    }
-  ],
   "override": [
     {
       "actions": [],
@@ -113,12 +95,14 @@ example: {
       ],
       "conditions": [
         {
-          "kind": "contains_display_name"
+            "kind": "event_property_contains",
+            "key": "content.m\\.mentions.user_ids",
+            "value": "@alice:example.com"
         }
       ],
       "default": true,
       "enabled": true,
-      "rule_id": ".m.rule.contains_display_name"
+      "rule_id": ".m.rule.is_user_mention"
     },
     {
       "actions": [

data/api/client-server/old_sync.yaml

@@ -324,7 +324,7 @@ paths:
         This endpoint was deprecated in r0 of this specification. Clients
         should instead call the
         [/rooms/{roomId}/event/{eventId}](/client-server-api/#get_matrixclientv3roomsroomideventeventid) API
-        or the [/rooms/{roomId}/context/{eventId](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
+        or the [/rooms/{roomId}/context/{eventId}](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.
       operationId: getOneEvent
       security:
         - accessTokenQuery: []

data/api/client-server/password_management.yaml

@@ -34,6 +34,10 @@ paths:
         valid access token is provided. The homeserver SHOULD NOT revoke the
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
+        to determine if this endpoint is available.
       security:
         - {}
         - accessTokenQuery: []

data/api/client-server/peeking_events.yaml

@@ -59,6 +59,7 @@ paths:
           example: "!somewhere:over.the.rainbow"
           schema:
             type: string
+          required: true
       responses:
         "200":
           description: The events received, which may be none.

data/api/client-server/profile.yaml

@@ -29,6 +29,11 @@ paths:
         Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
         them rather than treating `null` as a deletion request. Clients that want to delete a
         field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
+        depending on the `keyName`. Clients SHOULD check the value of the
+        [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect
+        which `keyName`s they are allowed to modify.
       operationId: setProfileField
       security:
         - accessTokenQuery: []

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

@@ -3,24 +3,6 @@
   "type": "m.push_rules",
   "content": {
     "global": {
-      "content": [
-        {
-          "actions": [
-            "notify",
-            {
-              "set_tweak": "sound",
-              "value": "default"
-            },
-            {
-              "set_tweak": "highlight"
-            }
-          ],
-          "default": true,
-          "enabled": true,
-          "pattern": "alice",
-          "rule_id": ".m.rule.contains_user_name"
-        }
-      ],
       "override": [
         {
           "actions": [],
@@ -82,12 +64,14 @@
           ],
           "conditions": [
             {
-              "kind": "contains_display_name"
+                "kind": "event_property_contains",
+                "key": "content.m\\.mentions.user_ids",
+                "value": "@alice:example.com"
             }
           ],
           "default": true,
           "enabled": true,
-          "rule_id": ".m.rule.contains_display_name"
+          "rule_id": ".m.rule.is_user_mention"
         },
         {
           "actions": [