From 9af28538e5d6e3a4e906dfc4f2899a6ca1019244 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 8 Aug 2023 14:30:38 -0400 Subject: [PATCH] Fix-up event format & examples. --- content/rooms/fragments/v11-event-format.md | 4 + content/rooms/v11.md | 14 ++-- data/api/server-server/definitions/pdu.yaml | 4 + .../server-server/definitions/pdu_v11.yaml | 81 +++++++++++++++++++ .../definitions/unsigned_pdu_base.yaml | 4 - data/api/server-server/examples/pdu_v11.json | 19 +++++ 6 files changed, 114 insertions(+), 12 deletions(-) create mode 100644 content/rooms/fragments/v11-event-format.md create mode 100644 data/api/server-server/definitions/pdu_v11.yaml create mode 100644 data/api/server-server/examples/pdu_v11.json diff --git a/content/rooms/fragments/v11-event-format.md b/content/rooms/fragments/v11-event-format.md new file mode 100644 index 00000000..a4da710d --- /dev/null +++ b/content/rooms/fragments/v11-event-format.md @@ -0,0 +1,4 @@ + +Events in rooms of this version have the following structure: + +{{% definition path="api/server-server/definitions/pdu_v11" %}} diff --git a/content/rooms/v11.md b/content/rooms/v11.md index bd70a10c..148c9cfe 100644 --- a/content/rooms/v11.md +++ b/content/rooms/v11.md @@ -37,13 +37,15 @@ Room version 11 is based upon room version 10 with the following considerations. ### Event format -The event format is unchanged by this room version. See [below](#event-format-1) -for details on the current event format. +The core event format is the same as [room version 10](/rooms/v10#event-format). +However, this room version changes some properties of some event types. + +{{% rver-fragment name="v11-event-format" %}} #### Remove the `creator` property of `m.room.create` events -The `m.room.create` event no longer has a `creator` property, which previously -was always equivalent to the `sender` of the event. +The `content` of a `m.room.create` event no longer has a `creator` property, +which previously was always equivalent to the `sender` of the event. #### Moving the `redacts` property of `m.room.redaction` events to a `content` property @@ -254,10 +256,6 @@ completeness. {{% rver-fragment name="v4-event-ids" %}} -### Event format - -{{% rver-fragment name="v4-event-format" %}} - ### State resolution {{% rver-fragment name="v2-state-res" %}} diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml index d87db1a3..5903f80e 100644 --- a/data/api/server-server/definitions/pdu.yaml +++ b/data/api/server-server/definitions/pdu.yaml @@ -20,6 +20,10 @@ 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: type: object title: Event Hash diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml new file mode 100644 index 00000000..df8cc6f3 --- /dev/null +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -0,0 +1,81 @@ +# Copyright 2019 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 +title: Persistent Data Unit +description: A persistent data unit (event) for room version 4 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: + 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'] + 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/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index c21149f6..ce42236f 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -107,10 +107,6 @@ properties: description: The event hash. example: Base64EncodedSha256HashesShouldBe43BytesLong required: ['sha256'] - redacts: - type: string - description: For redaction events, the ID of the event being redacted. - example: "$def456:matrix.org" unsigned: type: object title: UnsignedData diff --git a/data/api/server-server/examples/pdu_v11.json b/data/api/server-server/examples/pdu_v11.json new file mode 100644 index 00000000..292f38a0 --- /dev/null +++ b/data/api/server-server/examples/pdu_v11.json @@ -0,0 +1,19 @@ +{ + "$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" + ] +}