Clarify how many PDUs are in a given transaction object

Fixes https://github.com/matrix-org/matrix-doc/issues/2093

api/server-server/backfill.yaml

@@ -64,7 +64,7 @@ paths:
             A transaction containing the PDUs that preceded the given event(s), including the given
             event(s), up to the given limit.
           schema:
-            $ref: "definitions/transaction.yaml"
+            $ref: "definitions/unlimited_pdu_transaction.yaml"
   "/get_missing_events/{roomId}":
     post:
       summary: Retrieves events that the sender is missing

api/server-server/definitions/single_pdu_transaction.yaml

@@ -0,0 +1,32 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+allOf:
+  - $ref: "transaction.yaml"
+properties:
+  pdus:
+    type: array
+    description: |-
+      A single PDU. 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>`_ 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/definitions/unlimited_pdu_transaction.yaml

@@ -0,0 +1,33 @@
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+allOf:
+  - $ref: "transaction.yaml"
+properties:
+  pdus:
+    type: array
+    description: |-
+      List of persistent updates to rooms. 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>`_ 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/events.yaml

@@ -156,4 +156,4 @@ paths:
         200:
           description: A transaction containing a single PDU which is the event requested.
           schema:
-            $ref: "definitions/transaction.yaml"
+            $ref: "definitions/single_pdu_transaction.yaml"

changelogs/server_server/newsfragments/2095.clarification

@@ -0,0 +1 @@
+Clarify how many PDUs are contained in transaction objects for various endpoints.