From eedecf863a100986ff1833d100538b88bba330ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 25 Feb 2025 21:34:23 +0100 Subject: [PATCH 01/22] Clarify that join rules must be in auth events for knock events (#2063) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/server_server/newsfragments/2063.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/2063.clarification diff --git a/changelogs/server_server/newsfragments/2063.clarification b/changelogs/server_server/newsfragments/2063.clarification new file mode 100644 index 00000000..4e3df516 --- /dev/null +++ b/changelogs/server_server/newsfragments/2063.clarification @@ -0,0 +1 @@ +Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index 8e99c431..65494f80 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -537,7 +537,7 @@ the following subset of the room state: - If type is `m.room.member`: - The target's current `m.room.member` event, if any. - - If `membership` is `join` or `invite`, the current + - If `membership` is `join`, `invite` or `knock`, the current `m.room.join_rules` event, if any. - If membership is `invite` and `content` contains a `third_party_invite` property, the current From 10587366e9eb831f36aadc8911a661a46a7895d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 25 Feb 2025 22:00:32 +0100 Subject: [PATCH 02/22] =?UTF-8?q?For=20room=20versions=206=20and=207,=20cl?= =?UTF-8?q?arify=20that=20events=20with=20rejected=20auth=20eve=E2=80=A6?= =?UTF-8?q?=20(#2065)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Other room versions were updated in #1103 and #1137, but not these ones. Signed-off-by: Kévin Commaille --- .../newsfragments/2065.clarification | 1 + content/rooms/v6.md | 18 ++++++++++++------ content/rooms/v7.md | 18 ++++++++++++------ 3 files changed, 25 insertions(+), 12 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/2065.clarification diff --git a/changelogs/room_versions/newsfragments/2065.clarification b/changelogs/room_versions/newsfragments/2065.clarification new file mode 100644 index 00000000..e7fc9f20 --- /dev/null +++ b/changelogs/room_versions/newsfragments/2065.clarification @@ -0,0 +1 @@ +For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. diff --git a/content/rooms/v6.md b/content/rooms/v6.md index b2a5f024..72007d97 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -88,14 +88,20 @@ The rules are as follows: version, reject. 4. If `content` has no `creator` property, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. 4. If type is `m.room.member`: 1. If there is no `state_key` property, or no `membership` property in `content`, reject. diff --git a/content/rooms/v7.md b/content/rooms/v7.md index 216646d3..ba711c55 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -74,14 +74,20 @@ The rules are as follows: version, reject. 4. If `content` has no `creator` property, reject. 5. Otherwise, allow. -2. Reject if event has `auth_events` that: - 1. have duplicate entries for a given `type` and `state_key` pair - 2. have entries whose `type` and `state_key` don't match those +2. Considering the event's `auth_events`: + 1. If there are duplicate entries for a given `type` and `state_key` pair, + reject. + 2. If there are entries whose `type` and `state_key` don't match those specified by the [auth events selection](/server-server-api#auth-events-selection) - algorithm described in the server specification. -3. If event does not have a `m.room.create` in its `auth_events`, - reject. + algorithm described in the server specification, reject. + 3. If there are entries which were themselves rejected under the [checks + performed on receipt of a + PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject. + 4. If there is no `m.room.create` event among the entries, reject. +3. If the `content` of the `m.room.create` event in the room state has the + property `m.federate` set to `false`, and the `sender` domain of the event + does not match the `sender` domain of the create event, reject. 4. If type is `m.room.member`: 1. If there is no `state_key` property, or no `membership` property in `content`, reject. From ae06f3747087a2569bffc137b3c670e90b54df7d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 25 Feb 2025 17:11:50 -0500 Subject: [PATCH 03/22] fix typos in m.room_key.withheld (#2080) * fix typos * add changelog --- changelogs/client_server/newsfragments/2080.clarification | 1 + data/event-schemas/schema/m.room_key.withheld.yaml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2080.clarification diff --git a/changelogs/client_server/newsfragments/2080.clarification b/changelogs/client_server/newsfragments/2080.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/client_server/newsfragments/2080.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file diff --git a/data/event-schemas/schema/m.room_key.withheld.yaml b/data/event-schemas/schema/m.room_key.withheld.yaml index 797b51f9..1acca546 100644 --- a/data/event-schemas/schema/m.room_key.withheld.yaml +++ b/data/event-schemas/schema/m.room_key.withheld.yaml @@ -48,8 +48,8 @@ properties: session_id: type: string description: |- - Required of `code` is not `m.no_olm`. The session ID of the key - that this event is aboutis for. + Required if `code` is not `m.no_olm`. The session ID of the key + that this event is about. sender_key: type: string description: |- From 60339adb2d4df2d9ed480cf7cff270652d71a59c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 4 Mar 2025 18:08:42 +0100 Subject: [PATCH 04/22] Refactor PDU definitions to reduce duplication (#2070) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../newsfragments/2070.clarification | 1 + content/rooms/v1.md | 2 +- content/rooms/v2.md | 2 +- .../auth_events_prev_events_v4.yaml | 45 ++++++++++++ .../{ => components}/event_hash.yaml | 0 .../pdu_base.yaml} | 60 +++++----------- data/api/server-server/definitions/pdu.yaml | 45 ------------ .../api/server-server/definitions/pdu_v1.yaml | 70 +++++++++++++++++++ .../server-server/definitions/pdu_v11.yaml | 53 +------------- .../api/server-server/definitions/pdu_v3.yaml | 22 +----- .../api/server-server/definitions/pdu_v4.yaml | 33 ++------- .../definitions/unsigned_pdu.yaml | 28 -------- .../auth_events_prev_events_v4.json | 10 +++ .../examples/components/pdu_base.json | 21 ++++++ data/api/server-server/examples/pdu.json | 11 --- .../{unsigned_pdu_base.json => pdu_v1.json} | 17 ++--- data/api/server-server/examples/pdu_v11.json | 19 +---- data/api/server-server/examples/pdu_v3.json | 10 +-- data/api/server-server/examples/pdu_v4.json | 15 ++-- .../examples/pdu_v4_join_membership.json | 5 +- .../server-server/examples/unsigned_pdu.json | 4 -- 21 files changed, 190 insertions(+), 283 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/2070.clarification create mode 100644 data/api/server-server/definitions/components/auth_events_prev_events_v4.yaml rename data/api/server-server/definitions/{ => components}/event_hash.yaml (100%) rename data/api/server-server/definitions/{unsigned_pdu_base.yaml => components/pdu_base.yaml} (63%) delete mode 100644 data/api/server-server/definitions/pdu.yaml create mode 100644 data/api/server-server/definitions/pdu_v1.yaml delete mode 100644 data/api/server-server/definitions/unsigned_pdu.yaml create mode 100644 data/api/server-server/examples/components/auth_events_prev_events_v4.json create mode 100644 data/api/server-server/examples/components/pdu_base.json delete mode 100644 data/api/server-server/examples/pdu.json rename data/api/server-server/examples/{unsigned_pdu_base.json => pdu_v1.json} (52%) delete mode 100644 data/api/server-server/examples/unsigned_pdu.json 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" -} From dfc61ffc71ab0af1b58517ae40ce4b6f4521064e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 4 Mar 2025 18:14:42 +0100 Subject: [PATCH 05/22] Fix parsing of nested slices in resolve-refs and resolve-allof partials (#2069) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/2069.clarification | 1 + layouts/partials/json-schema/resolve-allof.html | 8 ++++++++ layouts/partials/json-schema/resolve-refs.html | 8 ++++++++ 3 files changed, 17 insertions(+) create mode 100644 changelogs/internal/newsfragments/2069.clarification diff --git a/changelogs/internal/newsfragments/2069.clarification b/changelogs/internal/newsfragments/2069.clarification new file mode 100644 index 00000000..2ad407fb --- /dev/null +++ b/changelogs/internal/newsfragments/2069.clarification @@ -0,0 +1 @@ +Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. diff --git a/layouts/partials/json-schema/resolve-allof.html b/layouts/partials/json-schema/resolve-allof.html index b8b81e7d..61a03c3f 100644 --- a/layouts/partials/json-schema/resolve-allof.html +++ b/layouts/partials/json-schema/resolve-allof.html @@ -24,6 +24,14 @@ {{ range $original }} {{ $resolved := partial "json-schema/resolve-allof" . }} + {{ if reflect.IsSlice $resolved }} + {{/* + If $resolved is a slice, `append` will add the items of $resolved to + $ret, but we want to add $resolved itself to $ret, so we always wrap + it into another slice. + */}} + {{ $resolved = slice $resolved }} + {{ end }} {{ $ret = $ret | append $resolved }} {{ end }} {{ else if reflect.IsMap $original }} diff --git a/layouts/partials/json-schema/resolve-refs.html b/layouts/partials/json-schema/resolve-refs.html index 9a36e413..7479498a 100644 --- a/layouts/partials/json-schema/resolve-refs.html +++ b/layouts/partials/json-schema/resolve-refs.html @@ -69,6 +69,14 @@ {{ range $schema }} {{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }} + {{ if reflect.IsSlice $resolved }} + {{/* + If $resolved is a slice, `append` will add the items of $resolved to + $result_slice, but we want to add $resolved itself to $result_slice, + so we wrap it into another slice. + */}} + {{ $resolved = slice $resolved }} + {{ end }} {{ $result_slice = $result_slice | append $resolved }} {{ end }} From 844dd6f8aefd301c18643488ef101d38c18c9be9 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 4 Mar 2025 18:18:27 +0100 Subject: [PATCH 06/22] Clients can choose which history visibility options they offer to users when creating rooms (#2072) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/2072.clarification | 1 + content/client-server-api/modules/history_visibility.md | 7 ++----- 2 files changed, 3 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2072.clarification diff --git a/changelogs/client_server/newsfragments/2072.clarification b/changelogs/client_server/newsfragments/2072.clarification new file mode 100644 index 00000000..ddb9a536 --- /dev/null +++ b/changelogs/client_server/newsfragments/2072.clarification @@ -0,0 +1 @@ +Clients can choose which history visibility options they offer to users when creating rooms. diff --git a/content/client-server-api/modules/history_visibility.md b/content/client-server-api/modules/history_visibility.md index b0d333ab..04487bdb 100644 --- a/content/client-server-api/modules/history_visibility.md +++ b/content/client-server-api/modules/history_visibility.md @@ -43,11 +43,8 @@ setting at that time was more restrictive. #### Client behaviour -Clients that implement this module MUST present to the user the possible -options for setting history visibility when creating a room. - -Clients may want to display a notice that their events may be read by -non-joined people if the value is set to `world_readable`. +Clients may want to display a notice that events may be read by +non-joined people if the history visibility is set to `world_readable`. #### Server behaviour From 4ff9a851e683b14b150b5941fb28b988e17242e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 5 Mar 2025 10:43:27 +0100 Subject: [PATCH 07/22] Add link to git commit for unstable changelog too (#2078) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/2078.clarification | 1 + layouts/docs/changelog.html | 12 ++++++++++-- scripts/generate-changelog.sh | 12 +++++++++++- 3 files changed, 22 insertions(+), 3 deletions(-) create mode 100644 changelogs/internal/newsfragments/2078.clarification diff --git a/changelogs/internal/newsfragments/2078.clarification b/changelogs/internal/newsfragments/2078.clarification new file mode 100644 index 00000000..d9285d5a --- /dev/null +++ b/changelogs/internal/newsfragments/2078.clarification @@ -0,0 +1 @@ +Add link to the git commit for the unstable changelog. diff --git a/layouts/docs/changelog.html b/layouts/docs/changelog.html index b23c8074..94fa55a3 100644 --- a/layouts/docs/changelog.html +++ b/layouts/docs/changelog.html @@ -31,9 +31,17 @@

{{ .Title }}

- {{ if ne $version "unstable" -}} - {{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version -}} + {{ $rev := $version }} + {{ if eq $version "unstable" -}} + {{- /* + Extract the git SHA from the frontmatter of the changelog, where + it was stashed by `generate-changelog.sh`. + */ -}} + {{ $rev = .Params.commit -}} + {{ end -}} + {{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $rev -}} + {{ if ne $version "unstable" }} {{ end -}} {{ $checklist := .OutputFormats.Get "checklist" -}} diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 678af60f..9c80b059 100755 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -44,8 +44,18 @@ outputs: - html - checklist date: $(date -Idate) ---- EOF + + # Add the commit hash for the unstable versions. It is used to generate a + # link to the commit on the repository. + if [ "$VERSION" == "vUNSTABLE" ]; then + echo "params:" + echo " commit: $(git rev-parse --short HEAD)" + fi + + # Close the frontmatter. + echo "---" + # Remove trailing whitespace (such as our intentionally blank RST headings) sed -e "s/[ ]*$//" rendered.md } > ../content/changelog/$FILENAME From 3adbfa30da98f2cee9d46fd96cf3b0eff3a31c6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 5 Mar 2025 10:44:59 +0100 Subject: [PATCH 08/22] Look for examples in all possible locations (#2076) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We used to only look for examples in a few (sometimes arbitrary) places, and we didn't support showing several examples in most cases. This is intended to fix this. In the process we try to deduplicate code to make sure that we use the same logic everywhere. Signed-off-by: Kévin Commaille --- .../internal/newsfragments/2076.clarification | 1 + .../newsfragments/2076.clarification | 1 + data/api/server-server/invites-v1.yaml | 16 --- data/api/server-server/invites-v2.yaml | 19 ---- data/api/server-server/joins-v2.yaml | 1 - data/api/server-server/knocks.yaml | 1 - layouts/partials/events/example.html | 8 +- .../partials/json-schema/resolve-example.html | 46 -------- .../json-schema/resolve-examples.html | 71 ++++++++++++ .../openapi/render-media-type-objects.html | 104 ++++++++++++++++++ layouts/partials/openapi/render-request.html | 59 +--------- .../partials/openapi/render-responses.html | 68 +----------- layouts/partials/render-example.html | 40 +++++++ layouts/shortcodes/definition.html | 11 +- 14 files changed, 226 insertions(+), 220 deletions(-) create mode 100644 changelogs/internal/newsfragments/2076.clarification create mode 100644 changelogs/server_server/newsfragments/2076.clarification delete mode 100644 layouts/partials/json-schema/resolve-example.html create mode 100644 layouts/partials/json-schema/resolve-examples.html create mode 100644 layouts/partials/openapi/render-media-type-objects.html create mode 100644 layouts/partials/render-example.html diff --git a/changelogs/internal/newsfragments/2076.clarification b/changelogs/internal/newsfragments/2076.clarification new file mode 100644 index 00000000..3cf1fb94 --- /dev/null +++ b/changelogs/internal/newsfragments/2076.clarification @@ -0,0 +1 @@ +Support more locations for examples in OpenAPI definitions and JSON schemas. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/2076.clarification b/changelogs/server_server/newsfragments/2076.clarification new file mode 100644 index 00000000..b3cad0d2 --- /dev/null +++ b/changelogs/server_server/newsfragments/2076.clarification @@ -0,0 +1 @@ +Remove an erroneous `room_id` field in a few examples. diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index c328f05e..7d241c37 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -75,22 +75,6 @@ paths: example: $ref: ../../event-schemas/examples/invite_room_state.json type: object - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - } - } required: true responses: "200": diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 8984b6d1..f42c8eea 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -78,25 +78,6 @@ paths: required: - room_version - event - example: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - } - } - } required: true responses: "200": diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index bb45b1be..91e6a83e 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -140,7 +140,6 @@ paths: - type - content example: { - "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index cba9d32b..01bfa637 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -270,7 +270,6 @@ paths: - type - content example: { - "room_id": "!somewhere:example.org", "type": "m.room.member", "state_key": "@someone:example.org", "origin": "example.org", diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html index 90752fbd..c24cd66b 100644 --- a/layouts/partials/events/example.html +++ b/layouts/partials/events/example.html @@ -13,10 +13,4 @@ {{ $path := delimit (slice "event-schemas/examples" .name) "/" }} {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }} -{{ $example_json := jsonify (dict "indent" " ") $example_content }} -{{ $example_json = replace $example_json "\\u003c" "<" }} -{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} - -```json -{{ $example_json }} -``` +{{ partial "render-example" (dict "example" $example_content) }} diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html deleted file mode 100644 index 8fa98400..00000000 --- a/layouts/partials/json-schema/resolve-example.html +++ /dev/null @@ -1,46 +0,0 @@ -{{/* - - For complex objects, example content is sometimes attached to the - object's individual properties (and subproperties...), so to get - a complete example for the whole object we need to iterate through - its properties (and subproperties...) and assemble them. - - That's what this template does. - -*/}} - -{{ $this_object := . }} - -{{ $example := $this_object.example }} - -{{ if not $example }} - - {{ if eq $this_object.type "object" }} - {{ $example = dict }} - - {{ range $key, $property := $this_object.properties}} - {{ $this_property_example := partial "json-schema/resolve-example" $property }} - {{ if $this_property_example }} - {{ $example = merge (dict $key $this_property_example) $example }} - {{ end }} - {{ end }} - - {{ else if eq $this_object.type "array" }} - - {{/* the "items" within an array can either be an object (where we have a - list of items which match the schema), or a list (for tuple - validation, where each item has a different schema). - - TODO: support tuple validation here. - */}} - {{ if reflect.IsMap $this_object.items }} - {{ $items_example := partial "json-schema/resolve-example" $this_object.items }} - {{ if $items_example }} - {{ $example = slice $items_example }} - {{ end }} - {{ end }} - {{ end }} - -{{ end }} - -{{ return $example }} diff --git a/layouts/partials/json-schema/resolve-examples.html b/layouts/partials/json-schema/resolve-examples.html new file mode 100644 index 00000000..dd126540 --- /dev/null +++ b/layouts/partials/json-schema/resolve-examples.html @@ -0,0 +1,71 @@ +{{/* + + Find examples in the given JSON schema. + + Tries to find examples in the `examples` and `example` keys of the schema + first. + + If it doesn't succeed, iterates through the properties and subproperties to + collect their examples, to merge them into a complete example for the whole + object. + + Parameter: the JSON schema to extract the examples from. + +*/}} + +{{ $this_object := . }} +{{ $examples := slice }} + +{{ if $this_object.examples }} + {{/* This is an array of examples, we can just use it */}} + {{ $examples = $this_object.examples }} +{{ else if $this_object.example }} + {{ $examples = slice $this_object.example }} +{{ else }} + {{/* Resolve the nested examples */}} + {{ if eq $this_object.type "object" }} + {{ $example := dict }} + + {{ range $key, $property := $this_object.properties}} + {{ $this_property_examples := partial "json-schema/resolve-examples" $property }} + {{/* + It would be too complex to handle several nested examples, + just use the first one. + */}} + {{ with index $this_property_examples 0 }} + {{ $example = merge (dict $key .) $example }} + {{ end }} + {{ end }} + + {{/* + Add the assembled example to the list if either (a) the example is + non-empty, or (b) the object itself is meant to be empty (so an + empty example is correct). + */}} + {{ if (or $example (not $this_object.properties)) }} + {{ $examples = slice $example }} + {{ end }} + + {{ else if eq $this_object.type "array" }} + + {{/* the "items" within an array can either be an object (where we have a + list of items which match the schema), or a list (for tuple + validation, where each item has a different schema). + + TODO: support tuple validation here. + */}} + {{ if reflect.IsMap $this_object.items }} + {{ $items_examples := partial "json-schema/resolve-examples" $this_object.items }} + {{/* + It would be too complex to handle several nested examples, + just use the first one. + */}} + {{ with index $items_examples 0 }} + {{ $examples = slice (slice .) }} + {{ end }} + {{ end }} + {{ end }} + +{{ end }} + +{{ return $examples }} diff --git a/layouts/partials/openapi/render-media-type-objects.html b/layouts/partials/openapi/render-media-type-objects.html new file mode 100644 index 00000000..7c48320e --- /dev/null +++ b/layouts/partials/openapi/render-media-type-objects.html @@ -0,0 +1,104 @@ +{{/* + + Render a map of [Media Type Objects](https://spec.openapis.org/oas/v3.1.1#media-type-object). + This map can be found as the `content` field of requests and responses. + + Parameters: + + * `content`: A map of MIME type to Media Type Object + * `kind`: the kind of object that is rendered, either `request` or `response`. + * `anchor_base`: a prefix to add to the HTML anchors generated for each object + + This template renders: + + * Object tables if the map contains an `application/json` MIME type, or a + table with the MIME types and the corresponding description of the object. + * The examples of the Media Type Objects. + +*/}} + +{{/* + Request and response bodies can have several content types. If there is a + JSON type, we display that; otherwise we just show the content types and + descriptions. +*/}} +{{ $json_body := index .content "application/json" }} +{{ if $json_body }} + {{/* + Display the JSON schemas + */}} + + {{ $schema := $json_body.schema }} + + {{/* + All this is to work out how to express the content of the response + in the case where it is an array. + */}} + {{ if eq $schema.type "array" }} + {{ $type_of := "" }} + {{ if $schema.items.anyOf }} + {{ $types := slice }} + {{ range $schema.items.anyOf }} + {{ if .title }} + {{ $types = $types | append .title}} + {{ else }} + {{ $types = $types | append .type }} + {{ end }} + {{ end }} + {{ $type_of = delimit $types ", "}} + {{ else }} + {{ $type_of = $schema.items.title }} + {{ end }} +

Array of {{ $type_of }}.

+ {{ end }} + + {{/* + Render object tables for any objects referenced in the request/response. + + This will be a no-op for request/response body types which aren't + objects or arrays. + */}} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" .anchor_base) }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" . }} + {{ end }} +{{ else }} + {{/* + Show the content types and description. + */}} + {{ partial "openapi/render-content-type" (dict "content_types" .content) }} +{{ end }} + +{{/* + Show all the examples. +*/}} +{{ if eq .kind "request" }} +

Request body example

+{{ end }} + +{{ range $mime, $body := .content }} + {{ $examples := slice }} + + {{/* + Find the examples to display, with the following priority: + + 1. The `examples` field + 2. The `example` field + 3. The examples in the `schema` field + */}} + {{ if $body.examples }} + {{/* This is a map of string to Example Object */}} + {{ range $key, $example := $body.examples }} + {{/* The example is in the `value` field of the object */}} + {{ $examples = $examples | append (slice $example.value) }} + {{ end }} + {{ else if $body.example }} + {{ $examples = slice $body.example }} + {{ else if $body.schema }} + {{ $examples = partial "json-schema/resolve-examples" $body.schema }} + {{ end }} + + {{ range $examples }} + {{ partial "render-example" (dict "example" . "mime" $mime) }} + {{ end }} +{{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 80b352c6..88749cbf 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -33,65 +33,8 @@ {{ if $request_body }}

Request body

- {{/* - A request can have several content types. - */}} - {{ $json_body := index $request_body.content "application/json" }} - {{ if $json_body }} - {{/* - Display the JSON schemas - */}} - {{ $schema := $json_body.schema }} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} - {{ end }} - {{ else }} - {{/* - Show the content types and description. - */}} - {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }} - {{ end }} - -

Request body example

- {{/* - Show all the examples. - */}} - {{ range $mime, $body := $request_body.content }} - {{ $example := dict }} - - {{ if $body.schema }} - {{ $example = partial "json-schema/resolve-example" $body.schema }} - {{ end }} - - {{ if and (eq ($example | len) 0) $body.example }} - {{/* - If no example was generated from the schema, fallback to the - main example. - */}} - {{ $example = $body.example }} - {{ end }} - - {{ if eq $mime "application/json" }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} -```json -{{ $example_json }} -``` - {{ else }} - {{ $example = $example | safeHTML }} - {{/* - We need to set a language for the code otherwise the styling - is different than other examples. - */}} -```json -{{ $example }} -``` - {{ end }} - - {{ end }} + {{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }} {{ end }} {{ else }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 084e9481..0e7f1324 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -59,72 +59,6 @@ {{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }} {{ end }} - {{/* - A response can have several content types. - */}} - {{ $json_body := index $response.content "application/json" }} - {{ if $json_body }} - {{/* - Display the JSON schemas - */}} - - {{ $schema := $json_body.schema }} - - {{/* - All this is to work out how to express the content of the response - in the case where it is an array. - */}} - {{ if eq $schema.type "array" }} - {{ $type_of := "" }} - {{ if $schema.items.anyOf }} - {{ $types := slice }} - {{ range $schema.items.anyOf }} - {{ if .title }} - {{ $types = $types | append .title}} - {{ else }} - {{ $types = $types | append .type }} - {{ end }} - {{ end }} - {{ $type_of = delimit $types ", "}} - {{ else }} - {{ $type_of = $schema.items.title }} - {{ end }} -

Array of {{ $type_of }}.

- {{ end }} - - - {{/* - render object tables for any objects referenced in the - response. (This will be a no-op for response types which aren't - objects or arrays.) - */}} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} - {{ end }} - - {{/* - render an example. currently this is only supported for arrays and objects. - */}} - {{ if or (eq $schema.type "object") (eq $schema.type "array") }} - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ if $json_body.examples }} - {{ $example = $json_body.examples.response.value }} - {{ end }} - - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} - -```json -{{ $example_json }} -``` - {{ end }} - {{ else }} - {{/* - Show the content types and description. - */}} - {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }} - {{ end }} + {{ partial "openapi/render-media-type-objects" (dict "content" $response.content "kind" "response" "anchor_base" $anchor) }} {{ end }} {{ end }} diff --git a/layouts/partials/render-example.html b/layouts/partials/render-example.html new file mode 100644 index 00000000..1f6c18fb --- /dev/null +++ b/layouts/partials/render-example.html @@ -0,0 +1,40 @@ +{{/* + + Renders an example to be included in HTML, with support for pretty-printing + JSON. + + Parameters: + + * `example`: the example + * `mime`: the mime type of the example. Used to pretty-print JSON and for + syntax highlighting. If it is not provided, it is assumed to be + `application/json`. + +*/}} + +{{ $example := .example }} + +{{/* + We need to convert the mime type to a recognized language. + For simplicity we only support JSON, which is also the default. Other mime + types are not highlighted. +*/}} +{{ $language := "json" }} + +{{ if (and .mime (ne .mime "application/json")) }} + {{/* + `no-highlight` treats the value as plain text, but still styles the code + block like the ones with proper syntax highlighting. + */}} + {{ $language = "no-highlight" }} +{{ end }} + +{{ if eq $language "json" }} + {{ $example = jsonify (dict "indent" " ") $example }} + {{ $example = replace $example "\\u003c" "<" }} + {{ $example = replace $example "\\u003e" ">" }} +{{ end }} + +```{{ $language }} +{{ $example | safeHTML }} +``` diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 10ad0e87..1a9643d9 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -58,13 +58,14 @@ {{ partial "openapi/render-object-table" . }} {{end}} +{{ $examples := partial "json-schema/resolve-examples" $definition }} +{{ if $examples }}

Examples

-{{ $example := partial "json-schema/resolve-example" $definition }} - -```json -{{ jsonify (dict "indent" " ") $example }} -``` + {{ range $examples }} + {{ partial "render-example" (dict "example" .) }} + {{ end }} +{{ end }} From 02a1aeefbcd4acde25569f80358c301a227a957e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 5 Mar 2025 10:52:40 +0100 Subject: [PATCH 09/22] Deduplicate `RoomKeysUpdateResponse` (#2073) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit And add a link to the endpoint that is mentionned while we're at it. Signed-off-by: Kévin Commaille --- .../internal/newsfragments/2073.clarification | 1 + data/api/client-server/key_backup.yaml | 122 ++++-------------- 2 files changed, 27 insertions(+), 96 deletions(-) create mode 100644 changelogs/internal/newsfragments/2073.clarification diff --git a/changelogs/internal/newsfragments/2073.clarification b/changelogs/internal/newsfragments/2073.clarification new file mode 100644 index 00000000..64dbc6c4 --- /dev/null +++ b/changelogs/internal/newsfragments/2073.clarification @@ -0,0 +1 @@ +Deduplicate the definition of `RoomKeysUpdateResponse`. diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 64833f6e..cd597f88 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -438,22 +438,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "403": description: |- The version specified does not match the current backup version. @@ -571,22 +556,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "404": description: The backup was not found. content: @@ -644,22 +614,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "403": description: |- The version specified does not match the current backup version. @@ -778,22 +733,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "404": description: The backup was not found. content: @@ -866,22 +806,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "403": description: |- The version specified does not match the current backup version. @@ -1007,22 +932,7 @@ paths: content: application/json: schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: abcdefg - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count + $ref: "#/components/schemas/RoomKeysUpdateResponse" "404": description: The backup was not found. content: @@ -1056,6 +966,26 @@ servers: basePath: default: /_matrix/client/v3 components: + schemas: + RoomKeysUpdateResponse: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + + See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion) + for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count securitySchemes: accessTokenQuery: $ref: definitions/security.yaml#/accessTokenQuery From 1916e53f8cd4c94f18c721662e0547ecd1ca2e4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 5 Mar 2025 10:56:49 +0100 Subject: [PATCH 10/22] Deduplicate `Invite3pid` (#2074) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Deduplicate Invite3pid Signed-off-by: Kévin Commaille --- .../internal/newsfragments/2074.clarification | 1 + data/api/client-server/create_room.yaml | 27 +---------- .../definitions/invite_3pid.yaml | 45 +++++++++++++++++++ .../client-server/third_party_membership.yaml | 32 +------------ 4 files changed, 48 insertions(+), 57 deletions(-) create mode 100644 changelogs/internal/newsfragments/2074.clarification create mode 100644 data/api/client-server/definitions/invite_3pid.yaml diff --git a/changelogs/internal/newsfragments/2074.clarification b/changelogs/internal/newsfragments/2074.clarification new file mode 100644 index 00000000..4f941dd2 --- /dev/null +++ b/changelogs/internal/newsfragments/2074.clarification @@ -0,0 +1 @@ +Deduplicate the definitions of `Invite3pid`. diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 9e36d5e8..3992fdfe 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -131,32 +131,7 @@ paths: A list of objects representing third-party IDs to invite into the room. items: - type: object - title: Invite3pid - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for - third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example `email` - (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: - - id_server - - id_access_token - - medium - - address + $ref: definitions/invite_3pid.yaml room_version: type: string description: |- diff --git a/data/api/client-server/definitions/invite_3pid.yaml b/data/api/client-server/definitions/invite_3pid.yaml new file mode 100644 index 00000000..f00f15c5 --- /dev/null +++ b/data/api/client-server/definitions/invite_3pid.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 +title: Invite3pid +properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for + third-party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + description: |- + The kind of address being passed in the address field, for example `email` + (see [the list of recognised values](/appendices/#3pid-types)). + address: + type: string + description: The invitee's third-party identifier. +required: + - id_server + - id_access_token + - medium + - address +example: { + "id_server": "matrix.org", + "id_access_token": "abc123_OpaqueString", + "medium": "email", + "address": "cheeky@monkey.com" +} \ No newline at end of file diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index ea366648..65148ee0 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -76,37 +76,7 @@ paths: content: application/json: schema: - type: object - example: { - "id_server": "matrix.org", - "id_access_token": "abc123_OpaqueString", - "medium": "email", - "address": "cheeky@monkey.com" - } - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for - third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example - `email` (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: - - id_server - - id_access_token - - medium - - address + $ref: definitions/invite_3pid.yaml required: true responses: "200": From e283c35dbda8661f748cb978e6ab5493d8a03fdd Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 5 Mar 2025 15:12:15 +0100 Subject: [PATCH 11/22] Remove extra trailing quotes from sync API specs (#2091) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/2091.clarification | 1 + data/api/client-server/old_sync.yaml | 2 +- data/api/client-server/room_initial_sync.yaml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2091.clarification diff --git a/changelogs/client_server/newsfragments/2091.clarification b/changelogs/client_server/newsfragments/2091.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/2091.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 0a3c0439..118087c0 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -214,7 +214,7 @@ paths: - public description: |- Whether this room is visible to the `/publicRooms` API - or not." + or not. account_data: type: array description: |- diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index 130efa1c..e9ad7a63 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/data/api/client-server/room_initial_sync.yaml @@ -96,7 +96,7 @@ paths: - public description: |- Whether this room is visible to the `/publicRooms` API - or not." + or not. account_data: type: array description: The private data that this user has attached to this room. From 7fd49a2808523b6a4436bea9a2f2dbd2c7b1b51b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Mar 2025 19:00:33 +0100 Subject: [PATCH 12/22] Set room version 11 as the default (#2105) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Set room version 11 as the default As per MSC4239 Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/room_versions/newsfragments/2105.feature | 1 + content/rooms/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/2105.feature diff --git a/changelogs/room_versions/newsfragments/2105.feature b/changelogs/room_versions/newsfragments/2105.feature new file mode 100644 index 00000000..9e13a36c --- /dev/null +++ b/changelogs/room_versions/newsfragments/2105.feature @@ -0,0 +1 @@ +Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). diff --git a/content/rooms/_index.md b/content/rooms/_index.md index 9334c3a1..d970bfe7 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including discovered security vulnerabilities and age. Clients should not ask room administrators to upgrade their rooms if the -room is running a stable version. Servers SHOULD use **room version 10** as +room is running a stable version. Servers SHOULD use **room version 11** as the default room version when creating new rooms. The available room versions are: From c7581356bf65607939877e37c17b28a220e0310b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 20:33:26 +0100 Subject: [PATCH 13/22] MSC4260: Reporting users (Client-Server API) (#2093) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * MSC4260: Reporting users (Client-Server API) Signed-off-by: Johannes Marbach * Add changelog * Update data/api/client-server/report_content.yaml Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> * Move option to consistently respond with 200 to user reporting endpoint * Move optional random delay to event and user reporting endpoints * Make reason required for user and room reports * Fix requiredness syntax --------- Signed-off-by: Johannes Marbach Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> --- .../client_server/newsfragments/2093.new | 1 + .../modules/report_content.md | 6 ++ data/api/client-server/report_content.yaml | 97 +++++++++++++++++-- 3 files changed, 97 insertions(+), 7 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2093.new diff --git a/changelogs/client_server/newsfragments/2093.new b/changelogs/client_server/newsfragments/2093.new new file mode 100644 index 00000000..28c03ffc --- /dev/null +++ b/changelogs/client_server/newsfragments/2093.new @@ -0,0 +1 @@ +Add `POST /_matrix/client/v3/users/{userId}/report` as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). \ No newline at end of file diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index 6f34e938..ab0e011b 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -29,3 +29,9 @@ is in before accepting a report. based on whether or not the reporting user is joined to the room. This is because users can be exposed to harmful content without being joined to a room. For instance, through room directories or invites. + +{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports +based on whether or not the reporting user is joined to any rooms that the +reported user is joined to. This is because users can be exposed to harmful +content without being joined to a room. For instance, through user +directories or invites. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 654784ca..4934ef3f 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -45,7 +45,9 @@ paths: properties: reason: type: string - description: The reason the room is being reported. + description: The reason the room is being reported. May be blank. + required: + - reason required: true security: - accessTokenQuery: [] @@ -88,12 +90,11 @@ paths: Reports an event as inappropriate to the server, which may then notify the appropriate people. The caller must be joined to the room to report it. - - It might be possible for clients to deduce whether an event exists by - timing the response, as only a report for an event that does exist - will require the homeserver to check whether a user is joined to - the room. To combat this, homeserver implementations should add - a random delay when generating a response. + + Furthermore, it might be possible for clients to deduce whether a reported + event exists by timing the response. This is because only a report for an + existing event will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. operationId: reportEvent parameters: - in: path @@ -164,6 +165,88 @@ paths: } tags: - Reporting content + "/users/{userId}/report": + post: + x-addedInMatrixVersion: "1.14" + summary: Report a user as inappropriate. + description: |- + Reports a user as inappropriate to the server, which may then notify + the appropriate people. How such information is delivered is left up to + implementations. The caller is not required to be joined to any rooms + that the reported user is joined to. + + Clients may wish to [ignore](#ignoring-users) users after reporting them. + + Clients could infer whether a reported user exists based on the 404 response. + Homeservers that wish to conceal this information MAY return 200 responses + regardless of the existence of the reported user. + + Furthermore, it might be possible for clients to deduce whether a reported + user exists by timing the response. This is because only a report for an + existing user will require the homeserver to do further processing. To + combat this, homeservers MAY add a random delay when generating a response. + operationId: reportUser + parameters: + - in: path + name: userId + description: The user being reported. + required: true + example: "@someguy:example.com" + schema: + type: string + format: mx-user-id + pattern: "^@" + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "this makes me sad" + } + properties: + reason: + type: string + description: The reason the room is being reported. May be blank. + required: + - reason + required: true + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: | + The user has been reported successfully or the server chose + to not disclose whether the users exists. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: |- + The user was not found on the homeserver. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The user was not found." + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Reporting content servers: - url: "{protocol}://{hostname}{basePath}" variables: From cb6d039c57d07ea489577d9234813c39e93a2243 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 25 Mar 2025 15:40:04 -0600 Subject: [PATCH 14/22] Normalize changelog --- changelogs/client_server/newsfragments/2051.clarification | 3 +-- changelogs/client_server/newsfragments/2059.removal | 2 +- changelogs/client_server/newsfragments/2093.new | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/changelogs/client_server/newsfragments/2051.clarification b/changelogs/client_server/newsfragments/2051.clarification index e8f7a70c..30cdbc73 100644 --- a/changelogs/client_server/newsfragments/2051.clarification +++ b/changelogs/client_server/newsfragments/2051.clarification @@ -1,2 +1 @@ -Document the `instance_id` field of `Protocol Instance` in the responses to -`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. +Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. diff --git a/changelogs/client_server/newsfragments/2059.removal b/changelogs/client_server/newsfragments/2059.removal index 94db06f8..1075c2e0 100644 --- a/changelogs/client_server/newsfragments/2059.removal +++ b/changelogs/client_server/newsfragments/2059.removal @@ -1 +1 @@ -Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). +Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). diff --git a/changelogs/client_server/newsfragments/2093.new b/changelogs/client_server/newsfragments/2093.new index 28c03ffc..931b93ae 100644 --- a/changelogs/client_server/newsfragments/2093.new +++ b/changelogs/client_server/newsfragments/2093.new @@ -1 +1 @@ -Add `POST /_matrix/client/v3/users/{userId}/report` as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). \ No newline at end of file +Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). \ No newline at end of file From 71ce620fc093e92b5a4ad23ea91c1cb2a09ab1b6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Mar 2025 10:23:09 -0600 Subject: [PATCH 15/22] Add a v6 event format with correct `depth` limits (#2114) * Add a v6 event format with correct `depth` limits * Changelog * numbers are hard --- .../newsfragments/2114.clarification | 1 + content/rooms/fragments/v6-event-format.md | 4 +++ content/rooms/v10.md | 2 +- content/rooms/v6.md | 11 +++--- content/rooms/v7.md | 2 +- content/rooms/v8.md | 2 +- content/rooms/v9.md | 2 +- .../definitions/components/pdu_base.yaml | 7 ---- .../api/server-server/definitions/pdu_v1.yaml | 7 ++++ .../server-server/definitions/pdu_v11.yaml | 14 ++++++-- .../api/server-server/definitions/pdu_v3.yaml | 7 ++++ .../api/server-server/definitions/pdu_v4.yaml | 7 ++++ .../api/server-server/definitions/pdu_v6.yaml | 36 +++++++++++++++++++ 13 files changed, 85 insertions(+), 17 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/2114.clarification create mode 100644 content/rooms/fragments/v6-event-format.md create mode 100644 data/api/server-server/definitions/pdu_v6.yaml 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 From fe880fdaf4f7f8c4f95fe56ea5a0a1ce9498f270 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Mar 2025 10:28:55 -0600 Subject: [PATCH 16/22] v1.14 --- .../newsfragments/1506.clarification | 1 - .../newsfragments/2036.clarification | 1 - .../newsfragments/2038.clarification | 1 - .../newsfragments/2046.clarification | 1 - .../newsfragments/2047.clarification | 1 - .../newsfragments/2048.clarification | 1 - .../newsfragments/2051.clarification | 1 - .../newsfragments/2055.clarification | 1 - .../client_server/newsfragments/2059.removal | 1 - .../newsfragments/2064.clarification | 1 - .../newsfragments/2072.clarification | 1 - .../newsfragments/2080.clarification | 1 - .../newsfragments/2091.clarification | 1 - .../client_server/newsfragments/2093.new | 1 - .../internal/newsfragments/2033.clarification | 1 - .../internal/newsfragments/2041.clarification | 1 - .../internal/newsfragments/2042.clarification | 1 - .../internal/newsfragments/2045.clarification | 1 - .../internal/newsfragments/2049.clarification | 1 - .../internal/newsfragments/2061.clarification | 1 - .../internal/newsfragments/2069.clarification | 1 - .../internal/newsfragments/2073.clarification | 1 - .../internal/newsfragments/2074.clarification | 1 - .../internal/newsfragments/2076.clarification | 1 - .../internal/newsfragments/2078.clarification | 1 - .../newsfragments/2065.clarification | 1 - .../newsfragments/2066.clarification | 1 - .../newsfragments/2070.clarification | 1 - .../room_versions/newsfragments/2105.feature | 1 - .../newsfragments/2114.clarification | 1 - .../newsfragments/2050.clarification | 1 - .../newsfragments/2063.clarification | 1 - .../newsfragments/2076.clarification | 1 - config/_default/hugo.toml | 6 +- content/changelog/v1.14.md | 93 +++++++++++++++++++ 35 files changed, 96 insertions(+), 36 deletions(-) delete mode 100644 changelogs/appendices/newsfragments/1506.clarification delete mode 100644 changelogs/client_server/newsfragments/2036.clarification delete mode 100644 changelogs/client_server/newsfragments/2038.clarification delete mode 100644 changelogs/client_server/newsfragments/2046.clarification delete mode 100644 changelogs/client_server/newsfragments/2047.clarification delete mode 100644 changelogs/client_server/newsfragments/2048.clarification delete mode 100644 changelogs/client_server/newsfragments/2051.clarification delete mode 100644 changelogs/client_server/newsfragments/2055.clarification delete mode 100644 changelogs/client_server/newsfragments/2059.removal delete mode 100644 changelogs/client_server/newsfragments/2064.clarification delete mode 100644 changelogs/client_server/newsfragments/2072.clarification delete mode 100644 changelogs/client_server/newsfragments/2080.clarification delete mode 100644 changelogs/client_server/newsfragments/2091.clarification delete mode 100644 changelogs/client_server/newsfragments/2093.new delete mode 100644 changelogs/internal/newsfragments/2033.clarification delete mode 100644 changelogs/internal/newsfragments/2041.clarification delete mode 100644 changelogs/internal/newsfragments/2042.clarification delete mode 100644 changelogs/internal/newsfragments/2045.clarification delete mode 100644 changelogs/internal/newsfragments/2049.clarification delete mode 100644 changelogs/internal/newsfragments/2061.clarification delete mode 100644 changelogs/internal/newsfragments/2069.clarification delete mode 100644 changelogs/internal/newsfragments/2073.clarification delete mode 100644 changelogs/internal/newsfragments/2074.clarification delete mode 100644 changelogs/internal/newsfragments/2076.clarification delete mode 100644 changelogs/internal/newsfragments/2078.clarification delete mode 100644 changelogs/room_versions/newsfragments/2065.clarification delete mode 100644 changelogs/room_versions/newsfragments/2066.clarification delete mode 100644 changelogs/room_versions/newsfragments/2070.clarification delete mode 100644 changelogs/room_versions/newsfragments/2105.feature delete mode 100644 changelogs/room_versions/newsfragments/2114.clarification delete mode 100644 changelogs/server_server/newsfragments/2050.clarification delete mode 100644 changelogs/server_server/newsfragments/2063.clarification delete mode 100644 changelogs/server_server/newsfragments/2076.clarification create mode 100644 content/changelog/v1.14.md diff --git a/changelogs/appendices/newsfragments/1506.clarification b/changelogs/appendices/newsfragments/1506.clarification deleted file mode 100644 index 41ef5ac4..00000000 --- a/changelogs/appendices/newsfragments/1506.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. diff --git a/changelogs/client_server/newsfragments/2036.clarification b/changelogs/client_server/newsfragments/2036.clarification deleted file mode 100644 index 9e586ae0..00000000 --- a/changelogs/client_server/newsfragments/2036.clarification +++ /dev/null @@ -1 +0,0 @@ -The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. diff --git a/changelogs/client_server/newsfragments/2038.clarification b/changelogs/client_server/newsfragments/2038.clarification deleted file mode 100644 index 169ca65c..00000000 --- a/changelogs/client_server/newsfragments/2038.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/2046.clarification b/changelogs/client_server/newsfragments/2046.clarification deleted file mode 100644 index bdcce777..00000000 --- a/changelogs/client_server/newsfragments/2046.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify formats of string types. diff --git a/changelogs/client_server/newsfragments/2047.clarification b/changelogs/client_server/newsfragments/2047.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/2047.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/2048.clarification b/changelogs/client_server/newsfragments/2048.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/2048.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/2051.clarification b/changelogs/client_server/newsfragments/2051.clarification deleted file mode 100644 index 30cdbc73..00000000 --- a/changelogs/client_server/newsfragments/2051.clarification +++ /dev/null @@ -1 +0,0 @@ -Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. diff --git a/changelogs/client_server/newsfragments/2055.clarification b/changelogs/client_server/newsfragments/2055.clarification deleted file mode 100644 index f8d79ec9..00000000 --- a/changelogs/client_server/newsfragments/2055.clarification +++ /dev/null @@ -1 +0,0 @@ -Applying redactions is a SHOULD for clients. diff --git a/changelogs/client_server/newsfragments/2059.removal b/changelogs/client_server/newsfragments/2059.removal deleted file mode 100644 index 1075c2e0..00000000 --- a/changelogs/client_server/newsfragments/2059.removal +++ /dev/null @@ -1 +0,0 @@ -Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). diff --git a/changelogs/client_server/newsfragments/2064.clarification b/changelogs/client_server/newsfragments/2064.clarification deleted file mode 100644 index 17cc2890..00000000 --- a/changelogs/client_server/newsfragments/2064.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify which rooms are returned from `/hierarchy`. diff --git a/changelogs/client_server/newsfragments/2072.clarification b/changelogs/client_server/newsfragments/2072.clarification deleted file mode 100644 index ddb9a536..00000000 --- a/changelogs/client_server/newsfragments/2072.clarification +++ /dev/null @@ -1 +0,0 @@ -Clients can choose which history visibility options they offer to users when creating rooms. diff --git a/changelogs/client_server/newsfragments/2080.clarification b/changelogs/client_server/newsfragments/2080.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/2080.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/2091.clarification b/changelogs/client_server/newsfragments/2091.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/2091.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/2093.new b/changelogs/client_server/newsfragments/2093.new deleted file mode 100644 index 931b93ae..00000000 --- a/changelogs/client_server/newsfragments/2093.new +++ /dev/null @@ -1 +0,0 @@ -Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). \ No newline at end of file diff --git a/changelogs/internal/newsfragments/2033.clarification b/changelogs/internal/newsfragments/2033.clarification deleted file mode 100644 index 9d3e7596..00000000 --- a/changelogs/internal/newsfragments/2033.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the changelog release info with Hugo, rather than the changelog generation script. diff --git a/changelogs/internal/newsfragments/2041.clarification b/changelogs/internal/newsfragments/2041.clarification deleted file mode 100644 index fd9a66f7..00000000 --- a/changelogs/internal/newsfragments/2041.clarification +++ /dev/null @@ -1 +0,0 @@ -Update release steps documentation. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/2042.clarification b/changelogs/internal/newsfragments/2042.clarification deleted file mode 100644 index 4abe8e4e..00000000 --- a/changelogs/internal/newsfragments/2042.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove unused `release_date` from Hugo config. diff --git a/changelogs/internal/newsfragments/2045.clarification b/changelogs/internal/newsfragments/2045.clarification deleted file mode 100644 index bfe42c51..00000000 --- a/changelogs/internal/newsfragments/2045.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that v1.0 of Matrix was a release prior to the current global versioning system. diff --git a/changelogs/internal/newsfragments/2049.clarification b/changelogs/internal/newsfragments/2049.clarification deleted file mode 100644 index 5a6e90f1..00000000 --- a/changelogs/internal/newsfragments/2049.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. diff --git a/changelogs/internal/newsfragments/2061.clarification b/changelogs/internal/newsfragments/2061.clarification deleted file mode 100644 index 3257cef1..00000000 --- a/changelogs/internal/newsfragments/2061.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the version of the Identity Service API when Matrix 1.0 was introduced. diff --git a/changelogs/internal/newsfragments/2069.clarification b/changelogs/internal/newsfragments/2069.clarification deleted file mode 100644 index 2ad407fb..00000000 --- a/changelogs/internal/newsfragments/2069.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. diff --git a/changelogs/internal/newsfragments/2073.clarification b/changelogs/internal/newsfragments/2073.clarification deleted file mode 100644 index 64dbc6c4..00000000 --- a/changelogs/internal/newsfragments/2073.clarification +++ /dev/null @@ -1 +0,0 @@ -Deduplicate the definition of `RoomKeysUpdateResponse`. diff --git a/changelogs/internal/newsfragments/2074.clarification b/changelogs/internal/newsfragments/2074.clarification deleted file mode 100644 index 4f941dd2..00000000 --- a/changelogs/internal/newsfragments/2074.clarification +++ /dev/null @@ -1 +0,0 @@ -Deduplicate the definitions of `Invite3pid`. diff --git a/changelogs/internal/newsfragments/2076.clarification b/changelogs/internal/newsfragments/2076.clarification deleted file mode 100644 index 3cf1fb94..00000000 --- a/changelogs/internal/newsfragments/2076.clarification +++ /dev/null @@ -1 +0,0 @@ -Support more locations for examples in OpenAPI definitions and JSON schemas. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/2078.clarification b/changelogs/internal/newsfragments/2078.clarification deleted file mode 100644 index d9285d5a..00000000 --- a/changelogs/internal/newsfragments/2078.clarification +++ /dev/null @@ -1 +0,0 @@ -Add link to the git commit for the unstable changelog. diff --git a/changelogs/room_versions/newsfragments/2065.clarification b/changelogs/room_versions/newsfragments/2065.clarification deleted file mode 100644 index e7fc9f20..00000000 --- a/changelogs/room_versions/newsfragments/2065.clarification +++ /dev/null @@ -1 +0,0 @@ -For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. diff --git a/changelogs/room_versions/newsfragments/2066.clarification b/changelogs/room_versions/newsfragments/2066.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/room_versions/newsfragments/2066.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/room_versions/newsfragments/2070.clarification b/changelogs/room_versions/newsfragments/2070.clarification deleted file mode 100644 index 7d0208cd..00000000 --- a/changelogs/room_versions/newsfragments/2070.clarification +++ /dev/null @@ -1 +0,0 @@ -Refactor PDU definitions to reduce duplication. diff --git a/changelogs/room_versions/newsfragments/2105.feature b/changelogs/room_versions/newsfragments/2105.feature deleted file mode 100644 index 9e13a36c..00000000 --- a/changelogs/room_versions/newsfragments/2105.feature +++ /dev/null @@ -1 +0,0 @@ -Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). diff --git a/changelogs/room_versions/newsfragments/2114.clarification b/changelogs/room_versions/newsfragments/2114.clarification deleted file mode 100644 index 46104473..00000000 --- a/changelogs/room_versions/newsfragments/2114.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/2050.clarification b/changelogs/server_server/newsfragments/2050.clarification deleted file mode 100644 index 8c4545d3..00000000 --- a/changelogs/server_server/newsfragments/2050.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. diff --git a/changelogs/server_server/newsfragments/2063.clarification b/changelogs/server_server/newsfragments/2063.clarification deleted file mode 100644 index 4e3df516..00000000 --- a/changelogs/server_server/newsfragments/2063.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/2076.clarification b/changelogs/server_server/newsfragments/2076.clarification deleted file mode 100644 index b3cad0d2..00000000 --- a/changelogs/server_server/newsfragments/2076.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove an erroneous `room_id` field in a few examples. diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 84362b3b..3ad53623 100644 --- a/config/_default/hugo.toml +++ b/config/_default/hugo.toml @@ -61,13 +61,13 @@ copyright = "The Matrix.org Foundation CIC" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. -# major = "1" -# minor = "13" +major = "1" +minor = "14" # User interface configuration [params.ui] diff --git a/content/changelog/v1.14.md b/content/changelog/v1.14.md new file mode 100644 index 00000000..d5f14aba --- /dev/null +++ b/content/changelog/v1.14.md @@ -0,0 +1,93 @@ +--- +title: v1.14 Changelog +linkTitle: v1.14 +type: docs +layout: changelog +outputs: + - html + - checklist +date: 2025-03-27 +--- + +## Client-Server API + +**New Endpoints** + +- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093)) + +**Removed Endpoints** + +- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059)) + +**Spec Clarifications** + +- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036)) +- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038)) +- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046)) +- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091)) +- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051)) +- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055)) +- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064)) +- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072)) + + +## Server-Server API + +**Spec Clarifications** + +- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050)) +- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063)) +- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076)) + + +## Application Service API + +No significant changes. + + +## Identity Service API + +No significant changes. + + +## Push Gateway API + +No significant changes. + + +## Room Versions + +**Backwards Compatible Changes** + +- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105)) + +**Spec Clarifications** + +- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065)) +- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066)) +- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070)) +- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114)) + + +## Appendices + +**Spec Clarifications** + +- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506)) + + +## Internal Changes/Tooling + +**Spec Clarifications** + +- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033)) +- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041)) +- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042)) +- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045)) +- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049)) +- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061)) +- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069)) +- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073)) +- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074)) +- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076)) +- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078)) From 029be205b9e738d56e3f41b7da3ca09b78de0090 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Mar 2025 10:30:02 -0600 Subject: [PATCH 17/22] -> unstable --- config/_default/hugo.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 3ad53623..3394c942 100644 --- a/config/_default/hugo.toml +++ b/config/_default/hugo.toml @@ -61,13 +61,13 @@ copyright = "The Matrix.org Foundation CIC" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. -major = "1" -minor = "14" +# major = "1" +# minor = "14" # User interface configuration [params.ui] From 817ec5380f57aecc392db19e8f2c12361a12249c Mon Sep 17 00:00:00 2001 From: Kim Brose <2803622+HarHarLinks@users.noreply.github.com> Date: Fri, 28 Mar 2025 14:19:23 +0100 Subject: [PATCH 18/22] Create funding-manifest-urls (#2115) * Create funding-manifest-urls * update funding-manifest-urls location, add news Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --------- Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- changelogs/internal/newsfragments/2115.clarification | 1 + static/.well-known/funding-manifest-urls | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/internal/newsfragments/2115.clarification create mode 100644 static/.well-known/funding-manifest-urls diff --git a/changelogs/internal/newsfragments/2115.clarification b/changelogs/internal/newsfragments/2115.clarification new file mode 100644 index 00000000..3deaf8c8 --- /dev/null +++ b/changelogs/internal/newsfragments/2115.clarification @@ -0,0 +1 @@ +Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. diff --git a/static/.well-known/funding-manifest-urls b/static/.well-known/funding-manifest-urls new file mode 100644 index 00000000..1b14b420 --- /dev/null +++ b/static/.well-known/funding-manifest-urls @@ -0,0 +1 @@ +https://matrix.org/funding.json From 8a2c58b1b17b26f742be2e1b0aeafdd41bb5f9fc Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 28 Mar 2025 14:13:17 +0000 Subject: [PATCH 19/22] Typo "not" -> "no" (#2121) * Typo "not" -> "no" Signed-off-by: Andy Balaam --------- Signed-off-by: Andy Balaam --- changelogs/client_server/newsfragments/2121.clarification | 1 + content/client-server-api/modules/secrets.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2121.clarification diff --git a/changelogs/client_server/newsfragments/2121.clarification b/changelogs/client_server/newsfragments/2121.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/2121.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index 3e586bc4..fb997992 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise, clients will try to use the default key to decrypt secrets. Clients that want to present a simplified interface to users by not supporting -multiple keys should use the default key if one is specified. If not default +multiple keys should use the default key if one is specified. If no default key is specified, the client may behave as if there is no key is present at all. When such a client creates a key, it should mark that key as being the default key. From 23ff7f1343ef00c61d148e84b3a26ec7826810b2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 7 Apr 2025 14:28:00 -0600 Subject: [PATCH 20/22] Fix minor typo in content hash calculations (#2128) * Fix minor typo in content hash calculations * Changelog --- changelogs/server_server/newsfragments/2128.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/2128.clarification diff --git a/changelogs/server_server/newsfragments/2128.clarification b/changelogs/server_server/newsfragments/2128.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/2128.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index 65494f80..d93aa51f 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1337,7 +1337,7 @@ calculated as follows. The *content hash* of an event covers the complete event including the *unredacted* contents. It is calculated as follows. -First, any existing `unsigned`, `signature`, and `hashes` members are +First, any existing `unsigned`, `signatures`, and `hashes` properties are removed. The resulting object is then encoded as [Canonical JSON](/appendices#canonical-json), and the JSON is hashed using SHA-256. From c39c7d06807d933c9584c59b9a9f9ba5b096409e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 15 Apr 2025 15:47:21 +0200 Subject: [PATCH 21/22] Fix `/sync` example (#2077) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix sync example The same event should not appear in `state` and in the `timeline` so we cannot use the same event twice. To provide a `state` example we assume that with lazy-loading the user did not get the state event for `@example:example.org`, so we add one since they sent a message in the timeline. The events that are referenced include a `room_id`, which doesn't appear on this endpoint, so we copy them without it. Finally, the `join` event of `@alice:example.org` is wrong because the sender does not match the state key, which wouldn't pass the authorization rules. Signed-off-by: Kévin Commaille * Fix the `m.room.member.yaml` example This is a `join` event, and the `sender` doesn't match the `state_key`, so the event couldn't pass the authorization rules. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../newsfragments/2077.clarification | 1 + data/api/client-server/sync.yaml | 46 +++++++++++++++++-- .../event-schemas/examples/m.room.member.yaml | 1 + 3 files changed, 45 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2077.clarification diff --git a/changelogs/client_server/newsfragments/2077.clarification b/changelogs/client_server/newsfragments/2077.clarification new file mode 100644 index 00000000..2077d47f --- /dev/null +++ b/changelogs/client_server/newsfragments/2077.clarification @@ -0,0 +1 @@ +Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. \ No newline at end of file diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 9d9a807d..e6fd7883 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -441,17 +441,57 @@ paths: "state": { "events": [ { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + "content": { + "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe", + "displayname": "Example user", + "membership": "join" + }, + "event_id": "$143273976499sgjks:example.org", + "origin_server_ts": 1432735824653, + "sender": "@example:example.org", + "state_key": "@example:example.org", + "type": "m.room.member", + "unsigned": { + "age": 45603, + "membership": "join" + } } ] }, "timeline": { "events": [ { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + "content": { + "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", + "displayname": "Alice Margatroid", + "membership": "join", + "reason": "Looking for support" + }, + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653, + "sender": "@alice:example.org", + "state_key": "@alice:example.org", + "type": "m.room.member", + "unsigned": { + "age": 1234, + "membership": "join" + } }, { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + "content": { + "body": "This is an example text message", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example text message", + "msgtype": "m.text" + }, + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653, + "sender": "@example:example.org", + "type": "m.room.message", + "unsigned": { + "age": 1234, + "membership": "join" + } } ], "limited": true, diff --git a/data/event-schemas/examples/m.room.member.yaml b/data/event-schemas/examples/m.room.member.yaml index 5147b258..85e9a9eb 100644 --- a/data/event-schemas/examples/m.room.member.yaml +++ b/data/event-schemas/examples/m.room.member.yaml @@ -1,6 +1,7 @@ { "$ref": "core/state_event.json", "state_key": "@alice:example.org", + "sender": "@alice:example.org", "type": "m.room.member", "content": { "membership": "join", From 65b1db721d1269936b4c9b3d4a8f0fc4250c9f94 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 15 Apr 2025 18:24:22 +0100 Subject: [PATCH 22/22] Describe behaviour when the `topic` key is falsey in a `m.room.topic` event. (#2068) We seem to have [updated this for m.room.name](https://github.com/matrix-org/matrix-spec/pull/1639) some years back but omitted it for topic. --- .../client_server/newsfragments/2068.clarification | 1 + data/event-schemas/schema/m.room.topic.yaml | 9 ++++++++- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/2068.clarification diff --git a/changelogs/client_server/newsfragments/2068.clarification b/changelogs/client_server/newsfragments/2068.clarification new file mode 100644 index 00000000..1b3c13e8 --- /dev/null +++ b/changelogs/client_server/newsfragments/2068.clarification @@ -0,0 +1 @@ +Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. diff --git a/data/event-schemas/schema/m.room.topic.yaml b/data/event-schemas/schema/m.room.topic.yaml index 78a3d878..56f0caf9 100644 --- a/data/event-schemas/schema/m.room.topic.yaml +++ b/data/event-schemas/schema/m.room.topic.yaml @@ -1,7 +1,14 @@ --- allOf: - $ref: core-event-schema/state_event.yaml -description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.' +description: |- + A topic is a short message detailing what is currently being discussed in the room. + It can also be used as a way to display extra information about the room, which may not + be suitable for the room name. + The room topic can also be set when creating a room using `/createRoom` with the `topic` key.' + + If the `topic` property is absent, null, or empty then the topic is unset. In other words, + an empty `topic` property effectively resets the room to having no topic. properties: content: properties:
Git commit{{ $commitLink }}
Release date{{ .Date | time.Format ":date_long" }}