Merge f42ce28bfe 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/2204.clarification

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

changelogs/client_server/newsfragments/2206.feature

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

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/internal/newsfragments/2205.clarification

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

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/history_visibility.md

@@ -16,8 +16,8 @@ The four options for the `m.room.history_visibility` event are:
 
 -   `world_readable` - All events while this is the
     `m.room.history_visibility` value may be shared by any participating
-    homeserver with anyone, regardless of whether they have ever joined
+    homeserver with any authenticated user, regardless of whether they have
-    the room.
+    ever joined the room. This includes [guest users](#guest-access).
 -   `shared` - Previous events are always accessible to newly joined
     members. All events in the room are accessible, even those sent when
     the member was not a part of the room.
@@ -44,7 +44,7 @@ setting at that time was more restrictive.
 #### Client behaviour
 
 Clients may want to display a notice that events may be read by
-non-joined people if the history visibility is set to `world_readable`.
+non-joined users if the history visibility is set to `world_readable`.
 
 #### Server behaviour
 

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

@@ -6,7 +6,7 @@ It is sometimes desirable to offer a preview of a room, where a user can
 This can be particularly effective when combined with [Guest Access](#guest-access).
 
 Previews are implemented via the `world_readable` [Room History
-Visibility](#room-history-visibility). setting, along with a special version of the [GET
+Visibility](#room-history-visibility) setting, along with a special version of the [GET
 /events](#get_matrixclientv3events) endpoint.
 
 #### Client behaviour

content/proposals.md

@@ -555,7 +555,7 @@ resolve to the desired MSC, whether it started as an issue or a PR.
 Other metadata:
 
 -   The MSC number is taken from the GitHub Pull Request ID. This is
-    carried for the lifetime of the proposal. These IDs do not necessary
+    carried for the lifetime of the proposal. These IDs do not necessarily
     represent a chronological order.
 -   The GitHub PR title will act as the MSC's title.
 -   Please link to the spec PR (if any) by adding a "PRs: \#1234" line

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

@@ -43,7 +43,7 @@ properties:
     example: "All things general"
   world_readable:
     type: boolean
-    description: Whether the room may be viewed by guest users without joining.
+    description: Whether the room may be viewed by users without joining.
     example: false
   guest_can_join:
     type: boolean

data/api/client-server/profile.yaml

@@ -19,7 +19,7 @@ paths:
   "/profile/{userId}/{keyName}":
     put:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+        "1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
       summary: Set a profile field for a user.
       description: |-
         Set or update a profile field for a user. Must be authenticated with an
@@ -44,13 +44,13 @@ paths:
         - in: path
           name: keyName
           description: The name of the profile field to set. This MUST be either
-            `avatar_url`, `displayname`, or a custom field following the
+            `avatar_url`, `displayname`, `m.tz`, or a custom field following the
             [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
           required: true
           example: "displayname"
           schema:
             type: string
-            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
         description: A JSON object containing the property whose name matches
           the `keyName` specified in the URL. See `additionalProperties` for
@@ -69,6 +69,10 @@ paths:
                 
                 For `displayname`, the value MUST be a string.
                 
+                For `m.tz`, the value MUST be a valid identifier from the  [IANA Time Zone Database](https://www.iana.org/time-zones).
+                Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
+                values.
+
                 For custom keys, any JSON type is allowed. Servers MAY not validate
                 these values, but clients SHOULD follow the format defined for that key.
               additionalProperties: true
@@ -137,7 +141,7 @@ paths:
         - User data
     get:
       x-changedInMatrixVersion:
-        "1.16": This endpoint now accepts a variable `keyName` parameter. Previously only `displayname` and `avatar_url` were accepted.
+        "1.16": This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted.
       summary: Get a profile field for a user.
       description: Get the value of a profile field for a user.
       operationId: getProfileField
@@ -156,7 +160,7 @@ paths:
           example: "displayname"
           schema:
             type: string
-            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
           description: The profile field value was retrieved.
@@ -214,7 +218,7 @@ paths:
           example: "displayname"
           schema:
             type: string
-            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
+            pattern: '^(avatar_url|displayname|m\.tz|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
           description: The profile field was deleted or it doesn't exist.
@@ -293,6 +297,10 @@ paths:
                     type: string
                     description: The user's display name if they have set one, otherwise not
                       present.
+                  m.tz:
+                    x-addedInMatrixVersion: "1.16"
+                    type: string
+                    description: The user's time zone.
                 additionalProperties:
                   x-addedInMatrixVersion: "1.16"
                   description: Additional profile fields.
@@ -302,6 +310,7 @@ paths:
                     {
                       "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
                       "displayname": "Alice Margatroid",
+                      "m.tz": "Europe/London",
                       "m.example_field": "custom_value",
                     }
         "403":

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)
+                            A list of state events to help the receiver of the invite identify the room.
-                            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
+                            type: object
-                          example:
+                            title: PDU
-                            $ref: ../../event-schemas/examples/invite_room_state.json
+                            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": [
+                          "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
-                            {
-                              "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"
-                              }
-                            }
-                          ]
                         },
                         "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)
+                    A list of state events to help the receiver of the invite identify the room.
-                    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
+                    type: object
-                  example:
+                    title: PDU
-                    $ref: ../../event-schemas/examples/invite_room_state.json
+                    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": [
+                        "invite_room_state": {"$ref": "./examples/invite_or_knock_state.json"}
-                          {
-                            "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"
-                            }
-                          }
-                        ]
                       },
                       "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: |-
-                      A list of [stripped state events](/client-server-api/#stripped-state)
+                        Note that events have a different format depending on the room
-                      to help the initiator of the knock identify 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 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/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