Improve upon the transaction schema and examples

Reduces data duplication and makes the objects more reusable for other areas of the spec

api/server-server/definitions/full_transaction.yaml

@@ -1,28 +0,0 @@
-# Copyright 2018 New Vector Ltd
-#
-# 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
-title: Transaction
-description: Transaction
-example:
-  $ref: "../examples/full_transaction.json"
-allOf:
-  - $ref: "transaction.yaml"
-  - type: object
-    properties:
-      edus:
-        type: array
-        description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
-        items:
-          $ref: "edu.yaml"
-required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/pdu.yaml

@@ -16,88 +16,10 @@ title: Persistent Data Unit
 description: A persistent data unit (event)
 example:
   $ref: "../examples/pdu.json"
-properties:
-  room_id:
-    type: string
-    description: Room identifier
-    example: "!abc123:matrix.org"
-  sender:
-    type: string
-    description: The ID of the user sending the event
-    example: "@someone:matrix.org"
-  origin:
-    type: string
-    description: The ``server_name`` of the homeserver that created this event
-    example: "matrix.org"    
-  origin_server_ts:
-    type: integer
-    format: int64
-    description: Timestamp in milliseconds on origin homeserver when this event was created.
-    example: 1234567890
-  type:
-    type: string
-    description: Event type
-    required: true
-    example: "m.room.message"
-  state_key:
-    type: string
-    description: |-
-      If this key is present, the event is a state event, and it will replace previous events
-      with the same ``type`` and ``state_key`` in the room state.
-    example: "my_key"
-  content:
-    type: object
-    description: The content of the event
-  prev_events:
-    type: array
-    description: |-
-      Event IDs and hashes of the most recent events in the room that the homeserver was aware
-      of when it made this event
-    items:
-      type: array
-      maxItems: 2
-      minItems: 2
-      items:
-        - type: string
-          title: Event ID
-          example: "$abc123:matrix.org"
+allOf:
+  - $ref: "unsigned_pdu.yaml"
   - type: object
-          title: Event Hash
-          example: {
-            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-          }
     properties:
-            sha256:
-              type: string
-              description: The event hash
-              example: abase64encodedsha256hashshouldbe43byteslong
-          required: ['sha256']
-  depth:
-    type: integer
-    description: The maximum depth of the ``prev_events``, plus one
-    example: 12
-  auth_events:
-    type: array
-    description: Event IDs and hashes for the "auth events" of this event
-    items:
-      type: array
-      maxItems: 2
-      minItems: 2
-      items:
-        - type: string
-          title: Event ID
-          example: "$abc123:matrix.org"
-        - type: object
-          title: Event Hash
-          example: {
-            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
-          }
-          properties:
-            sha256:
-              type: string
-              description: The event hash
-              example: abase64encodedsha256hashshouldbe43byteslong
-          required: ['sha256']
       hashes:
         type: object
         title: Event Hash
@@ -125,22 +47,6 @@ properties:
           title: Server Signatures
           additionalProperties:
             type: string
-  redacts:
-    type: string
-    description: For redaction events, the ID of the event being redacted
-    example: "$def456:matrix.org"
-  unsigned:
-    type: object
-    description: Additional data added by the origin server but not covered by the ``signatures``
-required:
-  - room_id
-  - sender
-  - origin
-  - origin_server_ts
-  - type
-  - content
-  - prev_events
-  - depth
-  - auth_events
+    required:
       - hashes
       - signatures

api/server-server/definitions/unsigned_pdu.yaml

@@ -0,0 +1,119 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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
+title: Unsigned Persistent Data Unit
+description: An unsigned persistent data unit (event)
+example:
+  $ref: "../examples/unsigned_pdu.json"
+properties:
+  room_id:
+    type: string
+    description: Room identifier
+    example: "!abc123:matrix.org"
+  sender:
+    type: string
+    description: The ID of the user sending the event
+    example: "@someone:matrix.org"
+  origin:
+    type: string
+    description: The ``server_name`` of the homeserver that created this event
+    example: "matrix.org"    
+  origin_server_ts:
+    type: integer
+    format: int64
+    description: Timestamp in milliseconds on origin homeserver when this event was created.
+    example: 1234567890
+  type:
+    type: string
+    description: Event type
+    required: true
+    example: "m.room.message"
+  state_key:
+    type: string
+    description: |-
+      If this key is present, the event is a state event, and it will replace previous events
+      with the same ``type`` and ``state_key`` in the room state.
+    example: "my_key"
+  content:
+    type: object
+    description: The content of the event
+    example: {"key": "value"}
+  prev_events:
+    type: array
+    description: |-
+      Event IDs and hashes of the most recent events in the room that the homeserver was aware
+      of when it made this event
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  depth:
+    type: integer
+    description: The maximum depth of the ``prev_events``, plus one
+    example: 12
+  auth_events:
+    type: array
+    description: Event IDs and hashes for the "auth events" of this event
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  redacts:
+    type: string
+    description: For redaction events, the ID of the event being redacted
+    example: "$def456:matrix.org"
+  unsigned:
+    type: object
+    description: Additional data added by the origin server but not covered by the ``signatures``
+    example: {"key": "value"}
+required:
+  - room_id
+  - sender
+  - origin
+  - origin_server_ts
+  - type
+  - content
+  - prev_events
+  - depth
+  - auth_events

api/server-server/examples/full_transaction.json

@@ -1,6 +0,0 @@
-{
-    "origin": "matrix.org",
-    "origin_server_ts": 1234567890,
-    "pdus": [{"$ref": "pdu.json"}],
-    "edus": [{"$ref": "edu.json"}]
-}

api/server-server/examples/pdu.json

@@ -1,16 +1,5 @@
 {
-    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
-    "sender": "@alice:example.com",
-    "origin": "example.com",
-    "event_id": "$a4ecee13e2accdadf56c1025:example.com",
-    "origin_server_ts": 1404838188000,
-    "type": "m.room.message",
-    "prev_events": [
-        [
-            "$af232176:example.org",
-            {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
-        ]
-    ],
+    "$ref": "unsigned_pdu.json",
     "hashes": {
         "sha256": "thishashcoversallfieldsincasethisisredacted"
     },
@@ -18,8 +7,5 @@
         "example.com": {
             "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
         }
-    },
-    "content": {
-        "key": "value"
     }
 }

api/server-server/examples/unsigned_pdu.json

@@ -0,0 +1,17 @@
+{
+    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
+    "sender": "@alice:example.com",
+    "origin": "example.com",
+    "event_id": "$a4ecee13e2accdadf56c1025:example.com",
+    "origin_server_ts": 1404838188000,
+    "type": "m.room.message",
+    "prev_events": [
+        [
+            "$af232176:example.org",
+            {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
+        ]
+    ],
+    "content": {
+        "key": "value"
+    }
+}

api/server-server/transactions.yaml

@@ -43,8 +43,21 @@ paths:
         - in: body
           name: body
           type: object
+          required: true
           schema:
-            $ref: "definitions/full_transaction.yaml"
+            allOf:
+              - $ref: "definitions/transaction.yaml"
+              - type: object
+                properties:
+                  edus:
+                    type: array
+                    description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
+                    items:
+                      $ref: "definitions/edu.yaml"
+          example: {
+            "$ref": "examples/transaction.json",
+            "edus": [{"$ref": "edu.json"}] # Relative to the examples directory
+          }
       responses:
         200:
           # TODO: Spec this (and figure out what it is)

scripts/templating/matrix_templates/units.py

@@ -138,6 +138,10 @@ def inherit_parents(obj):
     Recurse through the 'allOf' declarations in the object
     """
     logger.debug("inherit_parents %r" % obj)
+
+    if isinstance(obj, list):
+        return [inherit_parents(obj[i]) for i in range(0, len(obj))]
+
     parents = obj.get("allOf", [])
     if not parents:
         return obj
@@ -379,6 +383,10 @@ def get_tables_for_response(schema):
 def get_example_for_schema(schema):
     """Returns a python object representing a suitable example for this object"""
     schema = inherit_parents(schema)
+
+    if isinstance(schema, list):
+        return [get_example_for_schema(v) for v in schema]
+
     if 'example' in schema:
         example = schema['example']
         return example
@@ -398,7 +406,10 @@ def get_example_for_schema(schema):
     if proptype == 'array':
         if 'items' not in schema:
             raise Exception('"array" property has neither items nor example')
-        return [get_example_for_schema(schema['items'])]
+        result = get_example_for_schema(schema['items'])
+        if isinstance(result, list):
+            return result
+        return [result]
 
     if proptype == 'integer':
         return 0