Merge pull request #113 from matrix-org/invite-room-state

Add invite_room_state to spec

event-schemas/examples/v1/m.room.member

@@ -20,6 +20,22 @@
         "sender": "@zun:zun.soft"
     }
   },
+  "invite_room_state": [
+    {
+      "type": "m.room.name",
+      "state_key": "",
+      "content": {
+        "name": "Forest of Magic"
+      }
+    },
+    {
+      "type": "m.room.join_rules",
+      "state_key": "",
+      "content": {
+        "join_rules": "invite"
+      }
+    }
+  ],
   "state_key": "@alice:localhost",
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/schema/v1/m.room.member

@@ -1,7 +1,7 @@
 {
     "type": "object",
     "title": "The current membership state of a user in the room.",
-    "description": "Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. The ``third_party_invite`` property will be set if the invite was an ``m.room.third_party_invite`` event, and absent if the invite was an ``m.room.member`` event.",
+    "description": "Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. \n\nThe ``third_party_invite`` property will be set if the invite was an ``m.room.third_party_invite`` event, and absent if the invite was an ``m.room.member`` event.\n\nThis event also includes an ``invite_room_state`` key **outside the** ``content`` **key**. This contains an array of ``StrippedState`` Events. These events provide information on a few select state events such as the room name.",
     "allOf": [{
         "$ref": "core-event-schema/state_event.json"
     }],
@@ -24,7 +24,7 @@
                 },
                 "third_party_invite": {
                     "type": "object",
-                    "title": "invite",
+                    "title": "Invite",
                     "properties": {
                         "token": {
                             "type": "string",
@@ -81,17 +81,23 @@
             "description": "A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``",
             "items": {
                 "type": "object",
-                "title": "StateEvent",
+                "title": "StrippedState",
                 "description": "A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.",
+                "required": ["type", "state_key", "content"],
                 "properties": {
                     "type": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "The ``type`` for the event.",
+                        "enum": ["m.room.join_rules", "m.room.canonical_alias", "m.room.avatar", "m.room.name"]
                     },
                     "state_key": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "The ``state_key`` for the event."
                     },
                     "content": {
-                        "type": "object"
+                        "title": "EventContent",
+                        "type": "object",
+                        "description": "The ``content`` for the event."
                     }
                 }
             }

templating/matrix_templates/templates/events.tmpl

@@ -7,18 +7,18 @@
 {% for table in event.content_fields -%}
 {{"``"+table.title+"``" if table.title else "" }}
 
-================== ================= ===========================================
+======================= ================= ===========================================
-   {{table.title or "Content"}} Key          Type                 Description
+   {{table.title or "Content"}} Key                Type                 Description
-================== ================= ===========================================
+======================= ================= ===========================================
 {% for row in table.rows -%}
 {# -#}
 {# Row type needs to prepend spaces to line up with the type column (19 ch) -#}
 {# Desc needs to prepend the required text (maybe) and prepend spaces too -#}
 {#      It also needs to then wrap inside the desc col (43 ch width) -#}
 {# -#}
-{{row.key}}{{row.type|indent(19-row.key|length)}}{{row.desc|wrap(43,row.req_str | indent(18 - (row.type|length))) |indent_block(37)}}
+{{row.key}}{{row.type|indent(24-row.key|length)}}{{row.desc|wrap(43,row.req_str | indent(18 - (row.type|length))) |indent_block(42)}}
 {% endfor -%}
-================== ================= ===========================================
+======================= ================= ===========================================
 
 {% endfor %}
 Example::

templating/matrix_templates/units.py

@@ -532,6 +532,15 @@ class MatrixUnits(Units):
                     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_json_schema_object_fields(
+                        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"