diff --git a/changelogs/room_versions/newsfragments/2114.clarification b/changelogs/room_versions/newsfragments/2114.clarification new file mode 100644 index 00000000..46104473 --- /dev/null +++ b/changelogs/room_versions/newsfragments/2114.clarification @@ -0,0 +1 @@ +Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. \ No newline at end of file diff --git a/content/rooms/fragments/v6-event-format.md b/content/rooms/fragments/v6-event-format.md new file mode 100644 index 00000000..f230ac54 --- /dev/null +++ b/content/rooms/fragments/v6-event-format.md @@ -0,0 +1,4 @@ + +Events in rooms of this version have the following structure: + +{{% definition path="api/server-server/definitions/pdu_v6" %}} diff --git a/content/rooms/v10.md b/content/rooms/v10.md index 974a0822..81daf4d6 100644 --- a/content/rooms/v10.md +++ b/content/rooms/v10.md @@ -281,7 +281,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} ### State resolution diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 72007d97..2f728587 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -39,6 +39,13 @@ in [room version 5](/rooms/v5). [See above](#redactions). +### Event format + +{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json), +the `depth` limit has been reduced in this room version. + +{{% rver-fragment name="v6-event-format" %}} + ### Authorization rules {{% added-in v=6 %}} Rule 4, which related specifically to events @@ -229,10 +236,6 @@ completeness. {{% rver-fragment name="v4-event-ids" %}} -### Event format - -{{% rver-fragment name="v4-event-format" %}} - #### Deprecated event content schemas {{% rver-fragment name="v1-deprecated-formatting-off-spec" %}} diff --git a/content/rooms/v7.md b/content/rooms/v7.md index ba711c55..34e2a8eb 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -225,7 +225,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/content/rooms/v8.md b/content/rooms/v8.md index c6c116a8..aabf88c5 100644 --- a/content/rooms/v8.md +++ b/content/rooms/v8.md @@ -109,7 +109,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/content/rooms/v9.md b/content/rooms/v9.md index 582ff6b4..ac3288a1 100644 --- a/content/rooms/v9.md +++ b/content/rooms/v9.md @@ -74,7 +74,7 @@ completeness. ### Event format -{{% rver-fragment name="v4-event-format" %}} +{{% rver-fragment name="v6-event-format" %}} #### Deprecated event content schemas diff --git a/data/api/server-server/definitions/components/pdu_base.yaml b/data/api/server-server/definitions/components/pdu_base.yaml index 4b676c8f..be275611 100644 --- a/data/api/server-server/definitions/components/pdu_base.yaml +++ b/data/api/server-server/definitions/components/pdu_base.yaml @@ -41,13 +41,6 @@ properties: type: object description: The content of the event. example: {"key": "value"} - depth: - type: integer - description: |- - The maximum depth of the `prev_events`, plus one. Must be less than the - 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 hashes: $ref: "event_hash.yaml" signatures: diff --git a/data/api/server-server/definitions/pdu_v1.yaml b/data/api/server-server/definitions/pdu_v1.yaml index b9ba8cc1..d2fb2ef9 100644 --- a/data/api/server-server/definitions/pdu_v1.yaml +++ b/data/api/server-server/definitions/pdu_v1.yaml @@ -28,6 +28,13 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def456:matrix.org" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + 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 description: |- diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml index a3db6ee9..409b99c6 100644 --- a/data/api/server-server/definitions/pdu_v11.yaml +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -17,6 +17,16 @@ 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. + # v11 is the v6 event, but without redacts. - $ref: "components/pdu_base.yaml" - - $ref: "components/auth_events_prev_events_v4.yaml" \ No newline at end of file + - $ref: "components/auth_events_prev_events_v4.yaml" + - type: object + properties: + # v6 enforces Canonical JSON and therefore needs a depth limit change + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^53 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12 \ 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 69d8900c..ccca717b 100644 --- a/data/api/server-server/definitions/pdu_v3.yaml +++ b/data/api/server-server/definitions/pdu_v3.yaml @@ -24,6 +24,13 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def/456+oldevent" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + 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 items: diff --git a/data/api/server-server/definitions/pdu_v4.yaml b/data/api/server-server/definitions/pdu_v4.yaml index e859ee86..2edf1b31 100644 --- a/data/api/server-server/definitions/pdu_v4.yaml +++ b/data/api/server-server/definitions/pdu_v4.yaml @@ -26,3 +26,10 @@ allOf: type: string description: For redaction events, the ID of the event being redacted. example: "$def_456-oldevent" + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + 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 diff --git a/data/api/server-server/definitions/pdu_v6.yaml b/data/api/server-server/definitions/pdu_v6.yaml new file mode 100644 index 00000000..1278a6e3 --- /dev/null +++ b/data/api/server-server/definitions/pdu_v6.yaml @@ -0,0 +1,36 @@ +# 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 +title: Persistent Data Unit +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: "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" + # v6 enforces Canonical JSON and therefore needs a depth limit change + depth: + type: integer + description: |- + The maximum depth of the `prev_events`, plus one. Must be less than the + maximum value for an integer (2^53 - 1). If the room's depth is already at + the limit, the depth must be set to the limit. + example: 12