Merge 5bac209ac3 into 65b1db721d

We seem to have [updated this for m.room.name](https://github.com/matrix-org/matrix-spec/pull/1639) some years back but omitted it for topic.

changelogs/client_server/newsfragments/2068.clarification

@@ -0,0 +1 @@
+Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

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/2102.clarification

@@ -0,0 +1 @@
+"Public" rooms in user directory queries are defined through their join rule and history visibility.

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/api/client-server/users.yaml

@@ -20,10 +20,17 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        Performs a search for users. The homeserver may
+        Performs a search for users. The homeserver may determine which
-        determine which subset of users are searched, however the homeserver
+        subset of users are searched. However, the homeserver MUST at a
-        MUST at a minimum consider the users the requesting user shares a
+        minimum consider users who are visible to the requester based
-        room with and those who reside in public rooms (known to the homeserver).
+        on their membership in rooms known to the homeserver. This means:
+
+        -   users that share a room with the requesting user
+        -   users who are joined to rooms known to the homeserver that have a
+            `public` [join rule](#mroomjoin_rules)
+        -   users who are joined to rooms known to the homeserver that have a
+            `world_readable` [history visibility](#room-history-visibility)
+        
         The search MUST consider local users to the homeserver, and SHOULD
         query remote users as part of the search.
 

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/schema/m.room.topic.yaml

@@ -1,7 +1,14 @@
 ---
 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 also be set when creating a room using `/createRoom` with the `topic` key.'
+    
+    If the `topic` property is absent, null, or empty then the topic is unset. In other words,
+    an empty `topic` property effectively resets the room to having no topic.
 properties:
   content:
     properties: