diff --git a/changelogs/room_versions/newsfragments/2070.clarification b/changelogs/room_versions/newsfragments/2070.clarification new file mode 100644 index 00000000..7d0208cd --- /dev/null +++ b/changelogs/room_versions/newsfragments/2070.clarification @@ -0,0 +1 @@ +Refactor PDU definitions to reduce duplication. diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 1b950f11..773d7caa 100644 --- a/content/rooms/v1.md +++ b/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 diff --git a/content/rooms/v2.md b/content/rooms/v2.md index f9980261..f0ea1ac7 100644 --- a/content/rooms/v2.md +++ b/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 diff --git a/data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml b/data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml new file mode 100644 index 00000000..fabfef82 --- /dev/null +++ b/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 diff --git a/data/api/server-server/definitions/event_hash.yaml b/data/api/server-server/definitions/components/event_hash.yaml similarity index 100% rename from data/api/server-server/definitions/event_hash.yaml rename to data/api/server-server/definitions/components/event_hash.yaml diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/components/pdu_base.yaml similarity index 63% rename from data/api/server-server/definitions/unsigned_pdu_base.yaml rename to data/api/server-server/definitions/components/pdu_base.yaml index a2ec9552..4b676c8f 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/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 diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml deleted file mode 100644 index 00b83321..00000000 --- a/data/api/server-server/definitions/pdu.yaml +++ /dev/null @@ -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 diff --git a/data/api/server-server/definitions/pdu_v1.yaml b/data/api/server-server/definitions/pdu_v1.yaml new file mode 100644 index 00000000..b9ba8cc1 --- /dev/null +++ b/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 diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml index 60f9b3ac..a3db6ee9 100644 --- a/data/api/server-server/definitions/pdu_v11.yaml +++ b/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" \ No newline at end of file diff --git a/data/api/server-server/definitions/pdu_v3.yaml b/data/api/server-server/definitions/pdu_v3.yaml index e801518c..69d8900c 100644 --- a/data/api/server-server/definitions/pdu_v3.yaml +++ b/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 diff --git a/data/api/server-server/definitions/pdu_v4.yaml b/data/api/server-server/definitions/pdu_v4.yaml index d22956c6..e859ee86 100644 --- a/data/api/server-server/definitions/pdu_v4.yaml +++ b/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 diff --git a/data/api/server-server/definitions/unsigned_pdu.yaml b/data/api/server-server/definitions/unsigned_pdu.yaml deleted file mode 100644 index a27a21cd..00000000 --- a/data/api/server-server/definitions/unsigned_pdu.yaml +++ /dev/null @@ -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 diff --git a/data/api/server-server/examples/components/auth_events_prev_events_v4.json b/data/api/server-server/examples/components/auth_events_prev_events_v4.json new file mode 100644 index 00000000..3a203b49 --- /dev/null +++ b/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" + ] +} \ No newline at end of file diff --git a/data/api/server-server/examples/components/pdu_base.json b/data/api/server-server/examples/components/pdu_base.json new file mode 100644 index 00000000..448aeafa --- /dev/null +++ b/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 + } +} diff --git a/data/api/server-server/examples/pdu.json b/data/api/server-server/examples/pdu.json deleted file mode 100644 index 81981b23..00000000 --- a/data/api/server-server/examples/pdu.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "$ref": "unsigned_pdu.json", - "hashes": { - "sha256": "thishashcoversallfieldsincasethisisredacted" - }, - "signatures": { - "example.com": { - "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" - } - } -} \ No newline at end of file diff --git a/data/api/server-server/examples/unsigned_pdu_base.json b/data/api/server-server/examples/pdu_v1.json similarity index 52% rename from data/api/server-server/examples/unsigned_pdu_base.json rename to data/api/server-server/examples/pdu_v1.json index 079ee1ea..4e80ca52 100644 --- a/data/api/server-server/examples/unsigned_pdu_base.json +++ b/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 - } -} + ] +} \ No newline at end of file diff --git a/data/api/server-server/examples/pdu_v11.json b/data/api/server-server/examples/pdu_v11.json index 292f38a0..bbdcf433 100644 --- a/data/api/server-server/examples/pdu_v11.json +++ b/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" } ] } diff --git a/data/api/server-server/examples/pdu_v3.json b/data/api/server-server/examples/pdu_v3.json index acffdf26..6d2f5244 100644 --- a/data/api/server-server/examples/pdu_v3.json +++ b/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" diff --git a/data/api/server-server/examples/pdu_v4.json b/data/api/server-server/examples/pdu_v4.json index 3c2f0e22..ae25d537 100644 --- a/data/api/server-server/examples/pdu_v4.json +++ b/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" } + ] } diff --git a/data/api/server-server/examples/pdu_v4_join_membership.json b/data/api/server-server/examples/pdu_v4_join_membership.json index 1057ea94..23f69e81 100644 --- a/data/api/server-server/examples/pdu_v4_join_membership.json +++ b/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" diff --git a/data/api/server-server/examples/unsigned_pdu.json b/data/api/server-server/examples/unsigned_pdu.json deleted file mode 100644 index b886a365..00000000 --- a/data/api/server-server/examples/unsigned_pdu.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "$ref": "unsigned_pdu_base.json", - "event_id": "$a4ecee13e2accdadf56c1025:example.com" -}