Clarify the homeserver's behaviour for user searching

api/client-server/users.yaml

@@ -31,8 +31,16 @@ paths:
     post:
       summary: Searches the user directory.
       description: |-
-        This API performs a server-side search over all users registered on the server.
-        It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
+        Performs a search for users on the homeserver. The homeserver may
+        determine which subset of users are searched, however the homeserver
+        MUST at a minimum consider the users the requesting user shares a
+        room with and those who reside in public rooms (known to the homeserver).
+        The search MUST consider local users to the homeserver, and SHOULD
+        query remote users as part of the search.
+
+        The search is performed case-insensitively on user IDs and display
+        names preferably using a collation determined based upon the 
+        ``Accept-Language`` header provided in the request, if present.
       operationId: searchUserDirectory
       security:
         - accessToken: []
@@ -48,23 +56,23 @@ paths:
                 example: "foo"
               limit:
                 type: integer
-                description: The maximum number of results to return (Defaults to 10).
+                description: The maximum number of results to return. Defaults to 10.
                 example: 10
             required: ["search_term"]
       responses:
         200:
           description: The results of the search.
           examples:
             application/json: {
-                  "results": [
-                    {
-                      "user_id": "@foo:bar.com",
-                      "display_name": "Foo",
-                      "avatar_url": "mxc://bar.com/foo"
-                    }
-                  ],
-                  "limited": false
-              }
+              "results": [
+                {
+                  "user_id": "@foo:bar.com",
+                  "display_name": "Foo",
+                  "avatar_url": "mxc://bar.com/foo"
+                }
+              ],
+              "limited": false
+            }
           schema:
             type: object
             required: ["results", "limited"]

changelogs/client_server/newsfragments/1569.clarification

@@ -0,0 +1 @@
+Clarify the homeserver's behaviour for searching users.