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

changelogs/server_server/newsfragments/1383.clarification

@@ -0,0 +1 @@
+Fix `edu_type` in EDU examples.

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
 

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']
+required: ['edu_type', 'content']

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"

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

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"
+                      $ref: "definitions/edu_with_example.yaml"
-          example: {
-            "$ref": "examples/transaction.json",
-            "edus": [{"$ref": "examples/edu.json"}]
-          }
       responses:
         200:
           description: |-