diff --git a/proposals/3677-rich-room-topics.md b/proposals/3677-rich-room-topics.md new file mode 100644 index 000000000..db6688701 --- /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