Add room version 11 (#1604)

* Remove duplicate words.

* Add information on room version 11.

* Note some event changes.

* Newsfragment

* Fix-up event schema.

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Fix 'new in this version'.

* Clarify creator field.

* Fix-up event format & examples.

* Move the Redactions section to the client section.

* Reference the sender instead of the creator.

* More links

* Even more links.

* Fix order of headers.

* Fix typos.

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clarify description of creator.

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clean-up intro paragraphs for redactions.

* Clean-up examples and language.

* Review comments.

* FIx-up markup tags.

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

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

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

@@ -0,0 +1,81 @@
+# Copyright 2019-2023 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 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:
+        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

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

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"
+    ]
+}

data/event-schemas/examples/m.room.create.yaml

@@ -3,8 +3,7 @@
   "type": "m.room.create",
   "state_key": "",
   "content": {
-    "creator": "@example:example.org",
-    "room_version": "1",
+    "room_version": "11",
     "m.federate": true,
     "predecessor": {
       "event_id": "$something:example.org",

data/event-schemas/examples/m.room.redaction.yaml

@@ -1,8 +1,8 @@
 {
   "$ref": "core/room_event.json",
   "type": "m.room.redaction",
-  "redacts": "$fukweghifu23:localhost",
   "content": {
+    "redacts": "$fukweghifu23:localhost",
     "reason": "Spamming"
   }
 }

data/event-schemas/schema/m.room.create.yaml

@@ -6,7 +6,9 @@ properties:
   content:
     properties:
       creator:
-        description: The `user_id` of the room creator. This is set by the homeserver.
+        description: |-
+          The `user_id` of the room creator. **Required** for, and only present in, room versions 1 - 10. Starting with
+          room version 11 the event `sender` should be used instead.
         type: string
       m.federate:
         description: Whether users on other servers can join this room. Defaults to `true` if key does not exist.
@@ -32,8 +34,6 @@ properties:
             type: string
             description: The event ID of the last known event in the old room.
         required: [room_id, event_id]
-    required:
-      - creator
     type: object
   state_key:
     description: A zero-length string.

data/event-schemas/schema/m.room.redaction.yaml

@@ -5,18 +5,19 @@ description: 'This event is created by the server to describe which event has be
 properties:
   content:
     properties:
+      redacts:
+        description: The event ID that was redacted. Required for, and present starting in, room version 11.
+        type: string
       reason:
         description: 'The reason for the redaction, if any.'
         type: string
     type: object
   redacts:
-    description: The event ID that was redacted.
+    description: Required for, and only present in, room versions 1 - 10. The event ID that was redacted.
     type: string
   type:
     enum:
       - m.room.redaction
     type: string
-required:
-  - redacts
 title: Redaction
 type: object