Merge 7b5935e5cb into 7bc016bda6

* Part 1: Invites

* Part 2: Knocks

* Use correct schema and examples; Remind readers often about formats

* changelogs

* Add schema warning

* Name the objects

* Move changed-in and expand upon it

* Rename the example

* address review feedback

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/2207.feature

@@ -0,0 +1 @@
+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/server_server/newsfragments/2207.feature

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

content/client-server-api/_index.md

@@ -2818,6 +2818,14 @@ should be represented as stripped state events when possible:
 * [`m.room.canonical_alias`](#mroomcanonical_alias)
 * [`m.room.encryption`](#mroomencryption)
 
+{{% changed-in v="1.16" %}} The `m.room.create` event is now **required** in
+the following places:
+* [`invite_state`](#get_matrixclientv3sync_response-200_invited-room) and
+  [`knock_state`](#get_matrixclientv3sync_response-200_knocked-room) on
+  [`/sync`](#get_matrixclientv3sync) responses.
+* On [`m.room.member`](#mroommember) events, the `invite_room_state`
+  and `knock_room_state` under `unsigned` on the event.
+
 {{% boxes/note %}}
 Clients should inspect the list of stripped state events and not assume any
 particular event is present. The server might include events not described
@@ -2848,6 +2856,12 @@ events are not signed and could theoretically be modified, or outdated due to
 updates not being sent.
 {{% /boxes/warning %}}
 
+{{% boxes/warning %}}
+{{% added-in v="1.16" %}} Servers cannot pass through what they receive over
+federation to clients as stripped state. Servers are expected to prune the events
+into the stripped state schema below before passing the details onto clients.
+{{% /boxes/warning %}}
+
 {{% event-fields event_type="stripped_state" %}}
 
 ### Size limits

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

@@ -3,6 +3,9 @@
 
 {{% changed-in v="1.7" %}}
 
+{{% changed-in v="1.16" %}}: 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),
-[`.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 %}}
+{{% boxes/note %}}
 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.
-{{% /boxes/rationale %}}
+the event. When the `m.mentions` field was introduced, those push rules were
+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

@@ -382,6 +382,9 @@ The following `alt_aliases` values will NOT match:
 
 **`contains_display_name`**
 
+{{% changed-in v="1.16" %}}: 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 +416,9 @@ Parameters:
 
 #### Predefined Rules
 
+{{% changed-in v="1.16" %}}: 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 +563,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 +597,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 +709,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/server-server-api.md

@@ -945,6 +945,18 @@ Note that invites are used to indicate that knocks were accepted. As such,
 receiving servers should be prepared to manually link up a previous knock
 to an invite if the invite event does not directly reference the knock.
 
+{{% boxes/note %}}
+{{% added-in v="1.16" %}} `invite_room_state` MUST now have its entries formatted
+according to the room's version (see [room version specification](/rooms)). However,
+servers SHOULD consider their local ecosystems before returning the described
+`400 M_MISSING_PARAM` error code. While migrating, servers SHOULD warn about
+invites which fail the validation rather than error in room versions 1 through 11.
+All invites to other room versions which fail validation SHOULD result in an error.
+
+The specification suggests that servers finish their migration no later than
+January 2026, though servers may extend this as required to support their users.
+{{% /boxes/note %}}
+
 {{% http-api spec="server-server" api="invites-v1" %}}
 
 {{% http-api spec="server-server" api="invites-v2" %}}

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/server-server/examples/invite_or_knock_state.json

@@ -0,0 +1,9 @@
+[
+  {"$ref": "./minimal_pdu.json"},
+  {
+    "type": "m.room.create",
+    "content": {
+      "see_room_version_spec": "The event format changes depending on the room version."
+    }
+  }
+]

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

@@ -71,13 +71,32 @@ paths:
                       properties:
                         invite_room_state:
                           type: array
+                          x-changedInMatrixVersion:
+                            "1.16": |
+                              `m.room.create` and format requirements were added.
                           description: |-
-                            An optional list of [stripped state events](/client-server-api/#stripped-state)
-                            to help the receiver of the invite identify the room.
+                            A list of state events to help the receiver of the invite identify the room.
+                            Translated as [stripped state events](/client-server-api/#stripped-state)
+                            over the Client-Server API.
+
+                            MUST contain the `m.room.create` event for the room. All events listed
+                            MUST additionally be formatted according to the room version specification.
+
+                            Servers might need to apply validation to the `invite_room_state` depending
+                            on room version. See the `400 M_MISSING_PARAM` error definition for more
+                            information.
+
+                            Note that events have a different format depending on the room
+                            version - check the [room version specification](/rooms) for
+                            precise event formats.
                           items:
-                            $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
-                          example:
-                            $ref: ../../event-schemas/examples/invite_room_state.json
+                            type: object
+                            title: PDU
+                            properties: {}
+                            description: |-
+                              Note that events have a different format depending on the room
+                              version - check the [room version specification](/rooms) for
+                              precise event formats.
               type: object
         required: true
       responses:
@@ -118,24 +137,7 @@ paths:
                         "origin_server_ts": 1549041175876,
                         "sender": "@someone:example.org",
                         "unsigned": {
-                          "invite_room_state": [
-                            {
-                              "type": "m.room.name",
-                              "sender": "@bob:example.org",
-                              "state_key": "",
-                              "content": {
-                                "name": "Example Room"
-                              }
-                            },
-                            {
-                              "type": "m.room.join_rules",
-                              "sender": "@bob:example.org",
-                              "state_key": "",
-                              "content": {
-                                "join_rule": "invite"
-                              }
-                            }
-                          ]
+                          "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
                         },
                         "content": {
                           "membership": "invite"
@@ -168,6 +170,35 @@ paths:
                     "errcode": "M_FORBIDDEN",
                     "error": "User cannot invite the target user."
                   }
+        "400":
+          description: |-
+            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            the following:
+
+            * The `m.room.create` event is missing from `invite_room_state`.
+            * One or more entries in `invite_room_state` are not formatted according
+              to the room's version.
+            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * One or more events does not reside in the same room as the invite.
+              Note: Some room versions may require calculating the room ID for an
+              event rather than relying on the presence of `room_id`.
+
+            Servers MAY apply the validation above to room versions 1 through 11,
+            and SHOULD apply the validation above to all other room versions.
+
+            If `M_MISSING_PARAM` is returned and the request is associated with a
+            Client-Server API request, the Client-Server API request SHOULD fail
+            with a 5xx error rather than being passed through.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_MISSING_PARAM",
+                    "error": "Create event not among invite state entries."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

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

@@ -72,13 +72,32 @@ paths:
                   $ref: definitions/invite_event.yaml
                 invite_room_state:
                   type: array
+                  x-changedInMatrixVersion:
+                    "1.16": |
+                      `m.room.create` and format requirements were added.
                   description: |-
-                    An optional list of [stripped state events](/client-server-api/#stripped-state)
-                    to help the receiver of the invite identify the room.
+                    A list of state events to help the receiver of the invite identify the room.
+                    Translated as [stripped state events](/client-server-api/#stripped-state)
+                    over the Client-Server API.
+
+                    MUST contain the `m.room.create` event for the room. All events listed
+                    MUST additionally be formatted according to the room version specification.
+
+                    Servers might need to apply validation to the `invite_room_state` depending
+                    on room version. See the `400 M_MISSING_PARAM` error definition for more
+                    information.
+
+                    Note that events have a different format depending on the room
+                    version - check the [room version specification](/rooms) for
+                    precise event formats.
                   items:
-                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
-                  example:
-                    $ref: ../../event-schemas/examples/invite_room_state.json
+                    type: object
+                    title: PDU
+                    properties: {}
+                    description: |-
+                      Note that events have a different format depending on the room
+                      version - check the [room version specification](/rooms) for
+                      precise event formats.
               required:
                 - room_version
                 - event
@@ -111,24 +130,7 @@ paths:
                       "origin_server_ts": 1549041175876,
                       "sender": "@someone:example.org",
                       "unsigned": {
-                        "invite_room_state": [
-                          {
-                            "type": "m.room.name",
-                            "sender": "@bob:example.org",
-                            "state_key": "",
-                            "content": {
-                              "name": "Example Room"
-                            }
-                          },
-                          {
-                            "type": "m.room.join_rules",
-                            "sender": "@bob:example.org",
-                            "state_key": "",
-                            "content": {
-                              "join_rule": "invite"
-                            }
-                          }
-                        ]
+                        "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
                       },
                       "content": {
                         "membership": "invite"
@@ -151,6 +153,24 @@ paths:
 
             The error should be passed through to clients so that they
             may give better feedback to users.
+
+            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            the following:
+
+            * The `m.room.create` event is missing from `invite_room_state`.
+            * One or more entries in `invite_room_state` are not formatted according
+              to the room's version.
+            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+            * One or more events does not reside in the same room as the invite.
+              Note: Some room versions may require calculating the room ID for an
+              event rather than relying on the presence of `room_id`.
+
+            Servers MAY apply the validation above to room versions 1 through 11,
+            and SHOULD apply the validation above to all other room versions.
+
+            If `M_MISSING_PARAM` is returned and the request is associated with a
+            Client-Server API request, the Client-Server API request SHOULD fail
+            with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:

data/api/server-server/knocks.yaml

@@ -293,19 +293,41 @@ paths:
                   knock_room_state:
                     type: array
                     items:
-                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                      type: object
+                      title: PDU
+                      properties: {}
+                      description: |-
+                        Note that events have a different format depending on the room
+                        version - check the [room version specification](/rooms) for
+                        precise event formats.
+                    x-changedInMatrixVersion:
+                      "1.16": |
+                        `m.room.create` and format requirements were added.
                     description: |-
-                      A list of [stripped state events](/client-server-api/#stripped-state)
-                      to help the initiator of the knock identify the room.
+                      A list of state events to help the initiator of the knock identify
+                      the room. Translated as [stripped state events](/client-server-api/#stripped-state)
+                      over the Client-Server API.
+
+                      MUST contain the `m.room.create` event for the room. All events
+                      listed MUST additionally be formatted according to the room
+                      version specification.
+
+                      Entries which are [improperly signed](/server-server-api/#validating-hashes-and-signatures-on-received-events)
+                      or formatted SHOULD be removed by the server prior to supplying
+                      them over the Client-Server API.
+
+                      Note that events have a different format depending on the room
+                      version - check the [room version specification](/rooms) for
+                      precise event formats.
                     example:
-                      $ref: ../../event-schemas/examples/knock_room_state.json
+                      "$ref": "./examples/invite_or_knock_state.json"
                 required:
                   - knock_room_state
               examples:
                 response:
                   value: {
                     "knock_room_state": {
-                      "$ref": "../../event-schemas/examples/knock_room_state.json"
+                      "$ref": "./examples/invite_or_knock_state.json"
                     }
                   }
         "403":

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": [

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

@@ -137,6 +137,9 @@ properties:
       - type: object
         properties:
           invite_room_state:
+            x-changedInMatrixVersion:
+              "1.16": |
+                `m.room.create` was made a required event type for stripped state.
             description: |-
               A subset of the state of the room at the time of the invite, if `membership` is `invite`.
               Note that this state is informational, and SHOULD NOT be trusted; once the client has
@@ -145,16 +148,21 @@ properties:
               they SHOULD behave properly (with possibly a degraded but not a broken experience) in
               the absence of any particular events here. If they are set on the room, at least the
               state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name`
-              SHOULD be included.
+              SHOULD be included. The `m.room.create` event MUST be included, though MAY be missing if
+              the server hasn't updated to support the Matrix 1.16 specification.
             items:
               $ref: "core-event-schema/stripped_state.yaml"
             type: array
           knock_room_state:
+            x-changedInMatrixVersion:
+              "1.16": |
+                `m.room.create` was made a required event type for stripped state.
             description: |-
               A subset of the state of the room at the time of the knock, if `membership` is `knock`.
               This has the same restrictions as `invite_room_state`. If they are set on the room, at least
               the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, `m.room.name`,
-              and `m.room.encryption` SHOULD be included.
+              and `m.room.encryption` SHOULD be included. The `m.room.create` event MUST be included,
+              though MAY be missing if the server hasn't updated to support the Matrix 1.16 specification.
             items:
               $ref: "core-event-schema/stripped_state.yaml"
             type: array