MSC3765: Rich text in room topics

proposals/3765-rich-room-topics.md

@@ -0,0 +1,97 @@
+# MSC3765: 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 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.
+
+## 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 <b>pizza</b> | <a href=\"https://recipes.pizza.net\">Recipes</a>"
+        }, {
+            "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.msc3765.
+
+-   `m.topic` should be referred to as `org.matrix.msc3765.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