Improvements to CS API "User Data" section (#2359)

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

changelogs/client_server/newsfragments/2359.clarification

@@ -0,0 +1 @@
+Clarify formats of string types.

content/client-server-api/_index.md

@@ -4214,13 +4214,13 @@ an automatic propagation event to occur, informing likely-interested
 parties of the new values. This change is conveyed using two separate
 mechanisms:
 
--   an `m.room.member` event (with a `join` membership) is sent to every
+-   an [`m.room.member`](#mroommember) event (with a `join` membership) is sent
-    room the user is a member of, to update the `displayname` and
+    to every room the user is a member of, to update the `displayname` and
     `avatar_url`.
--   an `m.presence` presence status update is sent, again containing the
+-   an [`m.presence`](#mpresence) presence status update is sent, again
-    new values of the `displayname` and `avatar_url` keys, in addition
+    containing the new values of the `displayname` and `avatar_url` keys, in
-    to the required `presence` key containing the current presence state
+    addition to the required `presence` key containing the current presence
-    of the user.
+    state of the user.
 
 Both of these should be done automatically by the homeserver when a user
 successfully changes their display name or avatar URL fields.

data/api/client-server/profile.yaml

@@ -46,6 +46,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to set. This MUST be either
@@ -69,11 +71,11 @@ paths:
               description: |
                 An object which contains exactly one property. The key
                 of that property MUST match the `keyName` specified in the URL.
-                
+
-                For `avatar_url`, the value MUST be an MXC URI string. 
+                For `avatar_url`, the value MUST be an MXC URI string.
-                
+
                 For `displayname`, the value MUST be a string.
-                
+
                 For `m.tz`, the value MUST be a valid identifier from the  [IANA Time Zone Database](https://www.iana.org/time-zones).
                 Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
                 values.
@@ -96,7 +98,7 @@ paths:
           description: |
             The input was invalid in some way. This can include one
             of the following error codes:
-            
+
             - `M_BAD_JSON`: The provided value is not valid JSON.
             - `M_MISSING_PARAM`: The required `keyName` property is
               missing from the request body.
@@ -158,6 +160,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to retrieve.
@@ -216,6 +220,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: keyName
           description: The name of the profile field to delete.
@@ -286,6 +292,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
       responses:
         "200":
           description: The profile information for this user.

data/api/client-server/users.yaml

@@ -30,7 +30,7 @@ paths:
             `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.
 
@@ -82,6 +82,8 @@ paths:
                           type: string
                           example: "@foo:bar.com"
                           description: The user's matrix user ID.
+                          format: mx-user-id
+                          pattern: "^@"
                         display_name:
                           type: string
                           example: Foo