diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index de63e4661..ed84737e2 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