Move invite_room_state to the correct place in the client-server API

changelogs/client_server/newsfragments/1568.clarification

@@ -0,0 +1 @@
+Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.

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

@@ -5,22 +5,24 @@
     "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
     "displayname": "Alice Margatroid"
   },
-  "invite_room_state": [
-    {
-      "type": "m.room.name",
-      "state_key": "",
-      "content": {
-        "name": "Forest of Magic"
+  "unsigned": {
+    "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"
+        }
       }
-    },
-    {
-      "type": "m.room.join_rules",
-      "state_key": "",
-      "content": {
-        "join_rule": "invite"
-      }
-    }
-  ],
+    ]
+  },
   "state_key": "@alice:localhost",
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/schema/m.room.member

@@ -18,7 +18,9 @@ description: |-
 
   The ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.
 
-  This event may also include an ``invite_room_state`` key **outside the** ``content`` **key**. If present, this contains an array of ``StrippedState`` Events. These events provide information on a subset of state events such as the room name.
+  This event may also include an ``invite_room_state`` key inside the event's ``unsigned`` data.
+  If present, this contains an array of ``StrippedState`` Events. These events provide information
+  on a subset of state events such as the room name.
 properties:
   content:
     properties:
@@ -71,32 +73,37 @@ properties:
           - signed
         title: Invite
         type: object
+      unsigned:
+        type: object
+        title: UnsignedData
+        description: Contains optional extra information about the event.
+        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
+            type: array
     required:
       - membership
     title: EventContent
     type: object
-  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
-    type: array
   state_key:
     description: The ``user_id`` this membership event relates to.
     type: string

scripts/templating/matrix_templates/units.py

@@ -875,15 +875,6 @@ def read_event_schema(self, filepath):
             Units.prop(json_schema, "properties/content")
         )
 
-        # This is horrible because we're special casing a key on m.room.member.
-        # We need to do this because we want to document a non-content object.
-        if schema["type"] == "m.room.member":
-            invite_room_state = get_tables_for_schema(
-                json_schema["properties"]["invite_room_state"]["items"],
-            )
-            schema["content_fields"].extend(invite_room_state)
-
-
         # grab msgtype if it is the right kind of event
         msgtype = Units.prop(
             json_schema, "properties/content/properties/msgtype/enum"