Add title/desc to lots of event schemas, add missing keys (e.g. avatar_url, displayname), add required keys section to spec.

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

@@ -1,7 +1,9 @@
 {
   "age": 242352,
   "content": {
-    "membership": "join"
+    "membership": "join",
+    "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
+    "displayname": "Alice Margatroid"
   },
   "state_key": "@alice:localhost",
   "origin_server_ts": 1431961217939,

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

@@ -1,6 +1,8 @@
 {
   "age": 242352,
-  "content": {},
+  "content": {
+    "reason": "Spamming"
+  },
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.redaction",

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

@@ -1,6 +1,18 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "Informs the room about what room aliases it has been given.",
+    "description": "This event is sent by a homeserver directly to inform of changes
+    to the list of aliases it knows about for that room. The
+    ``state_key`` for this event is set to the homeserver which
+    owns the room alias. The entire set of known aliases for the
+    room is the union of all the ``m.room.aliases`` events, one
+    for each homeserver. Clients **should** check the validity
+    of any room alias given in this list before presenting it to
+    the user as trusted fact. The lists given by this event
+    should be considered simply as advice on which aliases
+    might exist, for which the client can perform the lookup to
+    confirm whether it receives the correct room ID.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],

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

@@ -1,6 +1,9 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "The first event in the room.",
+    "description": "This is the first event in a room and cannot be changed. It acts
+    as the root of all other events.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],

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

@@ -1,6 +1,11 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "Describes how users are allowed to join the room.",
+    "description": "A room may be ``public`` meaning anyone can join the room without
+    any prior action. Alternatively, it can be ``invite`` meaning that
+    a user who wishes to join the room must first receive an invite to
+    the room from someone already inside of the room.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],

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

@@ -1,6 +1,13 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "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.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],
@@ -11,6 +18,12 @@
                 "membership": {
                     "type": "string",
                     "enum": ["invite","join","knock","leave","ban"]
+                },
+                "avatar_url": {
+                    "type": "string"
+                },
+                "displayname": {
+                    "type": "string"
                 }
             },
             "required": ["membership"]

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

@@ -1,6 +1,12 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "A human-readable message in the room.",
+    "description": "This event is used when sending messages in a room. Messages are
+    not limited to be text. The ``msgtype`` key outlines the type
+    of message, e.g. text, audio, image, video, etc. The ``body`` key
+    is text and MUST be used with every kind of ``msgtype`` as a 
+    fallback mechanism for when a client cannot render a message.",
     "allOf": [{
         "$ref": "core#/definitions/room_event"
     }],

event-schemas/schema/v1/m.room.message.feedback

@@ -1,6 +1,13 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "A receipt for a message. N.B. not implemented in Synapse, and superceded in
+    v2 CS API by the ``relates_to`` event field.",
+    "description": "Feedback events are events sent to acknowledge a message in some way. There
+    are two supported acknowledgements: ``delivered`` (sent when the event has
+    been received) and ``read`` (sent when the event has been observed by the
+    end-user). The ``target_event_id`` should reference the ``m.room.message``
+    event being acknowledged.",
     "allOf": [{
         "$ref": "core#/definitions/room_event"
     }],

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

@@ -1,5 +1,12 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
+    "title": "Set the human-readable name for the room.",
+    "description": "A room has an opaque room ID which is not human-friendly to read. A room
+    alias is human-friendly, but not all rooms have room aliases. The room 
+    name is a human-friendly string designed to be displayed to the end-user.
+    The room name is not unique, as multiple rooms can have the same room name
+    set. The room name can also be set when creating a room using ``/createRoom``
+    with the ``name`` key.",
     "type": "object",
     "allOf": [{
         "$ref": "core#/definitions/state_event"

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

@@ -1,6 +1,20 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "Defines the power levels (privileges) of users in the room.",
+    "description": "This event specifies the minimum level a user must have in order
+    to perform a certain action. It also specifies the levels
+    of each user in the room. If a ``user_id`` is in the 
+    ``users`` list, then that ``user_id`` has the associated 
+    power level. Otherwise they have the default level 
+    ``users_default``. If ``users_default`` is not supplied,
+    it is assumed to be 0. The level required to send a
+    certain event is governed by ``events``, ``state_default``
+    and ``events_default``. If an event type is specified in 
+    ``events``, then the user must have at least the level
+    specified in order to send that event. If the event type is
+    not supplied, it defaults to ``events_default`` for Message
+    Events and ``state_default`` for State Events.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],
@@ -28,7 +42,7 @@
                 }
             },
             "required": ["ban","events","events_default","kick","redact",
-                         "state_default","users","users_default"]
+                         "state_default","users"]
         },
         "state_key": {
             "type": "string",

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

@@ -1,6 +1,15 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "Indicates a previous event has been redacted.",
+    "description": "Events can be redacted by either room or server admins. Redacting an event
+    means that all keys not required by the protocol are stripped off, allowing
+    admins to remove offensive or illegal content that may have been attached
+    to any event. This cannot be undone, allowing server owners to physically
+    delete the offending data.  There is also a concept of a moderator hiding a
+    message event, which can be undone, but cannot be applied to state
+    events. The event that has been redacted is specified in the ``redacts``
+    event level key.",
     "allOf": [{
         "$ref": "core#/definitions/room_event"
     }],

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

@@ -1,6 +1,12 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object",
+    "title": "Set a topic for the room.",
+    "description": "A topic is a short message detailing what is currently being discussed in
+    the room.  It can also be used as a way to display extra information about
+    the room, which may not be suitable for the room name. The room topic can
+    also be set when creating a room using ``/createRoom`` with the ``topic``
+    key.",
     "allOf": [{
         "$ref": "core#/definitions/state_event"
     }],

templating/build.py

@@ -66,8 +66,8 @@ def check_unaccessed(name, store):
 
 def main():
     # add a template filter to produce pretty pretty JSON
-    def jsonify(input, pre_whitespace=0):
-        code = json.dumps(input, indent=4)
+    def jsonify(input, indent=None, pre_whitespace=0):
+        code = json.dumps(input, indent=indent)
         if pre_whitespace:
             code = code.replace("\n", ("\n" +" "*pre_whitespace))
 

templating/internal/sections.py

@@ -8,6 +8,8 @@ def _render_section_room_events(env, units):
     schemas = units.get("event-schemas")
     sections = []
     for event_name in schemas:
+        if not event_name.startswith("m.room"):
+            continue
         sections.append(template.render(
             example=examples[event_name], 
             event=schemas[event_name]

templating/internal/units.py

@@ -62,14 +62,16 @@ def _load_schemas():
     for filename in os.listdir(path):
         if not filename.startswith("m."):
             continue
+        print "Reading %s" % os.path.join(path, filename)
         with open(os.path.join(path, filename), "r") as f:
-            json_schema = json.loads(f.read())
+            json_schema = json.loads(f.read(), strict=False)
             schema = {
                 "typeof": None,
                 "type": None,
                 "summary": None,
                 "desc": None,
-                "json_format": None
+                "json_format": None,
+                "required_keys": None
             }
 
             # add typeof
@@ -94,6 +96,12 @@ def _load_schemas():
             if content_props:
                 schema["json_format"] = format_for_obj(content_props)
 
+            # add required_keys
+            schema["required_keys"] = prop(
+                json_schema, "properties/content/required"
+            )
+
+
 
             schemata[filename] = schema
     return schemata

templating/templates/events.tmpl

@@ -5,11 +5,13 @@
     {{event.typeof}}
   Description:
     {{event.desc}}
+  Required Keys:
+    ``{{event.required_keys | jsonify}}``
 
   JSON Format::
 
-    {{event.json_format | jsonify(4)}}
+    {{event.json_format | jsonify(4, 4)}}
 
   Example::
 
-    {{example.content | jsonify(4)}}
+    {{example.content | jsonify(4, 4)}}