Make the backfill response aware of event format changes

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"}
+                {"see_room_version_spec": "The event format changes depending on the room version."}
               ]
             }

api/server-server/definitions/transaction.yaml

@@ -26,12 +26,21 @@ properties:
     type: integer
     format: int64
     description: |-
-      POSIX timestamp in milliseconds on originating homeserver when this 
+      POSIX timestamp in milliseconds on originating homeserver when this
       transaction started.
     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 version 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: {"see_room_version_spec": "The event format changes depending on the room version."}
 required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/examples/transaction.json

@@ -1,5 +1,7 @@
 {
     "origin": "matrix.org",
     "origin_server_ts": 1234567890,
-    "pdus": [{"$ref": "pdu.json"}]
-}
+    "pdus": [{
+        "see_room_version_spec": "The event format changes depending on the room version."
+    }]
+}