From 9bf0103ef359202026ffce958c243b898a828f9e Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Thu, 6 Jun 2019 14:36:30 -0600
Subject: [PATCH] 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               |  2 +-
 .../definitions/single_pdu_transaction.yaml   | 32 ++++++++++++++++++
 .../unlimited_pdu_transaction.yaml            | 33 +++++++++++++++++++
 api/server-server/events.yaml                 |  2 +-
 .../newsfragments/2095.clarification          |  1 +
 5 files changed, 68 insertions(+), 2 deletions(-)
 create mode 100644 api/server-server/definitions/single_pdu_transaction.yaml
 create mode 100644 api/server-server/definitions/unlimited_pdu_transaction.yaml
 create mode 100644 changelogs/server_server/newsfragments/2095.clarification

diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml
index 0da0e234..2ed6298c 100644
--- a/api/server-server/backfill.yaml
+++ b/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
diff --git a/api/server-server/definitions/single_pdu_transaction.yaml b/api/server-server/definitions/single_pdu_transaction.yaml
new file mode 100644
index 00000000..ff682a44
--- /dev/null
+++ b/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']
diff --git a/api/server-server/definitions/unlimited_pdu_transaction.yaml b/api/server-server/definitions/unlimited_pdu_transaction.yaml
new file mode 100644
index 00000000..0fc31ee4
--- /dev/null
+++ b/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']
diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml
index 1f1a802d..1f8ee537 100644
--- a/api/server-server/events.yaml
+++ b/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"
diff --git a/changelogs/server_server/newsfragments/2095.clarification b/changelogs/server_server/newsfragments/2095.clarification
new file mode 100644
index 00000000..66257e17
--- /dev/null
+++ b/changelogs/server_server/newsfragments/2095.clarification
@@ -0,0 +1 @@
+Clarify how many PDUs are contained in transaction objects for various endpoints.