From 966f3c443a81643186698e28108acd91cfaf371a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 21 Dec 2022 16:23:50 +0000
Subject: [PATCH] Fix `edu_type` on EDU examples (#1383)

The top-level `example` in `edu.yaml` was overriding the individual examples
for `edu_type`. Let's fix that by getting rid of the example in `edu.yaml`.

Fixes https://github.com/matrix-org/matrix-spec/issues/805
---
 .../newsfragments/1383.clarification          |  1 +
 content/server-server-api.md                  |  2 +-
 data/api/server-server/definitions/edu.yaml   |  4 +---
 .../definitions/edu_with_example.yaml         | 21 +++++++++++++++++++
 .../definitions/transaction.yaml              |  4 ++++
 data/api/server-server/transactions.yaml      |  6 +-----
 6 files changed, 29 insertions(+), 9 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1383.clarification
 create mode 100644 data/api/server-server/definitions/edu_with_example.yaml

diff --git a/changelogs/server_server/newsfragments/1383.clarification b/changelogs/server_server/newsfragments/1383.clarification
new file mode 100644
index 00000000..f6713b87
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1383.clarification
@@ -0,0 +1 @@
+Fix `edu_type` in EDU examples.
diff --git a/content/server-server-api.md b/content/server-server-api.md
index 144736ba..724e3220 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -669,7 +669,7 @@ EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of
 "previous" IDs. They are intended to be non-persistent data such as user
 presence, typing notifications, etc.
 
-{{% definition path="api/server-server/definitions/edu" %}}
+{{% definition path="api/server-server/definitions/edu_with_example" %}}
 
 ## Room State Resolution
 
diff --git a/data/api/server-server/definitions/edu.yaml b/data/api/server-server/definitions/edu.yaml
index 0e4edcc6..1680bd60 100644
--- a/data/api/server-server/definitions/edu.yaml
+++ b/data/api/server-server/definitions/edu.yaml
@@ -15,8 +15,6 @@
 type: object
 title: Ephemeral Data Unit
 description: An ephemeral data unit.
-example:
-  $ref: "../examples/edu.json"
 properties:
   edu_type:
     type: string
@@ -25,4 +23,4 @@ properties:
   content:
     type: object
     description: The content of the ephemeral message.
-required: ['edu_type', 'content']
\ No newline at end of file
+required: ['edu_type', 'content']
diff --git a/data/api/server-server/definitions/edu_with_example.yaml b/data/api/server-server/definitions/edu_with_example.yaml
new file mode 100644
index 00000000..a5773fd1
--- /dev/null
+++ b/data/api/server-server/definitions/edu_with_example.yaml
@@ -0,0 +1,21 @@
+# Copyright 2022 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.
+
+# this file exists, separately to edu.yaml, so that the individual EDU
+# type definitions can inherit from edu.yaml without inheriting the example.
+
+allOf:
+  - $ref: edu.yaml
+  - example:
+      $ref: "../examples/edu.json"
diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml
index e20204e0..25acda9e 100644
--- a/data/api/server-server/definitions/transaction.yaml
+++ b/data/api/server-server/definitions/transaction.yaml
@@ -11,6 +11,10 @@
 # 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.
+
+# note that this definition excludes `edus`, which are typically included in
+# a transaction; this is so that it can be referenced in single_pdu_transaction.
+
 type: object
 title: Transaction
 description: Transaction
diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml
index cb801ee8..d2aab20d 100644
--- a/data/api/server-server/transactions.yaml
+++ b/data/api/server-server/transactions.yaml
@@ -66,11 +66,7 @@ paths:
                       List of ephemeral messages. May be omitted if there are no ephemeral
                       messages to be sent. Must not include more than 100 EDUs.
                     items:
-                      $ref: "definitions/edu.yaml"
-          example: {
-            "$ref": "examples/transaction.json",
-            "edus": [{"$ref": "examples/edu.json"}]
-          }
+                      $ref: "definitions/edu_with_example.yaml"
       responses:
         200:
           description: |-