Merge pull request #1834 from matrix-org/travis/misc/event-formats

Represent event format changes more clearly in the spec

api/check_examples.py

@@ -75,6 +75,12 @@ def check_response(filepath, request, code, response):
                 filepath, request, code
             ))
             check_schema(filepath, example, schema)
+        except jsonschema.SchemaError as error:
+            for suberror in sorted(error.context, key=lambda e: e.schema_path):
+                print(list(suberror.schema_path), suberror.message, sep=", ")
+            raise ValueError("Error validating JSON schema for %r %r" % (
+                request, code
+            ), e)
         except Exception as e:
             raise ValueError("Error validating JSON schema for %r %r" % (
                 request, code

api/server-server/backfill.yaml

@@ -65,22 +65,6 @@ paths:
             event(s), up to the given limit.
           schema:
             $ref: "definitions/transaction.yaml"
-          # Override the example to show the response of the request a bit better
-          examples:
-            application/json: {
-              "$ref": "examples/transaction.json",
-              "pdus": [
-                {
-                  "$ref": "pdu.json",
-                  "room_id": "!SomeRoom:matrix.org",
-                  "event_id": "$abc123:matrix.org"
-                },
-                {
-                  "$ref": "pdu.json",
-                  "room_id": "!SomeRoom:matrix.org"
-                },
-              ]
-            }
   "/get_missing_events/{roomId}":
     post:
       summary: Retrieves events that the sender is missing
@@ -114,14 +98,14 @@ paths:
               earliest_events:
                 type: array
                 description: |-
-                  The latest events that the sender already has. These are skipped when retrieving
+                  The latest event IDs that the sender already has. These are skipped when retrieving
                   the previous events of ``latest_events``.
                 items:
                   type: string
                 example: ["$missing_event:example.org"]
               latest_events:
                 type: array
-                description: The events to retrieve the previous events for.
+                description: The event IDs to retrieve the previous events for.
                 items:
                   type: string
                 example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"]
@@ -136,13 +120,16 @@ paths:
             properties:
               events:
                 type: array
-                description: The missing events.
+                description: |-
+                  The missing events. The event format varies depending on the room version - check
+                  the `room version specification`_ for precise event formats.
                 items:
-                  $ref: definitions/pdu.yaml
+                  type: object
+                  title: PDU
             required: ['events']
           examples:
             application/json: {
               "events": [
-                {"$ref": "examples/pdu.json"}
+                {"$ref": "examples/minimal_pdu.json"}
               ]
             }

api/server-server/definitions/invite_event.yaml

@@ -1,4 +1,4 @@
-# Copyright 2018 New Vector Ltd
+# Copyright 2018-2019 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,15 +13,14 @@
 # limitations under the License.
 type: object
 title: Invite Event
-description: An invite event
+description: |-
+  An invite event. Note that events have a different format depending on the
+  room version - check the `room version specification`_ for precise event formats.
 allOf:
-  - $ref: "pdu.yaml"
   - type: object
     properties:
-      # Note: we override a bunch of parameters to change their descriptions
       sender:
         type: string
-        # TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite
         description: |-
           The matrix ID of the user who sent the original ``m.room.third_party_invite``.
         example: "@someone:example.org"
@@ -55,33 +54,10 @@ allOf:
             description: The value ``invite``.
             example: "invite"
         required: ['membership']
-      auth_events:
-        type: array
-        description: |-
-          An event reference list containing the authorization events that would
-          allow the member to be invited to the room.
-        items:
-          type: array
-          maxItems: 2
-          minItems: 2
-          items:
-            - type: string
-              title: Event ID
-              example: "$abc123:matrix.org"
-            - type: object
-              title: Event Hash
-              example: {
-                "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-              }
-              properties:
-                sha256:
-                  type: string
-                  description: The event hash.
-                  example: abase64encodedsha256hashshouldbe43byteslong
-              required: ['sha256']
-      redacts:
-        type: string
-        description: Not used.
     required:
-      # Every other field is already flagged as required by the $ref
       - state_key
+      - sender
+      - origin
+      - origin_server_ts
+      - type
+      - content

api/server-server/definitions/transaction.yaml

@@ -31,7 +31,17 @@ properties:
     example: 1532991320875
   pdus:
     type: array
-    description: List of persistent updates to rooms. Must not include more than 50 PDUs.
+    description: |-
+      List of persistent updates to rooms. Must not include more than 50 PDUs. Note that
+      events have a different format depending on the room version - check the
+      `room version specification`_ for precise event formats.
     items:
-      $ref: "pdu.yaml"
+      type: object
+      title: PDU
+      description: |-
+        The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
+        on the room version - check the `room version specification`_ for precise event formats.
+      properties: []
+      example:
+        $ref: "../examples/minimal_pdu.json"
 required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/event_auth.yaml

@@ -58,10 +58,19 @@ paths:
                 type: array
                 description: |-
                   The full set of authorization events that make up the state of
-                  the room, and their authorization events, recursively. 
+                  the room, and their authorization events, recursively. Note that
+                  events have a different format depending on the room version -
+                  check the `room version specification`_ for precise event formats.
                 items:
-                  $ref: "definitions/pdu.yaml"
+                  type: object
-                example: [{"$ref": "examples/pdu.json"}]
+                  title: PDU
+                  description: |-
+                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    varies depending on the room version - check the `room version specification`_
+                    for precise event formats.
+                  properties: []
+                  example:
+                    $ref: "examples/minimal_pdu.json"
             required: ['auth_chain']
   "/query_auth/{roomId}/{eventId}":
     post:
@@ -98,10 +107,20 @@ paths:
             properties:
               auth_chain:
                 type: array
-                description: The auth chain (the "remote auth").
+                description: |-
+                  The auth chain (the "remote auth"). Note that events have a different
+                  format depending on the room version - check the `room version specification`_
+                  for precise event formats.
                 items:
-                  $ref: "definitions/pdu.yaml"
+                  type: object
-                example: [{"$ref": "examples/pdu.json"}]
+                  title: PDU
+                  description: |-
+                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    varies depending on the room version - check the `room version specification`_
+                    for precise event formats.
+                  properties: []
+                  example:
+                    $ref: "examples/minimal_pdu.json"
               missing:
                 type: array
                 description: |-
@@ -142,10 +161,19 @@ paths:
                 type: array
                 description: |-
                   The auth chain the receiver has, and used to determine the auth
-                  chain differences (the "local auth").
+                  chain differences (the "local auth"). Note that events have a different
+                  format depending on the room version - check the `room version specification`_
+                  for precise event formats.
                 items:
-                  $ref: "definitions/pdu.yaml"
+                  type: object
-                example: [{"$ref": "examples/pdu.json"}]
+                  title: PDU
+                  description: |-
+                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    varies depending on the room version - check the `room version specification`_
+                    for precise event formats.
+                  properties: []
+                  example:
+                    $ref: "examples/minimal_pdu.json"
               missing:
                 type: array
                 description: |-

api/server-server/events.yaml

@@ -59,17 +59,35 @@ paths:
                 type: array
                 description: |-
                   The full set of authorization events that make up the state
-                  of the room, and their authorization events, recursively.
+                  of the room, and their authorization events, recursively. Note that
+                  events have a different format depending on the room version -
+                  check the `room version specification`_ for precise event formats.
                 items:
-                  $ref: "definitions/pdu.yaml"
+                  type: object
-                example: [{"$ref": "examples/pdu.json"}]
+                  title: PDU
+                  description: |-
+                    The `PDUs <#pdus>`_ contained in the auth chain. The event format
+                    varies depending on the room version - check the `room version specification`_
+                    for precise event formats.
+                  properties: []
+                  example:
+                    $ref: "examples/minimal_pdu.json"
               pdus:
                 type: array
                 description: |-
-                  The fully resolved state of the room at the given event.
+                  The fully resolved state of the room at the given event. Note that
+                  events have a different format depending on the room version -
+                  check the `room version specification`_ for precise event formats.
                 items:
-                  $ref: "definitions/pdu.yaml"
+                  type: object
-                example: [{"$ref": "examples/pdu.json"}]
+                  title: PDU
+                  description: |-
+                    The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format
+                    varies depending on the room version - check the `room version specification`_
+                    for precise event formats.
+                  properties: []
+                  example:
+                    $ref: "examples/minimal_pdu.json"
             required: ['auth_chain', 'pdus']
   "/state_ids/{roomId}":
     get:

api/server-server/examples/minimal_pdu.json

@@ -0,0 +1,7 @@
+{
+    "type": "m.room.minimal_pdu",
+    "room_id": "!somewhere:example.org",
+    "content": {
+        "see_room_version_spec": "The event format changes depending on the room version."
+    }
+}

api/server-server/examples/transaction.json

@@ -1,5 +1,7 @@
 {
     "origin": "matrix.org",
     "origin_server_ts": 1234567890,
-    "pdus": [{"$ref": "pdu.json"}]
+    "pdus": [{
+        "$ref": "minimal_pdu.json"
+    }]
 }

api/server-server/invites-v1.yaml

@@ -38,6 +38,11 @@ paths:
         Servers should prefer to use the v2 API for invites instead of the v1 API. Servers
         which receive a v1 invite request must assume that the room version is either ``"1"``
         or ``"2"``.
+
+        Note that events have a different format depending on the room version - check the
+        `room version specification`_ for precise event formats. **The request and response
+        bodies here describe the common event fields in more detail and may be missing other
+        required fields for a PDU.**
       operationId: sendInviteV1
       security:
         - signedRequest: []
@@ -107,9 +112,12 @@ paths:
                           }
                         ]
           example: {
-            "$ref": "examples/pdu.json",
+            "$ref": "examples/minimal_pdu.json",
             "type": "m.room.member",
             "state_key": "@joe:elsewhere.com",
+            "origin": "example.org",
+            "origin_server_ts": 1549041175876,
+            "sender": "@someone:example.org",
             "unsigned": {
               "invite_room_state": [
                 {
@@ -143,7 +151,8 @@ paths:
         200:
           description: |-
             The event with the invited server's signature added. All other fields of the events
-            should remain untouched.
+            should remain untouched. Note that events have a different format depending on the
+            room version - check the `room version specification`_ for precise event formats.
           schema:
             type: array
             minItems: 2
@@ -164,9 +173,12 @@ paths:
               200,
               {
                 "event":  {
-                  "$ref": "examples/pdu.json",
+                  "$ref": "examples/minimal_pdu.json",
                   "type": "m.room.member",
                   "state_key": "@someone:example.org",
+                  "origin": "example.org",
+                  "origin_server_ts": 1549041175876,
+                  "sender": "@someone:example.org",
                   "unsigned": {
                     "invite_room_state": [
                       {

api/server-server/invites-v2.yaml

@@ -42,6 +42,11 @@ paths:
         This endpoint is preferred over the v1 API as it is more useful for servers. Senders
         which receive a 400 or 404 response to this endpoint should retry using the v1
         API as the server may be older, if the room version is "1" or "2".
+
+        Note that events have a different format depending on the room version - check the
+        `room version specification`_ for precise event formats. **The request and response
+        bodies here describe the common event fields in more detail and may be missing other
+        required fields for a PDU.**
       operationId: sendInviteV2
       security:
         - signedRequest: []
@@ -111,9 +116,12 @@ paths:
           example: {
             "room_version": "2",
             "event": {
-              "$ref": "examples/pdu.json",
+              "$ref": "examples/minimal_pdu.json",
               "type": "m.room.member",
               "state_key": "@joe:elsewhere.com",
+              "origin": "example.org",
+              "origin_server_ts": 1549041175876,
+              "sender": "@someone:example.org",
               "content": {
                   "membership": "invite"
               },
@@ -146,7 +154,8 @@ paths:
         200:
           description: |-
             The event with the invited server's signature added. All other fields of the events
-            should remain untouched.
+            should remain untouched. Note that events have a different format depending on the
+            room version - check the `room version specification`_ for precise event formats.
           schema:
             type: object
             description: An object containing the signed invite event.
@@ -158,9 +167,12 @@ paths:
           examples:
             application/json: {
               "event":  {
-                "$ref": "examples/pdu.json",
+                "$ref": "examples/minimal_pdu.json",
                 "type": "m.room.member",
                 "state_key": "@someone:example.org",
+                "origin": "example.org",
+                "origin_server_ts": 1549041175876,
+                "sender": "@someone:example.org",
                 "unsigned": {
                   "invite_room_state": [
                     {

api/server-server/joins.yaml

@@ -61,7 +61,11 @@ paths:
       responses:
         200:
           description: |-
-            A template to be used for the rest of the `Joining Rooms`_ handshake.
+            A template to be used for the rest of the `Joining Rooms`_ handshake. Note that
+            events have a different format depending on the  room version - check the
+            `room version specification`_ for precise event formats. **The response body
+            here describes the common event fields in more detail and may be missing other
+            required fields for a PDU.**
           schema:
             type: object
             properties:
@@ -72,13 +76,13 @@ paths:
                   the room version is assumed to be either "1" or "2".
                 example: "2"
               event:
-                allOf:
+                description: |-
-                  - $ref: "definitions/unsigned_pdu.yaml"
+                  An unsigned template event. Note that events have a different format
-                  - description: |-
+                  depending on the room version - check the `room version specification`_
-                      An unsigned template event.
+                  for precise event formats.
                 type: object
+                title: Event Template
                 properties:
-                      # Note: we override a bunch of parameters to change their descriptions
                   sender:
                     type: string
                     description: The user ID of the joining member.
@@ -111,57 +115,26 @@ paths:
                         description: The value ``join``.
                         example: "join"
                     required: ['membership']
-                      depth:
-                        type: integer
-                        description: This field must be present but is ignored; it may be 0.
-                        example: 12
-                      auth_events:
-                        type: array
-                        description: |-
-                          An event reference list containing the authorization events that would
-                          allow the member to join the room. This should normally be the
-                          ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
-                          events.
-                        items:
-                          type: array
-                          maxItems: 2
-                          minItems: 2
-                          items:
-                            - type: string
-                              title: Event ID
-                              example: "$abc123:matrix.org"
-                            - type: object
-                              title: Event Hash
-                              example: {
-                                "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-                              }
-                              properties:
-                                sha256:
-                                  type: string
-                                  description: The event hash.
-                                  example: abase64encodedsha256hashshouldbe43byteslong
-                              required: ['sha256']
-                      redacts:
-                        type: string
-                        description: Not used.
                 required:
-                      # Every other field is already flagged as required by the $ref
                   - state_key
+                  - origin
+                  - origin_server_ts
+                  - type
+                  - content
+                  - sender
           examples:
             application/json: {
               "room_version": "2",
               "event": {
-                "$ref": "examples/unsigned_pdu.json",
+                "$ref": "examples/minimal_pdu.json",
                 "type": "m.room.member",
                 "state_key": "@someone:example.org",
+                "origin": "example.org",
+                "origin_server_ts": 1549041175876,
+                "sender": "@someone:example.org",
                 "content": {
                   "membership": "join"
-                },
+                }
-                "auth_events": [
-                  ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
-                  ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
-                  ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
-                ]
               }
             }
         400:
@@ -193,7 +166,12 @@ paths:
       summary: Submit a signed join event to a resident server
       description: |-
         Submits a signed join event to the resident server for it
-        to accept it into the room's graph.
+        to accept it into the room's graph. Note that events have
+        a different format depending on the  room version - check
+        the `room version specification`_ for precise event formats.
+        **The request and response body here describes the common
+        event fields in more detail and may be missing other required
+        fields for a PDU.**
       operationId: sendJoin
       security:
         - signedRequest: []
@@ -215,11 +193,8 @@ paths:
           type: object
           required: true
           schema:
-            allOf:
+            type: object
-              - $ref: "definitions/pdu.yaml"
-              - type: object
             properties:
-                  # Note: we override a bunch of parameters to change their descriptions
               sender:
                 type: string
                 description: The user ID of the joining member.
@@ -252,44 +227,20 @@ paths:
                     description: The value ``join``.
                     example: "join"
                 required: ['membership']
-                  depth:
-                    type: integer
-                    description: This field must be present but is ignored; it may be 0.
-                    example: 12
-                  auth_events:
-                    type: array
-                    description: |-
-                      An event reference list containing the authorization events that would
-                      allow the member to join the room.
-                    items:
-                      type: array
-                      maxItems: 2
-                      minItems: 2
-                      items:
-                        - type: string
-                          title: Event ID
-                          example: "$abc123:matrix.org"
-                        - type: object
-                          title: Event Hash
-                          example: {
-                            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-                          }
-                          properties:
-                            sha256:
-                              type: string
-                              description: The event hash.
-                              example: abase64encodedsha256hashshouldbe43byteslong
-                          required: ['sha256']
-                  redacts:
-                    type: string
-                    description: Not used.
             required:
-                  # Every other field is already flagged as required by the $ref
               - state_key
+              - sender
+              - origin
+              - origin_server_ts
+              - type
+              - content
           example: {
-            "$ref": "examples/pdu.json",
+            "$ref": "examples/minimal_pdu.json",
             "type": "m.room.member",
             "state_key": "@someone:example.org",
+            "origin": "example.org",
+            "origin_server_ts": 1549041175876,
+            "sender": "@someone:example.org",
             "content": {
                 "membership": "join"
             }
@@ -315,25 +266,44 @@ paths:
                     description: The resident server's DNS name.
                   auth_chain:
                     type: array
-                    description: The auth chain.
+                    description: |-
+                      The auth chain. Note that events have a different format depending on
+                      the room version - check the `room version specification`_ for precise
+                      event formats.
                     items:
                       type: object
+                      title: PDU
+                      description: |-
+                        The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
+                        on the room version - check the `room version specification`_ for precise event formats.
                       schema:
-                        $ref: "definitions/pdu.yaml"
+                        type: object
+                        properties: []
+                      example:
+                        $ref: "examples/minimal_pdu.json"
                   state:
                     type: array
-                    description: The room state.
+                    description: |-
+                      The room state. The event format varies depending on the room version -
+                      check the `room version specification`_ for precise event formats.
                     items:
                       type: object
+                      title: PDU
+                      description: |-
+                        The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
+                        on the room version - check the `room version specification`_ for precise event formats.
                       schema:
-                        $ref: "definitions/pdu.yaml"
+                        type: object
+                        properties: []
+                      example:
+                        $ref: "examples/minimal_pdu.json"
                 required: ["auth_chain", "state", "origin"]
           examples:
             application/json: [
               200,
               {
                 "origin": "matrix.org",
-                "auth_chain": [{"$ref": "examples/pdu.json"}],
+                "auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
-                "state": [{"$ref": "examples/pdu.json"}]
+                "state": [{"$ref": "examples/minimal_pdu.json"}]
               }
             ]

api/server-server/leaving.yaml

@@ -52,7 +52,11 @@ paths:
       responses:
         200:
           description: |-
-            A template to be used to call ``/send_leave``.
+            A template to be used to call ``/send_leave``. Note that
+            events have a different format depending on the  room version - check the
+            `room version specification`_ for precise event formats. **The response body
+            here describes the common event fields in more detail and may be missing other
+            required fields for a PDU.**
           schema:
           schema:
             type: object
@@ -64,13 +68,13 @@ paths:
                   the room version is assumed to be either "1" or "2".
                 example: "2"
               event:
-                allOf:
+                description: |-
-                  - $ref: "definitions/unsigned_pdu.yaml"
+                  An unsigned template event. Note that events have a different format
-                  - description: |-
+                  depending on the room version - check the `room version specification`_
-                      An unsigned template event.
+                  for precise event formats.
                 type: object
+                title: Event Template
                 properties:
-                      # Note: we override a bunch of parameters to change their descriptions
                   sender:
                     type: string
                     description: The user ID of the leaving member.
@@ -103,53 +107,26 @@ paths:
                         description: The value ``leave``.
                         example: "leave"
                     required: ['membership']
-                      auth_events:
-                        type: array
-                        description: |-
-                          An event reference list containing the authorization events that would
-                          allow the member to leave the room. This should normally be the
-                          ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
-                          events.
-                        items:
-                          type: array
-                          maxItems: 2
-                          minItems: 2
-                          items:
-                            - type: string
-                              title: Event ID
-                              example: "$abc123:matrix.org"
-                            - type: object
-                              title: Event Hash
-                              example: {
-                                "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-                              }
-                              properties:
-                                sha256:
-                                  type: string
-                                  description: The event hash.
-                                  example: abase64encodedsha256hashshouldbe43byteslong
-                              required: ['sha256']
-                      redacts:
-                        type: string
-                        description: Not used.
                 required:
-                      # Every other field is already flagged as required by the $ref
                   - state_key
+                  - sender
+                  - origin
+                  - origin_server_ts
+                  - type
+                  - content
           examples:
             application/json: {
               "room_version": "2",
               "event": {
-                "$ref": "examples/unsigned_pdu.json",
+                "$ref": "examples/minimal_pdu.json",
                 "type": "m.room.member",
                 "state_key": "@someone:example.org",
+                "origin": "example.org",
+                "origin_server_ts": 1549041175876,
+                "sender": "@someone:example.org",
                 "content": {
                   "membership": "leave"
-                },
+                }
-                "auth_events": [
-                  ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
-                  ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
-                  ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
-                ]
               }
             }
         403:
@@ -167,7 +144,12 @@ paths:
       summary: Submit a signed leave event to a resident server
       description: |-
         Submits a signed leave event to the resident server for it
-        to accept it into the room's graph.
+        to accept it into the room's graph. Note that events have
+        a different format depending on the  room version - check
+        the `room version specification`_ for precise event formats.
+        **The request and response body here describes the common
+        event fields in more detail and may be missing other required
+        fields for a PDU.**
       operationId: sendLeave
       security:
         - signedRequest: []
@@ -189,11 +171,8 @@ paths:
           type: object
           required: true
           schema:
-            allOf:
+            type: object
-              - $ref: "definitions/pdu.yaml"
-              - type: object
             properties:
-                  # Note: we override a bunch of parameters to change their descriptions
               sender:
                 type: string
                 description: The user ID of the leaving member.
@@ -230,40 +209,21 @@ paths:
                 type: integer
                 description: This field must be present but is ignored; it may be 0.
                 example: 12
-                  auth_events:
-                    type: array
-                    description: |-
-                      An event reference list containing the authorization events that would
-                      allow the member to leave the room.
-                    items:
-                      type: array
-                      maxItems: 2
-                      minItems: 2
-                      items:
-                        - type: string
-                          title: Event ID
-                          example: "$abc123:matrix.org"
-                        - type: object
-                          title: Event Hash
-                          example: {
-                            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-                          }
-                          properties:
-                            sha256:
-                              type: string
-                              description: The event hash.
-                              example: abase64encodedsha256hashshouldbe43byteslong
-                          required: ['sha256']
-                  redacts:
-                    type: string
-                    description: Not used.
             required:
-                  # Every other field is already flagged as required by the $ref
               - state_key
+              - sender
+              - origin
+              - origin_server_ts
+              - type
+              - depth
+              - content
           example: {
-            "$ref": "examples/pdu.json",
+            "$ref": "examples/minimal_pdu.json",
             "type": "m.room.member",
             "state_key": "@someone:example.org",
+            "origin": "example.org",
+            "origin_server_ts": 1549041175876,
+            "sender": "@someone:example.org",
             "content": {
                 "membership": "leave"
             }

api/server-server/third_party_invite.yaml

@@ -85,6 +85,7 @@ paths:
                   third_party_invite:
                     type: object
                     description: The third party invite
+                    title: Third Party Invite
                     properties:
                       display_name:
                         type: string
@@ -97,6 +98,7 @@ paths:
                         description: |-
                           A block of content which has been signed, which servers can use to
                           verify the event.
+                        title: Invite Signatures
                         properties:
                           signatures:
                             type: object

api/server-server/transactions.yaml

@@ -37,6 +37,9 @@ paths:
 
         The sending server must wait and retry for a 200 OK response before sending a
         transaction with a different ``txnId`` to the receiving server.
+
+        Note that events have a different format depending on the  room version - check
+        the `room version specification`_ for precise event formats.
       operationId: sendTransaction
       security:
         - signedRequest: []

specification/client_server_api.rst

@@ -1267,7 +1267,21 @@ point in time::
 
   [E0]->[E1]->[E2]->[E3]->[E4]->[E5]
 
+.. WARNING::
+
+   The format of events can change depending on room version. Check the
+   `room version specification`_ for specific details on what to expect for
+   event formats. Examples contained within the client-server specification
+   are expected to be compatible with all specified room versions, however
+   some differences may still apply.
+
+   For this version of the specification, clients only need to worry about
+   the event ID format being different depending on room version. Clients
+   should not be parsing the event ID, and instead be treating it as an
+   opaque string. No changes should be required to support the currently
+   available room versions.
 
+.. _`room version specification`: ../index.html#room-versions
 
 Types of room events
 ~~~~~~~~~~~~~~~~~~~~