Fix the rendering of the event format for room versions 1 and 2 (#1883)

* Fix rendering of array with items using anyOf

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Use a single definition for Event Hash

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add ending newline

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/room_versions/newsfragments/1883.clarification

@@ -0,0 +1 @@
+Fix the rendering of the event format for room versions 1 and 2.

data/api/server-server/definitions/event_hash.yaml

@@ -0,0 +1,13 @@
+type: object
+title: Event Hash
+description: |-
+  Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
+example: {
+  "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
+}
+properties:
+  sha256:
+    type: string
+    description: The hash.
+    example: ThisHashCoversAllFieldsInCaseThisIsRedacted
+required: ['sha256']

data/api/server-server/definitions/pdu.yaml

@@ -25,19 +25,7 @@ allOf:
         description: For redaction events, the ID of the event being redacted.
         example: "$def456:matrix.org"
       hashes:
-        type: object
+        $ref: "event_hash.yaml"
-        title: Event Hash
-        description: |-
-          Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
-        }
-        properties:
-          sha256:
-            type: string
-            description: The hash.
-            example: ThisHashCoversAllFieldsInCaseThisIsRedacted
-        required: ['sha256']
       signatures:
         type: object
         description: |-

data/api/server-server/definitions/pdu_v11.yaml

@@ -47,19 +47,7 @@ allOf:
           Must contain less than or equal to 20 events.
         example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
       hashes:
-        type: object
+        $ref: "event_hash.yaml"
-        title: Event Hash
-        description: |-
-          Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
-        }
-        properties:
-          sha256:
-            type: string
-            description: The hash.
-            example: ThisHashCoversAllFieldsInCaseThisIsRedacted
-        required: ['sha256']
       signatures:
         type: object
         description: |-

data/api/server-server/definitions/pdu_v3.yaml

@@ -49,19 +49,7 @@ allOf:
           Must contain less than or equal to 20 events.
         example: ["$base64EncodedHash", "$AnotherEvent"]
       hashes:
-        type: object
+        $ref: "event_hash.yaml"
-        title: Event Hash
-        description: |-
-          Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
-        }
-        properties:
-          sha256:
-            type: string
-            description: The hash.
-            example: ThisHashCoversAllFieldsInCaseThisIsRedacted
-        required: ['sha256']
       signatures:
         type: object
         description: |-

data/api/server-server/definitions/unsigned_pdu_base.yaml

@@ -60,17 +60,7 @@ properties:
           - type: string
             title: Event ID
             example: "$abc123:matrix.org"
-          - type: object
+          - $ref: "event_hash.yaml"
-            title: Event Hash
-            example: {
-              "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
-            }
-            properties:
-              sha256:
-                type: string
-                description: The event hash.
-                example: Base64EncodedSha256HashesShouldBe43BytesLong
-            required: ['sha256']
   depth:
     type: integer
     description: |-
@@ -96,17 +86,7 @@ properties:
           - type: string
             title: Event ID
             example: "$abc123:matrix.org"
-          - type: object
+          - $ref: "event_hash.yaml"
-            title: Event Hash
-            example: {
-              "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong"
-            }
-            properties:
-              sha256:
-                type: string
-                description: The event hash.
-                example: Base64EncodedSha256HashesShouldBe43BytesLong
-            required: ['sha256']
   unsigned:
     type: object
     title: UnsignedData

layouts/partials/json-schema/resolve-additional-types.html

@@ -155,6 +155,7 @@
     {{ if eq $this_object.type "array" }}
         /* Add any nested objects referenced in this object's `items` */
         {{ if $this_object.items.anyOf }}
+            {{ $updated_schemas := slice }}
             {{ range $idx, $item := $this_object.items.anyOf }}
                 {{ $res := partial "get-additional-objects" (dict
                     "this_object" $item
@@ -163,7 +164,10 @@
                     "name" (printf "%s.items[%d]" $name $idx)
                 ) }}
                 {{ $all_objects = $res.objects }}
+                {{ $updated_schemas = $updated_schemas | append $res.schema }}
             {{ end }}
+            /* Update the top-level schema with the updated subschemas for the items */
+            {{ $this_object = merge $this_object (dict "items" (dict "anyOf" $updated_schemas)) }}
         {{ else if reflect.IsMap $this_object.items}}
             {{ $res := partial "get-additional-objects" (dict
                  "this_object" $this_object.items

layouts/partials/openapi/render-object-table.html

@@ -117,6 +117,9 @@ resolve-additional-types.)
 
     * `oneOf`: optional array of dictionaries describing the different formats
       that the property can have
+    
+    * `anyOf`: optional array of dictionaries describing the different formats
+      that the property can have
 
     * `properties`: if the type is an object, optional dictionary for
       well-defined properties, each given as: `property_name` : `property_data`
@@ -158,13 +161,14 @@ resolve-additional-types.)
                 {{ $type = . }}
             {{ end }}
         {{ end }}
-    {{ else if or (reflect.IsSlice .type) .oneOf }}
+    {{ else if or (reflect.IsSlice .type) .oneOf .anyOf }}
         {{/*
             It's legal to specify an array of types.
 
-            There are two ways to do that:
+            There are three ways to do that:
               - Use an array of strings.
               - Use oneOf, with items having a schema.
+              - Use anyOf, with items having a schema.
 
             Join them together in that case, like `type|other_type`.
         */}}
@@ -174,6 +178,10 @@ resolve-additional-types.)
             {{ range .oneOf }}
                 {{ $types = $types | append (partial "property-type" .) }}
             {{ end }}
+        {{ else if .anyOf }}
+            {{ range .anyOf }}
+                {{ $types = $types | append (partial "property-type" .) }}
+            {{ end }}
         {{ else }}
             {{ range .type }}
                 {{ $types = $types | append (htmlEscape .) }}