Refactor PDU definitions to reduce duplication (#2070)

First of all, all PDU definitions were based on the v1 PDU definition with a few fields overwritten to change the format with needed.
While that works when rendering the spec, this is semantically incorrect because it means that the objects must match both schemas, which is impossible.

So now we make a base with only the common fields, and we add the others as needed by the room version.
Note that there is no more "unsigned PDU" definition since it is not used directly, and hashes and signatures are the same across all versions.

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

changelogs/room_versions/newsfragments/2070.clarification

@@ -0,0 +1 @@
+Refactor PDU definitions to reduce duplication.

content/rooms/v1.md

@@ -51,7 +51,7 @@ inconsistencies may occur.
 
 Events in version 1 rooms have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

content/rooms/v2.md

@@ -49,7 +49,7 @@ completeness.
 
 Events in rooms of this version have the following structure:
 
-{{% definition path="api/server-server/definitions/pdu" %}}
+{{% definition path="api/server-server/definitions/pdu_v1" %}}
 
 #### Deprecated event content schemas
 

data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml

@@ -0,0 +1,45 @@
+# Copyright 2025 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
+description: |-
+  The auth_events and prev_events fields of PDUs for room version 4
+  and beyond.
+properties:
+  auth_events:
+    type: array
+    items:
+      type: string
+      description: Event ID.
+    description: |-
+      Event IDs for the authorization events that would
+      allow this event to be in the room.
+
+      Must contain less than or equal to 10 events. Note that if the relevant
+      auth event selection rules are used, this restriction should never be
+      encountered.
+    example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+  prev_events:
+    type: array
+    items:
+      type: string
+      description: Event ID.
+    description: |-
+      Event IDs for the most recent events in the room
+      that the homeserver was aware of when it made this event.
+
+      Must contain less than or equal to 20 events.
+    example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
+required:
+  - auth_events
+  - prev_events

data/api/server-server/definitions/components/pdu_base.yaml

@@ -12,10 +12,7 @@
 # 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_base.json"
+description: Common fields for all PDU versions
 properties:
   room_id:
     type: string
@@ -44,23 +41,6 @@ properties:
     type: object
     description: The content of the event.
     example: {"key": "value"}
-  prev_events:
-    type: array
-    description: |-
-      Event IDs and reference hashes for the most recent events in the room
-      that the homeserver was aware of when it made this event.
-
-      Must contain less than or equal to 20 events.
-    items:
-      type: array
-      maxItems: 2
-      minItems: 2
-      items:
-        anyOf:
-          - type: string
-            title: Event ID
-            example: "$abc123:matrix.org"
-          - $ref: "event_hash.yaml"
   depth:
     type: integer
     description: |-
@@ -68,25 +48,22 @@ properties:
       maximum value for an integer (2^63 - 1). If the room's depth is already at
       the limit, the depth must be set to the limit.
     example: 12
-  auth_events:
-    type: array
+  hashes:
+    $ref: "event_hash.yaml"
+  signatures:
+    type: object
     description: |-
-      Event IDs and reference hashes for the authorization events that would
-      allow this event to be in the room.
-
-      Must contain less than or equal to 10 events. Note that if the relevant
-      auth event selection rules are used, this restriction should never be
-      encountered.
-    items:
-      type: array
-      maxItems: 2
-      minItems: 2
-      items:
-        anyOf:
-          - type: string
-            title: Event ID
-            example: "$abc123:matrix.org"
-          - $ref: "event_hash.yaml"
+      Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
+    example: {
+      "example.com": {
+        "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
+      }
+    }
+    additionalProperties:
+      type: object
+      title: Server Signatures
+      additionalProperties:
+        type: string
   unsigned:
     type: object
     title: UnsignedData
@@ -99,12 +76,11 @@ properties:
         description: The number of milliseconds that have passed since this message was sent.
         example: 4612
 required:
-  - event_id
   - room_id
   - sender
   - origin_server_ts
   - type
   - content
-  - prev_events
   - depth
-  - auth_events
+  - hashes
+  - signatures

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

@@ -1,45 +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: Persistent Data Unit
-description: A persistent data unit (event) for room versions 1 and 2.
-example:
-  $ref: "../examples/pdu.json"
-allOf:
-  - $ref: "unsigned_pdu.yaml"
-  - type: object
-    properties:
-      redacts:
-        type: string
-        description: For redaction events, the ID of the event being redacted.
-        example: "$def456:matrix.org"
-      hashes:
-        $ref: "event_hash.yaml"
-      signatures:
-        type: object
-        description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "example.com": {
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
-    required:
-      - hashes
-      - signatures

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

@@ -0,0 +1,70 @@
+# 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: Persistent Data Unit
+description: A persistent data unit (event) for room versions 1 and 2.
+example:
+  $ref: "../examples/pdu_v1.json"
+allOf:
+  - $ref: "components/pdu_base.yaml"
+  - type: object
+    properties:
+      event_id:
+        type: string
+        description: The event ID for the PDU.
+        example: "$a4ecee13e2accdadf56c1025:example.com"
+      redacts:
+        type: string
+        description: For redaction events, the ID of the event being redacted.
+        example: "$def456:matrix.org"
+      auth_events:
+        type: array
+        description: |-
+          Event IDs and reference hashes for the authorization events that would
+          allow this event to be in the room.
+
+          Must contain less than or equal to 10 events. Note that if the relevant
+          auth event selection rules are used, this restriction should never be
+          encountered.
+        items:
+          type: array
+          maxItems: 2
+          minItems: 2
+          items:
+            anyOf:
+              - type: string
+                title: Event ID
+                example: "$abc123:matrix.org"
+              - $ref: "components/event_hash.yaml"
+      prev_events:
+        type: array
+        description: |-
+          Event IDs and reference hashes for the most recent events in the room
+          that the homeserver was aware of when it made this event.
+
+          Must contain less than or equal to 20 events.
+        items:
+          type: array
+          maxItems: 2
+          minItems: 2
+          items:
+            anyOf:
+              - type: string
+                title: Event ID
+                example: "$abc123:matrix.org"
+              - $ref: "components/event_hash.yaml"
+    required:
+      - event_id
+      - auth_events
+      - prev_events

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

@@ -17,53 +17,6 @@ description: A persistent data unit (event) for room version 11 and beyond.
 example:
   $ref: "../examples/pdu_v11.json"
 allOf:
-  # v11 is the v4 event, but without redacts. Copy the auth_events/prev_events
-  # from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml.
-  - $ref: "unsigned_pdu_base.yaml"
-  - type: object
-    properties:
-      auth_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the authorization events that would
-          allow this event to be in the room.
-
-          Must contain less than or equal to 10 events. Note that if the relevant
-          auth event selection rules are used, this restriction should never be
-          encountered.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      prev_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the most recent events in the room
-          that the homeserver was aware of when it made this event.
-
-          Must contain less than or equal to 20 events.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      hashes:
-        $ref: "event_hash.yaml"
-      signatures:
-        type: object
-        description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "example.com": {
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
-    required:
-      - auth_events
-      - prev_events
-      - hashes
-      - signatures
+  # v11 is the v4 event, but without redacts.
+  - $ref: "components/pdu_base.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"

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

@@ -13,11 +13,11 @@
 # limitations under the License.
 type: object
 title: Persistent Data Unit
-description: A persistent data unit (event) for room version 3 and beyond.
+description: A persistent data unit (event) for room version 3.
 example:
   $ref: "../examples/pdu_v3.json"
 allOf:
-  - $ref: "unsigned_pdu_base.yaml"
+  - $ref: "components/pdu_base.yaml"
   - type: object
     properties:
       redacts:
@@ -48,24 +48,6 @@ allOf:
 
           Must contain less than or equal to 20 events.
         example: ["$base64EncodedHash", "$AnotherEvent"]
-      hashes:
-        $ref: "event_hash.yaml"
-      signatures:
-        type: object
-        description: |-
-          Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
-        example: {
-          "example.com": {
-            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
-          }
-        }
-        additionalProperties:
-          type: object
-          title: Server Signatures
-          additionalProperties:
-            type: string
     required:
       - auth_events
       - prev_events
-      - hashes
-      - signatures

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

@@ -13,41 +13,16 @@
 # limitations under the License.
 type: object
 title: Persistent Data Unit
-description: A persistent data unit (event) for room version 4 and beyond.
+description: |-
+  A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
 example:
   $ref: "../examples/pdu_v4.json"
 allOf:
-  - $ref: "pdu_v3.yaml"
+  - $ref: "components/pdu_base.yaml"
+  - $ref: "components/auth_events_prev_events_v4.yaml"
   - type: object
     properties:
       redacts:
         type: string
         description: For redaction events, the ID of the event being redacted.
         example: "$def_456-oldevent"
-      auth_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the authorization events that would
-          allow this event to be in the room.
-
-          Must contain less than or equal to 10 events. Note that if the relevant
-          auth event selection rules are used, this restriction should never be
-          encountered.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-      prev_events:
-        type: array
-        items:
-          type: string
-          description: Event ID.
-        description: |-
-          Event IDs for the most recent events in the room
-          that the homeserver was aware of when it made this event.
-
-          Must contain less than or equal to 20 events.
-        example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
-    required:
-      - auth_events
-      - prev_events

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

@@ -1,28 +0,0 @@
-# Copyright 2018-2019 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"
-allOf:
-  - $ref: "unsigned_pdu_base.yaml"
-  - type: object
-    properties:
-      event_id:
-        type: string
-        description: The event ID for the PDU.
-        example: "$a4ecee13e2accdadf56c1025:example.com"
-    required:
-      - event_id

data/api/server-server/examples/components/auth_events_prev_events_v4.json

@@ -0,0 +1,10 @@
+{
+    "auth_events": [
+        "$urlsafe_base64_encoded_eventid",
+        "$a-different-event-id"
+    ],
+    "prev_events": [
+        "$urlsafe_base64_encoded_eventid",
+        "$a-different-event-id"
+    ]
+}

data/api/server-server/examples/components/pdu_base.json

@@ -0,0 +1,21 @@
+{
+    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
+    "sender": "@alice:example.com",
+    "origin_server_ts": 1404838188000,
+    "depth": 12,
+    "type": "m.room.message",
+    "content": {
+        "key": "value"
+    },
+    "hashes": {
+        "sha256": "thishashcoversallfieldsincasethisisredacted"
+    },
+    "signatures": {
+        "example.com": {
+            "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+        }
+    },
+    "unsigned": {
+        "age": 4612
+    }
+}

data/api/server-server/examples/pdu.json

@@ -1,11 +0,0 @@
-{
-    "$ref": "unsigned_pdu.json",
-    "hashes": {
-        "sha256": "thishashcoversallfieldsincasethisisredacted"
-    },
-    "signatures": {
-        "example.com": {
-            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
-        }
-    }
-}

data/api/server-server/examples/pdu_v1.json

@@ -1,25 +1,16 @@
 {
-    "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
-    "sender": "@alice:example.com",
-    "origin_server_ts": 1404838188000,
-    "depth": 12,
+    "$ref": "components/pdu_base.json",
+    "event_id": "$a4ecee13e2accdadf56c1025:example.com",
     "auth_events": [
         [
             "$af232176:example.org",
             {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
         ]
     ],
-    "type": "m.room.message",
     "prev_events": [
         [
             "$af232176:example.org",
             {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
         ]
-    ],
-    "content": {
-        "key": "value"
-    },
-    "unsigned": {
-        "age": 4612
-    }
-}
+    ]
+}

data/api/server-server/examples/pdu_v11.json

@@ -1,19 +1,6 @@
 {
-    "$ref": "unsigned_pdu_base.json",
-    "hashes": {
-        "sha256": "thishashcoversallfieldsincasethisisredacted"
-    },
-    "signatures": {
-        "example.com": {
-            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
-        }
-    },
-    "auth_events": [
-        "$urlsafe_base64_encoded_eventid",
-        "$a-different-event-id"
-    ],
-    "prev_events": [
-        "$urlsafe_base64_encoded_eventid",
-        "$a-different-event-id"
+    "allOf": [
+        { "$ref": "components/pdu_base.json" },
+        { "$ref": "components/auth_events_prev_events_v4.json" }
     ]
 }

data/api/server-server/examples/pdu_v3.json

@@ -1,13 +1,5 @@
 {
-    "$ref": "unsigned_pdu_base.json",
-    "hashes": {
-        "sha256": "thishashcoversallfieldsincasethisisredacted"
-    },
-    "signatures": {
-        "example.com": {
-            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
-        }
-    },
+    "$ref": "components/pdu_base.json",
     "auth_events": [
         "$base64encodedeventid",
         "$adifferenteventid"

data/api/server-server/examples/pdu_v4.json

@@ -1,12 +1,7 @@
 {
-    "$ref": "pdu_v3.json",
-    "auth_events": [
-        "$urlsafe_base64_encoded_eventid",
-        "$a-different-event-id"
-    ],
-    "prev_events": [
-        "$urlsafe_base64_encoded_eventid",
-        "$a-different-event-id"
-    ],
-    "redacts": "$some-old_event"
+    "allOf": [
+        { "$ref": "components/pdu_base.json" },
+        { "$ref": "components/auth_events_prev_events_v4.json" },
+        { "redacts": "$some-old_event" }
+    ]
 }

data/api/server-server/examples/pdu_v4_join_membership.json

@@ -1,8 +1,5 @@
 {
-    "$ref": "unsigned_pdu_base.json",
-    "hashes": {
-        "sha256": "thishashcoversallfieldsincasethisisredacted"
-    },
+    "$ref": "components/pdu_base.json",
     "signatures": {
         "example.com": {
             "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"

data/api/server-server/examples/unsigned_pdu.json

@@ -1,4 +0,0 @@
-{
-    "$ref": "unsigned_pdu_base.json",
-    "event_id": "$a4ecee13e2accdadf56c1025:example.com"
-}