Improvements to CS API "Rooms" section (#2358)

* Clarify string formats of rooms endpoints

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

* Use description list for room memberships

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

* Add changelog

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

* Add link to m.room.join_rules definition

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2358.clarification

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

content/client-server-api/_index.md

@@ -3936,28 +3936,28 @@ room to send events in the room:
 
 Some rooms require that users be invited to it before they can join;
 others allow anyone to join. Whether a given room is an "invite-only"
-room is determined by the room config key `m.room.join_rules`. It can
+room is determined by the room state event [`m.room.join_rules`](#mroomjoin_rules).
-have one of the following values:
+It can have one of the following values:
 
 `public`
-This room is free for anyone to join without an invite.
+: This room is free for anyone to join without an invite.
 
 `invite`
-This room can only be joined if you were invited.
+: This room can only be joined if you were invited.
 
 `knock`
-This room can only be joined if you were invited, and allows anyone to
+: This room can only be joined if you were invited, and allows anyone to
 request an invite to the room. Note that this join rule is only available
 in room versions [which support knocking](/rooms/#feature-matrix).
 
-{{% added-in v="1.2" %}} `restricted`
+`restricted`
-This room can be joined if you were invited or if you are a member of another
+: {{% added-in v="1.2" %}} This room can be joined if you were invited or if you are a member of another
 room listed in the join rules. If the server cannot verify membership for any
 of the listed rooms then you can only join with an invite. Note that this rule
 is only expected to work in room versions [which support it](/rooms/#feature-matrix).
 
-{{% added-in v="1.3" %}} `knock_restricted`
+`knock_restricted`
-This room can be joined as though it was `restricted` *or* `knock`. If you
+: {{% added-in v="1.3" %}} This room can be joined as though it was `restricted` *or* `knock`. If you
 interact with the room using knocking, the `knock` rule takes effect whereas
 trying to join the room without an invite applies the `restricted` join rule.
 Note that this rule is only expected to work in room versions

data/api/client-server/banning.yaml

@@ -37,6 +37,8 @@ paths:
           example: "!e42d8c:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -50,6 +52,8 @@ paths:
                 user_id:
                   type: string
                   description: The fully qualified user ID of the user being banned.
+                  format: mx-user-id
+                  pattern: "^@"
                 reason:
                   x-addedInMatrixVersion: "1.1"
                   type: string
@@ -108,6 +112,8 @@ paths:
           example: "!e42d8c:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -121,6 +127,8 @@ paths:
                 user_id:
                   type: string
                   description: The fully qualified user ID of the user being unbanned.
+                  format: mx-user-id
+                  pattern: "^@"
                 reason:
                   x-addedInMatrixVersion: "1.1"
                   type: string

data/api/client-server/create_room.yaml

@@ -140,6 +140,8 @@ paths:
                     server to invite everyone in the list to the newly created room.
                   items:
                     type: string
+                    format: mx-user-id
+                    pattern: "^@"
                 invite_3pid:
                   type: array
                   description: |-
@@ -241,6 +243,8 @@ paths:
                   room_id:
                     type: string
                     description: The created room's ID.
+                    format: mx-room-id
+                    pattern: "^!"
                 required:
                   - room_id
               examples:

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

@@ -20,10 +20,14 @@ properties:
   sender:
     type: string
     description: The Matrix ID of the user who issued the invite.
+    format: mx-user-id
+    pattern: "^@"
     example: "@alice:example.org"
   mxid:
     type: string
     description: The Matrix ID of the invitee.
+    format: mx-user-id
+    pattern: "^@"
     example: "@bob:example.org"
   token:
     type: string

data/api/client-server/directory.yaml

@@ -33,6 +33,8 @@ paths:
           example: "#monkeys:matrix.org"
           schema:
             type: string
+            format: mx-room-alias
+            pattern: "^#"
       requestBody:
         content:
           application/json:
@@ -42,6 +44,8 @@ paths:
                 room_id:
                   type: string
                   description: The room ID to set.
+                  format: mx-room-id
+                  pattern: "^!"
               required:
                 - room_id
               example: {
@@ -104,6 +108,8 @@ paths:
           example: "#monkeys:matrix.org"
           schema:
             type: string
+            format: mx-room-alias
+            pattern: "^#"
       responses:
         "200":
           description: The room ID and other information for this alias.
@@ -115,12 +121,15 @@ paths:
                   room_id:
                     type: string
                     description: The room ID for this room alias.
+                    format: mx-room-id
+                    pattern: "^!"
                   servers:
                     type: array
                     description: A list of servers that are aware of this room alias.
                     items:
                       type: string
                       description: A server which is aware of this room alias.
+                      format: mx-server-name
               examples:
                 response:
                   value: {
@@ -185,6 +194,8 @@ paths:
           example: "#monkeys:matrix.org"
           schema:
             type: string
+            format: mx-room-alias
+            pattern: "^#"
       responses:
         "200":
           description: The mapping was deleted.
@@ -241,6 +252,8 @@ paths:
           example: "!abc123:example.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The list of local aliases for the room.
@@ -254,6 +267,8 @@ paths:
                     description: The server's local aliases on the room. Can be empty.
                     items:
                       type: string
+                      format: mx-room-alias
+                      pattern: "^#"
                 required:
                   - aliases
               examples:

data/api/client-server/inviting.yaml

@@ -48,6 +48,8 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -61,6 +63,8 @@ paths:
                 user_id:
                   type: string
                   description: The fully qualified user ID of the invitee.
+                  format: mx-user-id
+                  pattern: "^@"
                 reason:
                   x-addedInMatrixVersion: "1.1"
                   type: string

data/api/client-server/joining.yaml

@@ -43,6 +43,8 @@ paths:
           example: "!d41d8cd:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -78,6 +80,8 @@ paths:
                   room_id:
                     type: string
                     description: The joined room ID.
+                    format: mx-room-id
+                    pattern: "^!"
                 required:
                   - room_id
               examples:
@@ -136,7 +140,13 @@ paths:
           required: true
           example: "#monkeys:matrix.org"
           schema:
-            type: string
+            oneOf:
+              - type: string
+                format: mx-room-id
+                pattern: "^!"
+              - type: string
+                format: mx-room-alias
+                pattern: "^#"
         - in: query
           name: via
           x-addedInMatrixVersion: "1.12"
@@ -150,6 +160,7 @@ paths:
             type: array
             items:
               type: string
+              format: mx-server-name
       requestBody:
         content:
           application/json:
@@ -185,6 +196,8 @@ paths:
                   room_id:
                     type: string
                     description: The joined room ID.
+                    format: mx-room-id
+                    pattern: "^!"
                 required:
                   - room_id
               examples:

data/api/client-server/kicking.yaml

@@ -39,6 +39,8 @@ paths:
           example: "!e42d8c:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -52,6 +54,8 @@ paths:
                 user_id:
                   type: string
                   description: The fully qualified user ID of the user being kicked.
+                  format: mx-user-id
+                  pattern: "^@"
                 reason:
                   type: string
                   description: |-

data/api/client-server/knocking.yaml

@@ -47,7 +47,13 @@ paths:
           required: true
           example: "#monkeys:matrix.org"
           schema:
-            type: string
+            oneOf:
+              - type: string
+                format: mx-room-id
+                pattern: "^!"
+              - type: string
+                format: mx-room-alias
+                pattern: "^#"
         - in: query
           name: via
           x-addedInMatrixVersion: "1.12"
@@ -61,6 +67,7 @@ paths:
             type: array
             items:
               type: string
+              format: mx-server-name
       requestBody:
         content:
           application/json:
@@ -88,6 +95,8 @@ paths:
                   room_id:
                     type: string
                     description: The knocked room ID.
+                    format: mx-room-id
+                    pattern: "^!"
                 required:
                   - room_id
               examples:

data/api/client-server/leaving.yaml

@@ -54,6 +54,8 @@ paths:
           example: "!nkl290a:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -113,6 +115,8 @@ paths:
           example: "!au1ba7o:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The room has been forgotten.

data/api/client-server/list_joined_rooms.yaml

@@ -39,6 +39,8 @@ paths:
                     description: The ID of each room in which the user has `joined` membership.
                     items:
                       type: string
+                      format: mx-room-id
+                      pattern: "^!"
               examples:
                 response:
                   value: {

data/api/client-server/list_public_rooms.yaml

@@ -31,6 +31,8 @@ paths:
           example: "!curbf:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The visibility of the room in the directory.
@@ -84,6 +86,8 @@ paths:
           example: "!curbf:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       requestBody:
         content:
           application/json:
@@ -158,6 +162,7 @@ paths:
             to the local server. Case sensitive.
           schema:
             type: string
+            format: mx-server-name
       responses:
         "200":
           description: A list of the published rooms on the server.
@@ -186,6 +191,7 @@ paths:
             to the local server. Case sensitive.
           schema:
             type: string
+            format: mx-server-name
       requestBody:
         content:
           application/json: