Clarify exactly what StrippedState is

Fixes https://github.com/matrix-org/matrix-doc/issues/2066

The expectation everywhere is that the `sender` is required. `/initialSync` references StrippedState through a `m.room.member` event reference, and does not need editing.

api/client-server/sync.yaml

@@ -212,30 +212,7 @@ paths:
                             events:
                               description: The StrippedState events that form the invite state.
                               items:
-                                description: |-
-                                  A stripped down state event, with only the ``type``, ``state_key``,
-                                  ``sender``, and ``content`` keys.
-                                properties:
-                                  content:
-                                    description: The ``content`` for the event.
-                                    title: EventContent
-                                    type: object
-                                  state_key:
-                                    description: The ``state_key`` for the event.
-                                    type: string
-                                  type:
-                                    description: The ``type`` for the event.
-                                    type: string
-                                  sender:
-                                    description: The ``sender`` for the event.
-                                    type: string
-                                required:
-                                  - type
-                                  - state_key
-                                  - content
-                                  - sender
-                                title: StrippedState
-                                type: object
+                                $ref: "definitions/event-schemas/schema/stripped_state.yaml"
                               type: array
                   leave:
                     title: Left rooms

api/server-server/invites-v1.yaml

@@ -82,25 +82,7 @@ paths:
                           identify the room. The recommended events to include are the join rules,
                           canonical alias, avatar, and name of the room.
                         items:
-                          type: object
-                          title: Invite Room State Event
-                          properties:
-                            type:
-                              type: string
-                              description: The type of event.
-                              example: "m.room.join_rules"
-                            state_key:
-                              type: string
-                              description: The state key for the event. May be an empty string.
-                              example: ""
-                            content:
-                              type: object
-                              description: The content for the event.
-                            sender:
-                              type: string
-                              description: The sender of the event.
-                              example: "@someone:matrix.org"
-                          required: ['type', 'state_key', 'content', 'sender']
+                          $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml"
                         example: [
                           {
                             "type": "m.room.join_rules",

api/server-server/invites-v2.yaml

@@ -83,25 +83,7 @@ paths:
                   identify the room. The recommended events to include are the join rules,
                   canonical alias, avatar, and name of the room.
                 items:
-                  type: object
-                  title: Invite Room State Event
-                  properties:
-                    type:
-                      type: string
-                      description: The type of event.
-                      example: "m.room.join_rules"
-                    state_key:
-                      type: string
-                      description: The state key for the event. May be an empty string.
-                      example: ""
-                    content:
-                      type: object
-                      description: The content for the event.
-                    sender:
-                      type: string
-                      description: The sender of the event.
-                      example: "@someone:matrix.org"
-                  required: ['type', 'state_key', 'content', 'sender']
+                  $ref: "../client-server/definitions/event-schemas/schema/stripped_state.yaml"
                 example: [
                   {
                     "type": "m.room.join_rules",

changelogs/client_server/newsfragments/2067.clarification

@@ -0,0 +1 @@
+Clarify exactly what invite_room_state consists of.

changelogs/server_server/newsfragments/2067.clarification

@@ -0,0 +1 @@
+Clarify exactly what invite_room_state consists of.

event-schemas/examples/m.room.member$invite_room_state

@@ -7,21 +7,8 @@
   },
   "unsigned": {
     "age": 1234,
-    "invite_room_state": [
-      {
-        "type": "m.room.name",
-        "state_key": "",
-        "content": {
-          "name": "Forest of Magic"
-        }
-      },
-      {
-        "type": "m.room.join_rules",
-        "state_key": "",
-        "content": {
-          "join_rule": "invite"
-        }
-      }
-    ]
+    "invite_room_state": {
+      "$ref": "stripped_state.json"
+    }
   }
 }

event-schemas/examples/stripped_state.json

@@ -0,0 +1,18 @@
+[
+    {
+        "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"
+        }
+    }
+]

event-schemas/schema/m.room.member

@@ -81,24 +81,7 @@ properties:
           invite_room_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 joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; 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.'
             items:
-              description: 'A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.'
-              properties:
-                content:
-                  description: The ``content`` for the event.
-                  title: EventContent
-                  type: object
-                state_key:
-                  description: The ``state_key`` for the event.
-                  type: string
-                type:
-                  description: The ``type`` for the event.
-                  type: string
-              required:
-                - type
-                - state_key
-                - content
-              title: StrippedState
-              type: object
+              $ref: "stripped_state.yaml"
             type: array
     required:
       - membership

event-schemas/schema/stripped_state.yaml

@@ -0,0 +1,44 @@
+# Copyright 2019 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.
+
+# Note: this, and the example, are in the `event-schemas` directory because
+# the CS API uses a symlink. In order for the `m.room.member` event to
+# reference this, we'd need to use relative pathing. The symlink makes this
+# difficult because the schema would be at two different locations, with
+# different relative pathing.
+
+title: StrippedState
+type: object
+description: |-
+  A stripped down state event, with only the ``type``, ``state_key``,
+  ``sender``, and ``content`` keys.
+properties:
+  content:
+    description: The ``content`` for the event.
+    title: EventContent
+    type: object
+  state_key:
+    description: The ``state_key`` for the event.
+    type: string
+  type:
+    description: The ``type`` for the event.
+    type: string
+  sender:
+    description: The ``sender`` for the event.
+    type: string
+required:
+  - type
+  - state_key
+  - content
+  - sender