Merge c94b54dab1 into 4ed55a60ec

changelogs/client_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2144.clarification

@@ -1 +0,0 @@
-Fix typo: as->has.

changelogs/server_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

content/application-service-api.md

@@ -492,10 +492,10 @@ via the query string). It is expected that the application service use
 the transactions pushed to it to handle events rather than syncing with
 the user implied by `sender_localpart`.
 
-#### Published room directories
+#### Application service room directories
 
-Application services can maintain their own published room directories for
+Application services can maintain their own room directories for their
-their defined third-party protocols. These directories may be accessed by
+defined third-party protocols. These room directories may be accessed by
 clients through additional parameters on the `/publicRooms`
 client-server endpoint.
 

content/client-server-api/_index.md

@@ -2846,35 +2846,7 @@ re-invited.
 
 {{% http-api spec="client-server" api="banning" %}}
 
-### Published room directory
+### Listing rooms
-
-Homeservers MAY publish a room directory to allow users to discover rooms. A room
-can have one of two visibility settings in the directory:
-
--   `public`: The room will be shown in the published room directory.
--   `private`: The room will be hidden from the published room directory.
-
-Clients can define a room's initial visibility in the directory via the `visibility`
-parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room
-creation, clients can query and change a room's visibility in the directory through
-the endpoints listed below, provided that the server permits this.
-
-{{% boxes/warning %}}
-The visibility setting merely defines whether a room is included in the published
-room directory or not. It doesn't make any guarantees about the room's
-[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility).
-
-In particular, a visibility setting of `public` should not be confused with a `public`
-join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published
-in the directory, too.
-
-Similarly, a visibility setting of `public` does not necessarily imply a `world_readable`
-history visibility.
-
-To increase performance or by preference, servers MAY apply additional filters when listing the
-directory, for instance, by automatically excluding rooms with `invite` join rules
-that are not `world_readable` regardless of their visibility.
-{{% /boxes/warning %}}
 
 {{% http-api spec="client-server" api="list_public_rooms" %}}
 

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

@@ -528,7 +528,7 @@ messages, Alice only sends one request event (an event with type
 `m.room.message` with `msgtype: m.key.verification.request`, rather than an
 event with type `m.key.verification.request`), to the room. In addition, Alice
 does not send an `m.key.verification.cancel` event to tell Bob's other devices
-that the request has already been accepted; instead, when Bob's other devices
+that the request as already been accepted; instead, when Bob's other devices
 see his `m.key.verification.ready` event, they will know that the request has
 already been accepted, and that they should ignore the request.
 

content/server-server-api.md

@@ -1048,10 +1048,11 @@ user's Matrix ID and the token delivered when the invite was stored,
 this verification will prove that the `m.room.member` invite event comes
 from the user owning the invited third-party identifier.
 
-## Published Room Directory
+## Public Room Directory
 
-To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory), 
+To complement the [Client-Server
-homeservers need a way to query the published rooms of another server.
+API](/client-server-api)'s room directory,
+homeservers need a way to query the public rooms for another server.
 This can be done by making a request to the `/publicRooms` endpoint for
 the server the room directory should be retrieved for.
 

data/api/client-server/appservice_room_directory.yaml

@@ -13,21 +13,18 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Application Service Published Room Directory API
+  title: Matrix Client-Server Application Service Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: |-
+      summary: Updates a room's visibility in the application service's room directory.
-        Updates a room's visibility in the application service's published room
-        directory.
       description: |-
-        Updates the visibility of a given room in the application service's
+        Updates the visibility of a given room on the application service's room
-        published room directory.
+        directory.
 
-        This API is similar to the
+        This API is similar to the room directory visibility API used by clients
-        [visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
+        to update the homeserver's more general room directory.
-        used by clients to update the homeserver's more general published room directory.
 
         This API requires the use of an application service access token (`as_token`)
         instead of a typical client's access_token. This API cannot be invoked by

data/api/client-server/create_room.yaml

@@ -87,9 +87,12 @@ paths:
                     - public
                     - private
                   description: |-
-                    The room's visibility in the server's
+                    A `public` visibility indicates that the room will be shown
-                    [published room directory](/client-server-api#published-room-directory).
+                    in the published room list. A `private` visibility will hide
-                    Defaults to `private`.
+                    the room from the published room list. Rooms default to
+                    `private` visibility if this key is not included. NB: This
+                    should not be confused with `join_rules` which also uses the
+                    word `public`.
                 room_alias_name:
                   type: string
                   description: |-

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 type: object
-title: "PublishedRoomsChunk"
+title: "PublicRoomsChunk"
 properties:
   canonical_alias:
     type: string

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

@@ -13,15 +13,28 @@
 # limitations under the License.
 
 type: object
-description: A list of the published rooms on the server.
+description: A list of the rooms on the server.
 required: ["chunk"]
 properties:
   chunk:
     type: array
     description: |-
-      A paginated chunk of published rooms.
+      A paginated chunk of public rooms.
     items:
-      $ref: "public_rooms_chunk.yaml"
+      allOf:
+        - $ref: "public_rooms_chunk.yaml"
+        - type: object
+          title: PublicRoomsChunk
+          properties:
+            # Override description of join_rule
+            join_rule:
+              type: string
+              description: |-
+                The room's join rule. When not present, the room is assumed to
+                be `public`. Note that rooms with `invite` join rules are not
+                expected here, but rooms with `knock` rules are given their
+                near-public nature.
+              example: "public"
   next_batch:
     type: string
     description: |-
@@ -37,7 +50,7 @@ properties:
   total_room_count_estimate:
     type: integer
     description: |-
-        An estimate on the total number of published rooms, if the
+        An estimate on the total number of public rooms, if the
         server has an estimate.
 example: {
   "chunk": [

data/api/client-server/list_public_rooms.yaml

@@ -13,15 +13,14 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Client-Server Published Room Directory API
+  title: Matrix Client-Server Room Directory API
   version: 1.0.0
 paths:
   "/directory/list/room/{roomId}":
     get:
       summary: Gets the visibility of a room in the directory
-      description: |-
+      description: Gets the visibility of a given room on the server's public room
-        Gets the visibility of a given room in the server's
+        directory.
-        published room directory.
       operationId: getRoomVisibilityOnDirectory
       parameters:
         - in: path
@@ -33,7 +32,7 @@ paths:
             type: string
       responses:
         "200":
-          description: The visibility of the room in the directory.
+          description: The visibility of the room in the directory
           content:
             application/json:
               schema:
@@ -51,7 +50,7 @@ paths:
                     "visibility": "public"
                   }
         "404":
-          description: The room is not known to the server.
+          description: The room is not known to the server
           content:
             application/json:
               schema:
@@ -65,13 +64,14 @@ paths:
       tags:
         - Room discovery
     put:
-      summary: Sets the visibility of a room in the directory
+      summary: Sets the visibility of a room in the room directory
       description: |-
-        Sets the visibility of a given room in the server's published room directory.
+        Sets the visibility of a given room in the server's public room
+        directory.
 
-        Servers MAY implement additional access control checks, for instance,
+        Servers may choose to implement additional access control checks
-        to ensure that a room's visibility can only be changed by the room creator
+        here, for instance that room visibility can only be changed by
-        or a server administrator.
+        the room creator or a server administrator.
       operationId: setRoomVisibilityOnDirectory
       security:
         - accessTokenQuery: []
@@ -97,11 +97,11 @@ paths:
                     - public
                   description: |-
                     The new visibility setting for the room.
-                    Defaults to `public`.
+                    Defaults to 'public'.
               example: {
                 "visibility": "public"
               }
-        description: The new visibility for the room in the published room directory.
+        description: The new visibility for the room on the room directory.
         required: true
       responses:
         "200":
@@ -114,7 +114,7 @@ paths:
                 response:
                   value: {}
         "404":
-          description: The room is not known to the server.
+          description: The room is not known to the server
           content:
             application/json:
               schema:
@@ -129,9 +129,9 @@ paths:
         - Room discovery
   /publicRooms:
     get:
-      summary: Lists a server's published room directory
+      summary: Lists the public rooms on the server.
       description: |-
-        Lists a server's published room directory.
+        Lists the public rooms on the server.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -154,13 +154,13 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the published room directory from. Defaults
+            The server to fetch the public room lists from. Defaults to the
-            to the local server. Case sensitive.
+            local server. Case sensitive.
           schema:
             type: string
       responses:
         "200":
-          description: A list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:
@@ -168,9 +168,9 @@ paths:
       tags:
         - Room discovery
     post:
-      summary: Lists a server's published room directory with an optional filter
+      summary: Lists the public rooms on the server with optional filter.
       description: |-
-        Lists a server's published room directory with an optional filter.
+        Lists the public rooms on the server, with optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
@@ -182,8 +182,8 @@ paths:
         - in: query
           name: server
           description: |-
-            The server to fetch the published room directory from. Defaults
+            The server to fetch the public room lists from. Defaults to the
-            to the local server. Case sensitive.
+            local server. Case sensitive.
           schema:
             type: string
       requestBody:
@@ -253,7 +253,7 @@ paths:
         required: true
       responses:
         "200":
-          description: A filtered list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:

data/api/server-server/public_rooms.yaml

@@ -13,20 +13,16 @@
 # limitations under the License.
 openapi: 3.1.0
 info:
-  title: Matrix Federation Published Room Directory API
+  title: Matrix Federation Public Rooms API
   version: 1.0.0
 paths:
   /publicRooms:
     get:
-      summary: Lists the server's published room directory
+      summary: Get all the public rooms for a homeserver
       description: |-
-        Lists the server's published room directory.
+        Gets all the public rooms for the homeserver. This should not return
-
+        rooms that are listed on another homeserver's directory, just those
-        This API returns paginated responses. The rooms are ordered by the number
+        listed on the receiving homeserver's directory.
-        of joined members, with the largest rooms first.
-
-        This SHOULD not return rooms that are listed on another homeserver's directory,
-        just those listed on the receiving homeserver's directory.
       operationId: getPublicRooms
       security:
         - signedRequest: []
@@ -66,18 +62,21 @@ paths:
             type: string
       responses:
         "200":
-          description: A list of the published rooms on the server.
+          description: The public room list for the homeserver.
           content:
             application/json:
               schema:
                 $ref: ../client-server/definitions/public_rooms_response.yaml
     post:
-      summary: Lists the server's published room directory with an optional filter
+      summary: Gets the public rooms on the server with optional filter.
       description: |-
-        Lists the server's published room directory with an optional filter.
+        Lists the public rooms on the server, with optional filter.
 
         This API returns paginated responses. The rooms are ordered by the number
         of joined members, with the largest rooms first.
+
+        Note that this endpoint receives and returns the same format that is seen
+        in the Client-Server API's `POST /publicRooms` endpoint.
       operationId: queryPublicRooms
       security:
         - signedRequest: []
@@ -148,11 +147,69 @@ paths:
         required: true
       responses:
         "200":
-          description: A filtered list of the published rooms on the server.
+          description: A list of the rooms on the server.
           content:
             application/json:
               schema:
-                $ref: ../client-server/definitions/public_rooms_response.yaml
+                type: object
+                description: A list of the rooms on the server.
+                required:
+                  - chunk
+                properties:
+                  chunk:
+                    title: PublicRoomsChunks
+                    type: array
+                    description: A paginated chunk of public rooms.
+                    items:
+                      allOf:
+                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
+                        - type: object
+                          properties:
+                            # Override description of join_rule
+                            join_rule:
+                              type: string
+                              description: |-
+                                The room's join rule. When not present, the room is assumed to
+                                be `public`. Note that rooms with `invite` join rules are not
+                                expected here, but rooms with `knock` rules are given their
+                                near-public nature.
+                  next_batch:
+                    type: string
+                    description: |-
+                      A pagination token for the response. The absence of this token
+                      means there are no more results to fetch and the client should
+                      stop paginating.
+                  prev_batch:
+                    type: string
+                    description: |-
+                      A pagination token that allows fetching previous results. The
+                      absence of this token means there are no results before this
+                      batch, i.e. this is the first batch.
+                  total_room_count_estimate:
+                    type: integer
+                    description: |-
+                      An estimate on the total number of public rooms, if the
+                      server has an estimate.
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
+                        "guest_can_join": false,
+                        "name": "CHEESE",
+                        "num_joined_members": 37,
+                        "room_id": "!ol19s:bleecker.street",
+                        "topic": "Tasty tasty cheese",
+                        "world_readable": true,
+                        "join_rule": "public",
+                        "room_type": "m.space"
+                      }
+                    ],
+                    "next_batch": "p190q",
+                    "prev_batch": "p1902",
+                    "total_room_count_estimate": 115
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables: