Update MSC3765: Rich text in room topics

proposals/3765-rich-room-topics.md

@@ -44,33 +44,52 @@ 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
 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