Merge 7f0431b95f into c39c7d0680

* Fix sync example

The same event should not appear in `state` and in the `timeline` so we cannot use the same event twice.

To provide a `state` example we assume that with lazy-loading the user did not get the state event for `@example:example.org`, so we add one since they sent a message in the timeline.

The events that are referenced include a `room_id`, which doesn't appear on this endpoint, so we copy them without it.

Finally, the `join` event of `@alice:example.org` is wrong because the sender does not match the state key, which wouldn't pass the authorization rules.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Fix the `m.room.member.yaml` example

This is a `join` event, and the `sender` doesn't match the `state_key`, so the event couldn't pass the authorization rules.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2077.clarification

@@ -0,0 +1 @@
+Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

changelogs/client_server/newsfragments/2095.feature

@@ -0,0 +1 @@
+Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/server_server/newsfragments/2095.feature

@@ -0,0 +1 @@
+Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

content/client-server-api/modules/search.md

@@ -26,9 +26,10 @@ on certain keys of certain event types.
 
 The supported keys to search over are:
 
--   `content.body` in `m.room.message`
--   `content.name` in `m.room.name`
--   `content.topic` in `m.room.topic`
+-   `content.body` in [`m.room.message`](#mroommessage)
+-   `content.name` in [`m.room.name`](#mroomname)
+-   `content.topic` as well as the `body` of the `text/plain` representation
+     in [`m.room.topic`](#mroomtopic)
 
 The search will *not* include rooms that are end to end encrypted.
 

data/api/client-server/create_room.yaml

@@ -109,15 +109,17 @@ paths:
                 name:
                   type: string
                   description: |-
-                    If this is included, an `m.room.name` event will be sent
-                    into the room to indicate the name of the room. See Room
-                    Events for more information on `m.room.name`.
+                    If this is included, an [`m.room.name`](#mroomname) event
+                    will be sent into the room to indicate the name for the room.
+                    This overwrites any [`m.room.name`](#mroomname) event in
+                    `initial_state`.
                 topic:
                   type: string
                   description: |-
-                    If this is included, an `m.room.topic` event will be sent
-                    into the room to indicate the topic for the room. See Room
-                    Events for more information on `m.room.topic`.
+                    If this is included, an [`m.room.topic`](#mroomtopic) event
+                    with a `text/plain` mimetype will be sent into the room to
+                    indicate the topic for the room. This overwrites any
+                    [`m.room.topic`](#mroomtopic) event in `initial_state`.
                 invite:
                   type: array
                   description: |-

data/api/client-server/definitions/public_rooms_chunk.yaml

@@ -33,7 +33,9 @@ properties:
     example: "!abcdefg:example.org"
   topic:
     type: string
-    description: The topic of the room, if any.
+    description: |-
+      The plaintext topic of the room. Omitted if no `text/plain` mimetype
+      exists in [`m.room.topic`](/client-server-api/#mroomtopic).
     example: "All things general"
   world_readable:
     type: boolean

data/api/client-server/sync.yaml

@@ -441,17 +441,57 @@ paths:
                           "state": {
                             "events": [
                               {
-                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
+                                  "displayname": "Example user",
+                                  "membership": "join"
+                                },
+                                "event_id": "$143273976499sgjks:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "state_key": "@example:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 45603,
+                                  "membership": "join"
+                                }
                               }
                             ]
                           },
                           "timeline": {
                             "events": [
                               {
-                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
+                                  "displayname": "Alice Margatroid",
+                                  "membership": "join",
+                                  "reason": "Looking for support"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@alice:example.org",
+                                "state_key": "@alice:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
                               },
                               {
-                                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                                "content": {
+                                  "body": "This is an example text message",
+                                  "format": "org.matrix.custom.html",
+                                  "formatted_body": "<b>This is an example text message</b>",
+                                  "msgtype": "m.text"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "type": "m.room.message",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
                               }
                             ],
                             "limited": true,

data/event-schemas/examples/m.room.member.yaml

@@ -1,6 +1,7 @@
 {
   "$ref": "core/state_event.json",
   "state_key": "@alice:example.org",
+  "sender": "@alice:example.org",
   "type": "m.room.member",
   "content": {
     "membership": "join",

data/event-schemas/examples/m.room.topic.yaml

@@ -3,6 +3,14 @@
   "type": "m.room.topic",
   "state_key": "",
   "content": {
-    "topic": "A room topic"
+    "m.topic": {
+      "m.text": [ {
+        "mimetype": "text/html",
+        "body": "An <em>interesting</em> room topic"
+      }, {
+        "body": "An interesting room topic"
+      }]
+    },
+    "topic": "An interesting room topic"
   }
 }

data/event-schemas/schema/components/m_text_content_block.yaml

@@ -0,0 +1,28 @@
+type: array
+description: |-
+  An ordered array of textual representations in different mimetypes.
+
+  Senders SHOULD specify at least one representation and SHOULD always
+  include a plaintext representation.
+  
+  Receivers SHOULD use the first representation in the array that
+  they understand.
+title: TextContentBlock
+items:
+  type: object
+  title: TextualRepresentation
+  properties:
+    mimetype:
+      type: string
+      description: The mimetype. Defaults to `text/plain` if omitted.
+      example: "text/html"
+    body:
+      type: string
+      description: |-
+        The string content.
+
+        Clients SHOULD validate and sanitize the content as they do
+        for rich content associated with [`msgtype`](#mroommessage-msgtypes)
+        of [`m.room.message`](#mroommessage).
+  required:
+  - body

data/event-schemas/schema/m.room.topic.yaml

@@ -1,13 +1,38 @@
 ---
 allOf:
   - $ref: core-event-schema/state_event.yaml
-description: 'A topic is a short message detailing what is currently being discussed in the room.  It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
+description: |-
+  A topic is a short message detailing what is currently being discussed
+  in the room.  It can also be used as a way to display extra information
+  about the room, which may not be suitable for the room name. The room
+  topic can be set when creating a room using
+  [`/createRoom`](client-server-api/#post_matrixclientv3createroom), either
+  with the `topic` key or by specifying a full event in `initial_state`.
+  
+  In order to prevent formatting abuse in room topics, clients SHOULD
+  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).
 properties:
   content:
     properties:
       topic:
-        description: The topic text.
+        description: |-
+          The topic in plain text.
+
+          This SHOULD duplicate the content of the `text/plain`
+          representation in `m.topic` if any exists.
         type: string
+      m.topic:
+        type: object
+        title: TopicContentBlock
+        x-addedInMatrixVersion: "1.15"
+        description: |-
+          Textual representation of the room topic in different mimetypes.
+        properties:
+          m.text:
+            $ref: components/m_text_content_block.yaml
     required:
       - topic
     type: object