From 9b914c6fd945d25419d03627439bfd223b160ca7 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Sun, 3 Apr 2022 14:21:38 +0200 Subject: [PATCH 01/21] Add rich room topic MSC Signed-off-by: Johannes Marbach --- proposals/3677-rich-room-topics.md | 97 ++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 proposals/3677-rich-room-topics.md diff --git a/proposals/3677-rich-room-topics.md b/proposals/3677-rich-room-topics.md new file mode 100644 index 00000000000..db6688701f8 --- /dev/null +++ b/proposals/3677-rich-room-topics.md @@ -0,0 +1,97 @@ +# MSC3677: Rich text in room topics + +## Problem + +Topics are a central piece of room meta data and usually made easily +accessible to room members in clients. As a result, room administrators +often extend the use of topics to collect helpful peripheral information +that is related to the room’s purpose. Most commonly these are links to +external resources. At the moment, topics are limitted to [plain text] +which, depending on the number and length of URLs and other content, +easily gets inconvenient to consume and calls for richer text formatting +options. + +## Proposal + +To enrich `m.room.topic` events, we build upon extensible events as +defined in [MSC1767] and define a new `m.topic` event in `content`. +The latter contains a list of renderings in the same format that +[MSC1767] uses for `m.message` events. + +``` json +{ + "type": "m.room.topic", + "state_key": "", + "content": { + "m.topic": [{ + "mimetype": "text/html", // optional, default text/plain + "body": "All about pizza | Recipes" + }, { + "mimetype": "text/plain", + "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" + }], + }, + ... +} +``` + +A change to `/_matrix/client/v3/createRoom` is not necessary. The +endpoint has a plain text `topic` parameter but also allows to specify a +full `m.room.topic` event in `initial_state`. + +Room topics also occur as part of the `PublicRoomsChunk` object in the +responses of `/_matrix/client/v3/publicRooms` and +`/_matrix/client/v1/rooms/{roomId}/hierarchy`. The topic can be kept +plain text here because this data should commonly only be displayed to +users that are *not* a member of the room yet. These users will not have +the same need for rich room topics as users who are inside the room. + +## Transition + +Similar to [MSC1767] a time-constrained transition period is proposed. +Upon being included in a released version of the specification, the +following happens: + +- The `topic` field in the content of `m.room.topic` events is + deprecated +- Clients continue to include `topic` in outgoing events as a fallback +- Clients prefer the new `m.topic` format in events which include it +- A 1 year timer begins for clients to implement the above conditions + - This can be shortened if the ecosystem adopts the format sooner + - After the (potentially shortened) timer, an MSC is introduced to + remove the deprecated `topic` field. Once accepted under the + relevant process, clients stop including the field in outgoing + events. + +## Potential issues + +None. + +## Alternatives + +The combination of `format` and `formatted_body` currently utilised to +enable HTML in `m.room.message` events could be generalised to +`m.room.topic` events. However, this would only allow for a single +format in addition to plain text and is a weaker form of reuse as +described in the introductory section of [MSC1767]. + +## Security considerations + +Allowing HTML in room topics is subject to the same security +considerations that apply to HTML in room messages. + +## Unstable prefix + +While this MSC is not considered stable, implementations should apply +the behaviours of this MSC on top of room version 9 as +org.matrix.msc3677. + +- `m.topic` should be referred to as `org.matrix.msc3677.topic` until + this MSC lands + +## Dependencies + +- [MSC1767] + + [plain text]: https://spec.matrix.org/v1.2/client-server-api/#mroomtopic + [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 From 06d315da1530ac3678dcbf21cde2fcad2278a52a Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Sun, 3 Apr 2022 14:28:54 +0200 Subject: [PATCH 02/21] Rename to reflect propper MSC number --- .../{3677-rich-room-topics.md => 3765-rich-room-topics.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename proposals/{3677-rich-room-topics.md => 3765-rich-room-topics.md} (96%) diff --git a/proposals/3677-rich-room-topics.md b/proposals/3765-rich-room-topics.md similarity index 96% rename from proposals/3677-rich-room-topics.md rename to proposals/3765-rich-room-topics.md index db6688701f8..cf7ceb4869b 100644 --- a/proposals/3677-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -1,4 +1,4 @@ -# MSC3677: Rich text in room topics +# MSC3765: Rich text in room topics ## Problem @@ -84,9 +84,9 @@ considerations that apply to HTML in room messages. While this MSC is not considered stable, implementations should apply the behaviours of this MSC on top of room version 9 as -org.matrix.msc3677. +org.matrix.msc3765. -- `m.topic` should be referred to as `org.matrix.msc3677.topic` until +- `m.topic` should be referred to as `org.matrix.msc3765.topic` until this MSC lands ## Dependencies From 09c7014e2d1ec2ce6be83f1214faf7bb7bfe82c4 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Sun, 3 Apr 2022 14:30:29 +0200 Subject: [PATCH 03/21] Fix typo --- proposals/3765-rich-room-topics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index cf7ceb4869b..782feccc613 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -6,7 +6,7 @@ Topics are a central piece of room meta data and usually made easily accessible to room members in clients. As a result, room administrators often extend the use of topics to collect helpful peripheral information that is related to the room’s purpose. Most commonly these are links to -external resources. At the moment, topics are limitted to [plain text] +external resources. At the moment, topics are limited to [plain text] which, depending on the number and length of URLs and other content, easily gets inconvenient to consume and calls for richer text formatting options. From 1d0031ae03b09a3e3e259d546bc4f6d7de37a270 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 4 Apr 2022 19:49:52 +0200 Subject: [PATCH 04/21] Explain why m.topic is kept separate from m.message --- proposals/3765-rich-room-topics.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 782feccc613..05e4827a3f1 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -35,6 +35,9 @@ The latter contains a list of renderings in the same format that } ``` +While the content of `m.topic` is currently identical to `m.message`, a +dedicated event type allows the two to diverge in the future. + A change to `/_matrix/client/v3/createRoom` is not necessary. The endpoint has a plain text `topic` parameter but also allows to specify a full `m.room.topic` event in `initial_state`. From 3b572e7d1bcfd8add10b407b022d7fecde759dda Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 4 Apr 2022 20:11:13 +0200 Subject: [PATCH 05/21] Use json5 for formatting code snippet Co-authored-by: Travis Ralston --- proposals/3765-rich-room-topics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 05e4827a3f1..92cf33faf7a 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -18,7 +18,7 @@ defined in [MSC1767] and define a new `m.topic` event in `content`. The latter contains a list of renderings in the same format that [MSC1767] uses for `m.message` events. -``` json +```json5 { "type": "m.room.topic", "state_key": "", From 62701096dd8014f5e30b43223e3067b3386ef3d8 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 4 Apr 2022 20:13:01 +0200 Subject: [PATCH 06/21] Remove unneeded unstable room version --- proposals/3765-rich-room-topics.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 92cf33faf7a..08fa846fc62 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -85,12 +85,8 @@ considerations that apply to HTML in room messages. ## Unstable prefix -While this MSC is not considered stable, implementations should apply -the behaviours of this MSC on top of room version 9 as -org.matrix.msc3765. - -- `m.topic` should be referred to as `org.matrix.msc3765.topic` until - this MSC lands +While this MSC is not considered stable, `m.topic` should be referred +to as `org.matrix.msc3765.topic`. ## Dependencies From af184dd30135c11934b3c5c041d12887c70731e8 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 5 Jan 2023 15:50:59 +0100 Subject: [PATCH 07/21] Adapt to latest version of MSC1767 --- proposals/3765-rich-room-topics.md | 87 ++++++++++++++++++++---------- 1 file changed, 59 insertions(+), 28 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 08fa846fc62..38273fde826 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -13,18 +13,18 @@ options. ## Proposal -To enrich `m.room.topic` events, we build upon extensible events as -defined in [MSC1767] and define a new `m.topic` event in `content`. -The latter contains a list of renderings in the same format that -[MSC1767] uses for `m.message` events. +Drawing from extensible events as described in [MSC1767], +`m.room.topic` is formally deprecated and replaced with a new `m.topic` +event type. The latter contains an `m.markup` content block representing +the room topic in different mime types. -```json5 +``` json5 { - "type": "m.room.topic", + "type": "m.topic", "state_key": "", "content": { - "m.topic": [{ - "mimetype": "text/html", // optional, default text/plain + "m.markup": [{ + "mimetype": "text/html", "body": "All about pizza | Recipes" }, { "mimetype": "text/plain", @@ -35,12 +35,15 @@ The latter contains a list of renderings in the same format that } ``` +Details of how `m.markup` works may be found in [MSC1767] and are not +repeated here. + While the content of `m.topic` is currently identical to `m.message`, a dedicated event type allows the two to diverge in the future. A change to `/_matrix/client/v3/createRoom` is not necessary. The endpoint has a plain text `topic` parameter but also allows to specify a -full `m.room.topic` event in `initial_state`. +full `m.topic` event in `initial_state`. Room topics also occur as part of the `PublicRoomsChunk` object in the responses of `/_matrix/client/v3/publicRooms` and @@ -51,20 +54,47 @@ the same need for rich room topics as users who are inside the room. ## Transition -Similar to [MSC1767] a time-constrained transition period is proposed. -Upon being included in a released version of the specification, the -following happens: - -- The `topic` field in the content of `m.room.topic` events is - deprecated -- Clients continue to include `topic` in outgoing events as a fallback -- Clients prefer the new `m.topic` format in events which include it -- A 1 year timer begins for clients to implement the above conditions - - This can be shortened if the ecosystem adopts the format sooner - - After the (potentially shortened) timer, an MSC is introduced to - remove the deprecated `topic` field. Once accepted under the - relevant process, clients stop including the field in outgoing - events. +The same transition mechanism as in [MSC1767] is proposed. In +particular, this means a new room version N is introduced. Starting from +N clients are not permitted to send `m.room.topic` events anymore and +MUST treat `m.room.topic` as an invalid event type. Instead the new +`m.topic` event type is to be used. + +Similarly, servers use the `m.topic` event type instead of +`m.room.topic` when creating rooms with a room version greater or equal +to N. + +Specific care should be taken when rooms are upgraded via +[`/rooms/{roomId}/upgrade`]. If the new room version is greater or +equal to N, an existing `m.room.topic` event in the old room + +``` json5 +{ + "type": "m.room.topic", + "state_key": "", + "content": { + "topic": "All about pizza" + }, + ... +} +``` + +should be migrated to an `m.topic` event with a single plain-text markup +in the new room + +``` json5 +{ + "type": "m.topic", + "state_key": "", + "content": { + "m.markup": [{ + "mimetype": "text/plain", + "body": "All about pizza" + }], + }, + ... +} +``` ## Potential issues @@ -74,8 +104,8 @@ None. The combination of `format` and `formatted_body` currently utilised to enable HTML in `m.room.message` events could be generalised to -`m.room.topic` events. However, this would only allow for a single -format in addition to plain text and is a weaker form of reuse as +`m.topic` events. However, this would only allow for a single +format in addition to plain text and is a weaker form of reuse than described in the introductory section of [MSC1767]. ## Security considerations @@ -85,12 +115,13 @@ considerations that apply to HTML in room messages. ## Unstable prefix -While this MSC is not considered stable, `m.topic` should be referred -to as `org.matrix.msc3765.topic`. +While this MSC is not considered stable, `m.topic` should be referred to +as `org.matrix.msc3765.topic`. ## Dependencies -- [MSC1767] +- [MSC1767] [plain text]: https://spec.matrix.org/v1.2/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 + [`/rooms/{roomId}/upgrade`]: https://spec.matrix.org/v1.5/client-server-api/#post_matrixclientv3roomsroomidupgrade From aa373d1eb3963b84ea6e6d86cd228cfd217b3d9e Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 5 Jan 2023 16:03:12 +0100 Subject: [PATCH 08/21] Add paragraph about preventing formatting abuse --- proposals/3765-rich-room-topics.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 38273fde826..62898252cc5 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -38,6 +38,12 @@ the room topic in different mime types. Details of how `m.markup` works may be found in [MSC1767] and are not repeated here. +In order to prevent formatting abuse in room topics, clients are +encouraged to treat the first two lines as the shorthand topic and the +remainder as additional information. Specifically, this means that +things like headings and enumerations should be ignored (or formatted +as regular text) unless they occur after the second line. + While the content of `m.topic` is currently identical to `m.message`, a dedicated event type allows the two to diverge in the future. From ea93852a81167981f4a303db04461ea317050291 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 23 Feb 2024 21:08:00 +0100 Subject: [PATCH 09/21] Introduce wrapping m.topic content block (#4111) --- proposals/3765-rich-room-topics.md | 75 ++++++++++++++++-------------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 62898252cc5..5b4233617c7 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -15,38 +15,41 @@ options. Drawing from extensible events as described in [MSC1767], `m.room.topic` is formally deprecated and replaced with a new `m.topic` -event type. The latter contains an `m.markup` content block representing -the room topic in different mime types. +event type. The latter contains a new content block `m.topic` which wraps +an `m.text` content block that allows representing the room topic in +different mime types. ``` json5 { - "type": "m.topic", - "state_key": "", - "content": { - "m.markup": [{ - "mimetype": "text/html", - "body": "All about pizza | Recipes" - }, { - "mimetype": "text/plain", - "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" - }], - }, - ... + "type": "m.topic", + "state_key": "", + "content": { + "m.topic": { + "m.text": [{ + "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" + }, { + "mimetype": "text/html", + "body": "All about pizza | Recipes" + }] + } + }, + ... } ``` -Details of how `m.markup` works may be found in [MSC1767] and are not +Details of how `m.text` works may be found in [MSC1767] and are not repeated here. +The wrapping `m.topic` content block is similar to `m.caption` for file +uploads as defined in [MSC3551]. It avoids clients accidentally rendering +the topic state event as a room message. + In order to prevent formatting abuse in room topics, clients are encouraged to treat the first two lines as the shorthand topic and the remainder as additional information. Specifically, this means that things like headings and enumerations should be ignored (or formatted as regular text) unless they occur after the second line. -While the content of `m.topic` is currently identical to `m.message`, a -dedicated event type allows the two to diverge in the future. - A change to `/_matrix/client/v3/createRoom` is not necessary. The endpoint has a plain text `topic` parameter but also allows to specify a full `m.topic` event in `initial_state`. @@ -76,29 +79,30 @@ equal to N, an existing `m.room.topic` event in the old room ``` json5 { - "type": "m.room.topic", - "state_key": "", - "content": { - "topic": "All about pizza" - }, - ... + "type": "m.room.topic", + "state_key": "", + "content": { + "topic": "All about pizza" + }, + ... } ``` -should be migrated to an `m.topic` event with a single plain-text markup -in the new room +should be migrated to an `m.topic` event with a single plain-text entry +in `m.text` in the new room ``` json5 { - "type": "m.topic", - "state_key": "", - "content": { - "m.markup": [{ - "mimetype": "text/plain", - "body": "All about pizza" - }], - }, - ... + "type": "m.topic", + "state_key": "", + "content": { + "m.topic": { + "m.text": [{ + "body": "All about pizza" + }] + } + }, + ... } ``` @@ -130,4 +134,5 @@ as `org.matrix.msc3765.topic`. [plain text]: https://spec.matrix.org/v1.2/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 + [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 [`/rooms/{roomId}/upgrade`]: https://spec.matrix.org/v1.5/client-server-api/#post_matrixclientv3roomsroomidupgrade From a6b155565067d1a97b0164a1132be88b9eaf6d95 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 23 Feb 2024 21:28:31 +0100 Subject: [PATCH 10/21] Clarify the case of HTML-only topics and transition logic (#4112) * Clarify and simplify transition logic * Clarify the case of HTML-only topics --- proposals/3765-rich-room-topics.md | 51 +++++------------------------- 1 file changed, 8 insertions(+), 43 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 5b4233617c7..fa322c725f2 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -59,52 +59,17 @@ responses of `/_matrix/client/v3/publicRooms` and `/_matrix/client/v1/rooms/{roomId}/hierarchy`. The topic can be kept plain text here because this data should commonly only be displayed to users that are *not* a member of the room yet. These users will not have -the same need for rich room topics as users who are inside the room. +the same need for rich room topics as users who are inside the room. If +no plain text topic exists, home servers should return an empty topic +string from these end points. Since this will inevitably lead to bad UX, +client implementations are encouraged to always include a plain text +variant when sending `m.topic` events. ## Transition -The same transition mechanism as in [MSC1767] is proposed. In -particular, this means a new room version N is introduced. Starting from -N clients are not permitted to send `m.room.topic` events anymore and -MUST treat `m.room.topic` as an invalid event type. Instead the new -`m.topic` event type is to be used. - -Similarly, servers use the `m.topic` event type instead of -`m.room.topic` when creating rooms with a room version greater or equal -to N. - -Specific care should be taken when rooms are upgraded via -[`/rooms/{roomId}/upgrade`]. If the new room version is greater or -equal to N, an existing `m.room.topic` event in the old room - -``` json5 -{ - "type": "m.room.topic", - "state_key": "", - "content": { - "topic": "All about pizza" - }, - ... -} -``` - -should be migrated to an `m.topic` event with a single plain-text entry -in `m.text` in the new room - -``` json5 -{ - "type": "m.topic", - "state_key": "", - "content": { - "m.topic": { - "m.text": [{ - "body": "All about pizza" - }] - } - }, - ... -} -``` +As this MSC replaces `m.room.topic` for an extensible alternative, +clients and servers are expected to treat `m.room.topic` as invalid in +extensible event-supporting room versions. ## Potential issues From 95fb38a613c8426df5a3f4cdea1b785ed852789f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 26 Aug 2024 16:03:54 +0200 Subject: [PATCH 11/21] Make it more explicit that m.topic replaces m.room.topic without deprecation (#4181) --- proposals/3765-rich-room-topics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index fa322c725f2..84878c91c76 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -13,11 +13,11 @@ options. ## Proposal -Drawing from extensible events as described in [MSC1767], -`m.room.topic` is formally deprecated and replaced with a new `m.topic` -event type. The latter contains a new content block `m.topic` which wraps -an `m.text` content block that allows representing the room topic in -different mime types. +Drawing from extensible events as described in [MSC1767], `m.room.topic` +is prohibited in room versions that support extensible events and replaced +with a new `m.topic` event type. The latter contains a new content block +`m.topic` which wraps an `m.text` content block that allows representing +the room topic in different mime types. ``` json5 { From f915cc4663c153f18c77b5fe05081eafc4e9d37c Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 27 Aug 2024 14:05:14 +0200 Subject: [PATCH 12/21] Remove line-based formatting logic and limit length of topics (#4182) --- proposals/3765-rich-room-topics.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 84878c91c76..824e5658d40 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -45,10 +45,11 @@ uploads as defined in [MSC3551]. It avoids clients accidentally rendering the topic state event as a room message. In order to prevent formatting abuse in room topics, clients are -encouraged to treat the first two lines as the shorthand topic and the -remainder as additional information. Specifically, this means that -things like headings and enumerations should be ignored (or formatted -as regular text) unless they occur after the second line. +encouraged to limit the length of topics to at most two lines. Additionally, +clients should ignore things like headings and enumerations (or format them +as regular text). A future MSC may introduce a mechanism to capture extended +multiline details that are not suitable for room topics in a separate field +or event type. A change to `/_matrix/client/v3/createRoom` is not necessary. The endpoint has a plain text `topic` parameter but also allows to specify a From 385bf0ba194141cecec6e3a6bcb3de72271d0530 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 14:01:10 +0200 Subject: [PATCH 13/21] Update MSC3765: Rich text in room topics (#4215) Updates MSC from feedback, --- proposals/3765-rich-room-topics.md | 84 ++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 21 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 824e5658d40..38de31ab6e1 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -44,6 +44,10 @@ The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering the topic state event as a room message. +It is recommended that clients always include a plain text variant when +sending `m.topic` events. This prevents bad UX in situations where a plain +text topic is sufficient such as the public rooms directory. + In order to prevent formatting abuse in room topics, clients are encouraged to limit the length of topics to at most two lines. Additionally, clients should ignore things like headings and enumerations (or format them @@ -51,26 +55,41 @@ as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field or event type. -A change to `/_matrix/client/v3/createRoom` is not necessary. The -endpoint has a plain text `topic` parameter but also allows to specify a -full `m.topic` event in `initial_state`. - -Room topics also occur as part of the `PublicRoomsChunk` object in the -responses of `/_matrix/client/v3/publicRooms` and -`/_matrix/client/v1/rooms/{roomId}/hierarchy`. The topic can be kept -plain text here because this data should commonly only be displayed to -users that are *not* a member of the room yet. These users will not have -the same need for rich room topics as users who are inside the room. If -no plain text topic exists, home servers should return an empty topic -string from these end points. Since this will inevitably lead to bad UX, -client implementations are encouraged to always include a plain text -variant when sending `m.topic` events. +On the server side, any logic that currently operates on `m.room.topic` is +updated to use `m.topic` instead. + +In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.topic` +to be written with a `text/plain` mimetype. If an `m.topic` event is supplied +in `initial_state`, the `topic` parameter overwrites its `text/plain` mimetype +but retains any other mimetypes. + +In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] +and their `POST` siblings, the `topic` response field is read from the +`text/plain` mimetype of `m.topic` if it exists or omitted otherwise. +A plain text topic is sufficient here because this data is commonly +only displayed to users that are *not* a member of the room yet. These +users don't have the same need for rich room topics as users who already +reside in the room. + +The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] +and [`/_matrix/federation/v1/hierarchy/{roomId}`]. + +In [server side search], the `room_events` category is expanded to search +over the `text/plain` mimetype in `m.topic`. + +Finally, `m.topic` is also added to the events that are recommended for +inclusion in [stripped state]. ## Transition As this MSC replaces `m.room.topic` for an extensible alternative, clients and servers are expected to treat `m.room.topic` as invalid in -extensible event-supporting room versions. +extensible event-supporting room versions. Similarly, `m.topic` cannot +be used in non-extensible-supporting room versions. + +It is recommended that servers replicate `m.room.topic` to `m.topic` +with a plain text mimetype and vice versa when [upgrading] between room +versions that do and don't support extensible events. ## Potential issues @@ -87,18 +106,41 @@ described in the introductory section of [MSC1767]. ## Security considerations Allowing HTML in room topics is subject to the same security -considerations that apply to HTML in room messages. +considerations that apply to HTML in room messages. In particular, +topics are already included in the content that clients should [sanitise] +for unsafe HTML. + +## Other notes + +Normally extensible events would only be permitted in a specific +room version. However, to facilitate adoption, clients MAY include +the `m.topic` content block in `m.room.topic` events in room +versions that don't support extensible events. They must, however, +take care to always duplicate the plain text mimetype into the +normal `topic` field, too. This ensures compatibility for clients +and servers that don't support this proposal. Since such clients +are likely to delete the `m.topic` content block when updating +`m.room.topic` themselves, it also helps prevent inconsistencies. ## Unstable prefix While this MSC is not considered stable, `m.topic` should be referred to -as `org.matrix.msc3765.topic`. +as `org.matrix.msc3765.topic`. Note that extensible events and content +blocks might have their own prefixing requirements. ## Dependencies - [MSC1767] - [plain text]: https://spec.matrix.org/v1.2/client-server-api/#mroomtopic - [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 - [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 - [`/rooms/{roomId}/upgrade`]: https://spec.matrix.org/v1.5/client-server-api/#post_matrixclientv3roomsroomidupgrade +[plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic +[MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 +[MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations +[server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search +[stripped state]: https://spec.matrix.org/v1.12/client-server-api/#stripped-state +[upgrading]: https://spec.matrix.org/v1.12/client-server-api/#room-upgrades +[`/_matrix/client/v1/rooms/{roomId}/hierarchy`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv1roomsroomidhierarchy +[`/_matrix/client/v3/createRoom`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3createroom +[`/_matrix/federation/v1/hierarchy/{roomId}`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1hierarchyroomid +[`GET /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms +[`GET /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1publicrooms From bb726db4d82f9c6b84a1b15f3dec557c9e462fbe Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 29 Oct 2024 09:58:36 +0000 Subject: [PATCH 14/21] Accept suggestion Co-authored-by: Johannes Marbach --- proposals/3765-rich-room-topics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 38de31ab6e1..ed6b6c639b2 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -75,7 +75,7 @@ The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] and [`/_matrix/federation/v1/hierarchy/{roomId}`]. In [server side search], the `room_events` category is expanded to search -over the `text/plain` mimetype in `m.topic`. +over the `m.text` content block of `m.topic` events. Finally, `m.topic` is also added to the events that are recommended for inclusion in [stripped state]. From 1b4682e43a6ba6fa44af1cfbd3694fe512302f8c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 4 Nov 2024 09:57:29 -0500 Subject: [PATCH 15/21] Clarify length / display limits. Co-authored-by: Johannes Marbach --- proposals/3765-rich-room-topics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index ed6b6c639b2..54f319b6216 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -49,7 +49,8 @@ sending `m.topic` events. This prevents bad UX in situations where a plain text topic is sufficient such as the public rooms directory. In order to prevent formatting abuse in room topics, clients are -encouraged to limit the length of topics to at most two lines. Additionally, +encouraged to limit the length of topics during both entry and display, +for instance, by capping the number of displayed lines. Additionally, clients should ignore things like headings and enumerations (or format them as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field From d42f0e36866c397932f969c0e9a1050499b9fab1 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 26 Nov 2024 07:58:59 -0500 Subject: [PATCH 16/21] Apply clarifications from author Co-authored-by: Johannes Marbach --- proposals/3765-rich-room-topics.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 54f319b6216..d389159a5c7 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -60,17 +60,19 @@ On the server side, any logic that currently operates on `m.room.topic` is updated to use `m.topic` instead. In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.topic` -to be written with a `text/plain` mimetype. If an `m.topic` event is supplied -in `initial_state`, the `topic` parameter overwrites its `text/plain` mimetype -but retains any other mimetypes. +to be written with a `text/plain` mimetype. If at the same time an `m.topic` +event is supplied in `initial_state`, it is overwritten entirely. A future MSC +may generalize the `topic` parameter to allow specifying other mime types +without `initial_state`. In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] and their `POST` siblings, the `topic` response field is read from the `text/plain` mimetype of `m.topic` if it exists or omitted otherwise. A plain text topic is sufficient here because this data is commonly only displayed to users that are *not* a member of the room yet. These -users don't have the same need for rich room topics as users who already -reside in the room. +users don't commonly have the same need for rich room topics as users +who already reside in the room. A future MSC may update these endpoints +to support rich text topics. The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] and [`/_matrix/federation/v1/hierarchy/{roomId}`]. From fda22d8b4cc15d99197b49c61d417fb48a523aa8 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 12 Dec 2024 22:10:55 +0100 Subject: [PATCH 17/21] Make MSC3765 independent of extensible events and new room versions (#4240) --- proposals/3765-rich-room-topics.md | 81 +++++++++++------------------- 1 file changed, 30 insertions(+), 51 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index d389159a5c7..74417269835 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -13,25 +13,26 @@ options. ## Proposal -Drawing from extensible events as described in [MSC1767], `m.room.topic` -is prohibited in room versions that support extensible events and replaced -with a new `m.topic` event type. The latter contains a new content block -`m.topic` which wraps an `m.text` content block that allows representing -the room topic in different mime types. +Drawing from extensible events as described in [MSC1767], a new content +block `m.topic` is defined, which wraps an `m.text` content block that +allows representing the room topic in different mime types. In current +room versions, this content block is added to the content of [`m.room.topic`] +events as shown below[^1]. -``` json5 +```json5 { - "type": "m.topic", + "type": "m.room.topic", "state_key": "", "content": { "m.topic": { "m.text": [{ - "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" + "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" }, { - "mimetype": "text/html", - "body": "All about pizza | Recipes" + "mimetype": "text/html", + "body": "All about pizza | Recipes" }] - } + }, + "topic": "All about **pizza** | [Recipes](https://recipes.pizza.net)" }, ... } @@ -48,6 +49,12 @@ It is recommended that clients always include a plain text variant when sending `m.topic` events. This prevents bad UX in situations where a plain text topic is sufficient such as the public rooms directory. +Additionally, clients should duplicate the plain text topic into the existing +`topic` field for backwards compatibility with clients that don't support +`m.topic` yet. This also helps prevent inconsistencies since such clients +are likely to delete the `m.topic` content block when updating `m.room.topic` +themselves. + In order to prevent formatting abuse in room topics, clients are encouraged to limit the length of topics during both entry and display, for instance, by capping the number of displayed lines. Additionally, @@ -56,14 +63,14 @@ as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field or event type. -On the server side, any logic that currently operates on `m.room.topic` is -updated to use `m.topic` instead. +On the server side, any logic that currently operates on the `topic` field is +updated to use the `m.topic` content block instead. -In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.topic` -to be written with a `text/plain` mimetype. If at the same time an `m.topic` -event is supplied in `initial_state`, it is overwritten entirely. A future MSC -may generalize the `topic` parameter to allow specifying other mime types -without `initial_state`. +In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.room.topic` +to be written with a `text/plain` mimetype in `m.topic`. If at the same time an +`m.room.topic` event is supplied in `initial_state`, it is overwritten entirely. +A future MSC may generalize the `topic` parameter to allow specifying other mime +types without `initial_state`. In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] and their `POST` siblings, the `topic` response field is read from the @@ -78,21 +85,7 @@ The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] and [`/_matrix/federation/v1/hierarchy/{roomId}`]. In [server side search], the `room_events` category is expanded to search -over the `m.text` content block of `m.topic` events. - -Finally, `m.topic` is also added to the events that are recommended for -inclusion in [stripped state]. - -## Transition - -As this MSC replaces `m.room.topic` for an extensible alternative, -clients and servers are expected to treat `m.room.topic` as invalid in -extensible event-supporting room versions. Similarly, `m.topic` cannot -be used in non-extensible-supporting room versions. - -It is recommended that servers replicate `m.room.topic` to `m.topic` -with a plain text mimetype and vice versa when [upgrading] between room -versions that do and don't support extensible events. +over the `m.text` content block of `m.room.topic` events. ## Potential issues @@ -102,7 +95,7 @@ None. The combination of `format` and `formatted_body` currently utilised to enable HTML in `m.room.message` events could be generalised to -`m.topic` events. However, this would only allow for a single +`m.room.topic` events. However, this would only allow for a single format in addition to plain text and is a weaker form of reuse than described in the introductory section of [MSC1767]. @@ -113,35 +106,21 @@ considerations that apply to HTML in room messages. In particular, topics are already included in the content that clients should [sanitise] for unsafe HTML. -## Other notes - -Normally extensible events would only be permitted in a specific -room version. However, to facilitate adoption, clients MAY include -the `m.topic` content block in `m.room.topic` events in room -versions that don't support extensible events. They must, however, -take care to always duplicate the plain text mimetype into the -normal `topic` field, too. This ensures compatibility for clients -and servers that don't support this proposal. Since such clients -are likely to delete the `m.topic` content block when updating -`m.room.topic` themselves, it also helps prevent inconsistencies. - ## Unstable prefix While this MSC is not considered stable, `m.topic` should be referred to as `org.matrix.msc3765.topic`. Note that extensible events and content blocks might have their own prefixing requirements. -## Dependencies - -- [MSC1767] +[^1]: A future MSC may discuss how to adopt the `m.topic` content block in + new room versions which support extensible events. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 [sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations [server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search -[stripped state]: https://spec.matrix.org/v1.12/client-server-api/#stripped-state -[upgrading]: https://spec.matrix.org/v1.12/client-server-api/#room-upgrades +[`m.room.topic`]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [`/_matrix/client/v1/rooms/{roomId}/hierarchy`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv1roomsroomidhierarchy [`/_matrix/client/v3/createRoom`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3createroom [`/_matrix/federation/v1/hierarchy/{roomId}`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1hierarchyroomid From ac5c6fcbb7ff3796a425f1336eac4ce85c69f4d5 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 18 Dec 2024 10:29:16 +0000 Subject: [PATCH 18/21] Apply suggestions from code review --- proposals/3765-rich-room-topics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 74417269835..c7b2be6ad41 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -45,8 +45,8 @@ The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering the topic state event as a room message. -It is recommended that clients always include a plain text variant when -sending `m.topic` events. This prevents bad UX in situations where a plain +It is recommended that clients always include a plain text variant within `m.text` when +sending `m.room.topic` events. This prevents bad UX in situations where a plain text topic is sufficient such as the public rooms directory. Additionally, clients should duplicate the plain text topic into the existing @@ -66,14 +66,14 @@ or event type. On the server side, any logic that currently operates on the `topic` field is updated to use the `m.topic` content block instead. -In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.room.topic` +In [`/_matrix/client/v3/createRoom`], the `topic` parameter should cause `m.room.topic` to be written with a `text/plain` mimetype in `m.topic`. If at the same time an `m.room.topic` event is supplied in `initial_state`, it is overwritten entirely. A future MSC may generalize the `topic` parameter to allow specifying other mime types without `initial_state`. In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] -and their `POST` siblings, the `topic` response field is read from the +and their `POST` siblings, the `topic` response field should be read from the `text/plain` mimetype of `m.topic` if it exists or omitted otherwise. A plain text topic is sufficient here because this data is commonly only displayed to users that are *not* a member of the room yet. These From 79e3f5d476bdd91f6d8a03510a279710f21d38fc Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 21 Jan 2025 14:46:31 +0000 Subject: [PATCH 19/21] Update proposals/3765-rich-room-topics.md Co-authored-by: Johannes Marbach --- proposals/3765-rich-room-topics.md | 41 ++++++++++++++---------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index c7b2be6ad41..1724e0679ac 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -64,28 +64,25 @@ multiline details that are not suitable for room topics in a separate field or event type. On the server side, any logic that currently operates on the `topic` field is -updated to use the `m.topic` content block instead. - -In [`/_matrix/client/v3/createRoom`], the `topic` parameter should cause `m.room.topic` -to be written with a `text/plain` mimetype in `m.topic`. If at the same time an -`m.room.topic` event is supplied in `initial_state`, it is overwritten entirely. -A future MSC may generalize the `topic` parameter to allow specifying other mime -types without `initial_state`. - -In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] -and their `POST` siblings, the `topic` response field should be read from the -`text/plain` mimetype of `m.topic` if it exists or omitted otherwise. -A plain text topic is sufficient here because this data is commonly -only displayed to users that are *not* a member of the room yet. These -users don't commonly have the same need for rich room topics as users -who already reside in the room. A future MSC may update these endpoints -to support rich text topics. - -The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] -and [`/_matrix/federation/v1/hierarchy/{roomId}`]. - -In [server side search], the `room_events` category is expanded to search -over the `m.text` content block of `m.room.topic` events. +updated to use the `m.topic` content block instead: + +- In [`/_matrix/client/v3/createRoom`], the `topic` parameter should cause `m.room.topic` + to be written with a `text/plain` mimetype in `m.topic`. If at the same time an + `m.room.topic` event is supplied in `initial_state`, it is overwritten entirely. + A future MSC may generalize the `topic` parameter to allow specifying other mime + types without `initial_state`. +- In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] + and their `POST` siblings, the `topic` response field should be read from the + `text/plain` mimetype of `m.topic` if it exists or omitted otherwise. + A plain text topic is sufficient here because this data is commonly + only displayed to users that are *not* a member of the room yet. These + users don't commonly have the same need for rich room topics as users + who already reside in the room. A future MSC may update these endpoints + to support rich text topics. +- The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] + and [`/_matrix/federation/v1/hierarchy/{roomId}`]. +- In [server side search], the `room_events` category is expanded to search + over the `m.text` content block of `m.room.topic` events. ## Potential issues From a64a82520cb540c9e586b3fbb8a723ec5e0aefd9 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 21 Jan 2025 15:51:53 +0100 Subject: [PATCH 20/21] Properly explain why the m.topic content block is needed (#4251) --- proposals/3765-rich-room-topics.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 1724e0679ac..de63e4661ba 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -43,7 +43,13 @@ repeated here. The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering -the topic state event as a room message. +the topic as a room message. Note that while [MSC1767] had explicitly +excluded state events from being treated as extensible, this is being +changed with [MSC4252]. The extra content block, therefore, allows putting +a fallback representation that is actually designated for the timeline +into a separate `content['m.text']` field. Lastly, the `m.topic` content +block also serves as a good place for additional fields to be added by +other MSCs in the future. It is recommended that clients always include a plain text variant within `m.text` when sending `m.room.topic` events. This prevents bad UX in situations where a plain @@ -115,6 +121,7 @@ blocks might have their own prefixing requirements. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[MSC4252]: https://github.com/matrix-org/matrix-spec-proposals/pull/4252 [sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations [server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search [`m.room.topic`]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic From c83f56db86f32845951e5dac5a794eda8bc6ad9c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 23 Jan 2025 12:50:30 +0000 Subject: [PATCH 21/21] Apply suggestions from code review Co-authored-by: Johannes Marbach --- proposals/3765-rich-room-topics.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index de63e4661ba..ed84737e2a6 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -25,11 +25,11 @@ events as shown below[^1]. "state_key": "", "content": { "m.topic": { - "m.text": [{ - "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" - }, { + "m.text": [ { "mimetype": "text/html", "body": "All about pizza | Recipes" + }, { + "body": "All about **pizza** | [Recipes](https://recipes.pizza.net)" }] }, "topic": "All about **pizza** | [Recipes](https://recipes.pizza.net)" @@ -38,16 +38,18 @@ events as shown below[^1]. } ``` -Details of how `m.text` works may be found in [MSC1767] and are not -repeated here. +In line with [MSC1767], clients should render the first mime type in the +array that they understand. Further details of how `m.text` works may +be found in [MSC1767] and are not repeated here. The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering -the topic as a room message. Note that while [MSC1767] had explicitly -excluded state events from being treated as extensible, this is being -changed with [MSC4252]. The extra content block, therefore, allows putting +the topic as a room message. ([MSC1767] specifies that unknown events with +an `m.text` content block should be rendered as a regular room message, and +while [MSC1767] had explicitly excluded state events from being treated as +extensible, this is being changed with [MSC4252].) The extra content block, therefore, allows putting a fallback representation that is actually designated for the timeline -into a separate `content['m.text']` field. Lastly, the `m.topic` content +into a separate `content['m.text']` field. In addition, the `m.topic` content block also serves as a good place for additional fields to be added by other MSCs in the future. @@ -112,15 +114,13 @@ for unsafe HTML. ## Unstable prefix While this MSC is not considered stable, `m.topic` should be referred to -as `org.matrix.msc3765.topic`. Note that extensible events and content -blocks might have their own prefixing requirements. +as `org.matrix.msc3765.topic`. [^1]: A future MSC may discuss how to adopt the `m.topic` content block in new room versions which support extensible events. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 -[MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 [MSC4252]: https://github.com/matrix-org/matrix-spec-proposals/pull/4252 [sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations [server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search