diff --git a/api/client-server/users.yaml b/api/client-server/users.yaml
index ff24967a..cecf9424 100644
--- a/api/client-server/users.yaml
+++ b/api/client-server/users.yaml
@@ -75,17 +75,20 @@ paths:
                 items:
                   title: User
                   type: object
-                  require: ["user_id"]
+                  required: ["user_id"]
                   properties:
                     user_id:
                       type: string
                       example: "@foo:bar.com"
+                      description: The MXID of the user.
                     display_name:
                       type: string
                       example: "Foo"
+                      description: The display name of the user, if one exists.
                     avatar_url:
                       type: string
                       example: "mxc://bar.com/foo"
+                      description: The avatar url, as an MXC, if one exists.
               limited:
                 type: boolean
                 description: Indicates if the result list has been truncated by the limit.
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index 2586041d..e40aa6f1 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -1336,14 +1336,17 @@ Listing rooms
 {{list_public_rooms_cs_http_api}}
 
 
-Users
------
+User Data
+---------
+
+User Directory
+~~~~~~~~~~~~~~
 
 {{users_cs_http_api}}
 
 
 Profiles
---------
+~~~~~~~~
 
 {{profile_cs_http_api}}