Improvements to "Filtering" section (#2347)

* Clarify string format of filtering endpoints.

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

* Use inline code for endpoints and add link to /members definition

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

* Add changelog

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

---------

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

changelogs/client_server/newsfragments/2347.clarification

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

content/client-server-api/_index.md

@@ -3120,19 +3120,20 @@ events they have already been sent, and choose to skip sending membership
 events for members whose membership has not changed. These are called
 'redundant membership events'. Clients may request that redundant membership
 events are always included in responses by setting `include_redundant_members`
-to true in the filter.
+to `true` in the filter.
 
 The expected pattern for using lazy-loading is currently:
 
--   Client performs an initial /sync with lazy-loading enabled, and
+-   Client performs an initial `/sync` with lazy-loading enabled, and
     receives only the membership events which relate to the senders of
     the events it receives.
 -   Clients which support display-name tab-completion or other
     operations which require rapid access to all members in a room
-    should call /members for the currently selected room, with an `?at`
-    parameter set to the /sync response's from token. The member list
-    for the room is then maintained by the state in subsequent
-    incremental /sync responses.
+    should call [`/members`](#get_matrixclientv3roomsroomidmembers) for
+    the currently selected room, with an `?at` parameter set to the
+    `/sync` response's `from` token. The member list for the room is
+    then maintained by the state in subsequent incremental `/sync`
+    responses.
 -   Clients which do not support tab-completion may instead pull in
     profiles for arbitrary users (e.g. read receipts, typing
     notifications) on demand by querying the room state or [`/profile`](#get_matrixclientv3profileuserid).

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

@@ -26,6 +26,8 @@ properties:
       `senders` filter.
     items:
       type: string
+      format: mx-user-id
+      pattern: "^@"
     type: array
   not_types:
     description: A list of event types to exclude. If this list is absent then no
@@ -40,6 +42,8 @@ properties:
       senders are included.
     items:
       type: string
+      format: mx-user-id
+      pattern: "^@"
     type: array
   types:
     description: A list of event types to include. If this list is absent then all

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

@@ -43,12 +43,16 @@ allOf:
         filter.
       items:
         type: string
+        format: mx-room-id
+        pattern: "^!"
       type: array
     rooms:
       description: A list of room IDs to include. If this list is absent then all rooms
         are included.
       items:
         type: string
+        format: mx-room-id
+        pattern: "^!"
       type: array
     contains_url:
       type: boolean

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

@@ -50,6 +50,8 @@ properties:
           `state`, `timeline` or `account_data`
         items:
           type: string
+          format: mx-room-id
+          pattern: "^!"
         type: array
       rooms:
         description: A list of room IDs to include. If this list is absent then all rooms
@@ -57,6 +59,8 @@ properties:
           `state`, `timeline` or `account_data`
         items:
           type: string
+          format: mx-room-id
+          pattern: "^!"
         type: array
       ephemeral:
         allOf:

data/api/client-server/filter.yaml

@@ -36,6 +36,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
       requestBody:
         content:
           application/json:
@@ -130,6 +132,8 @@ paths:
           example: "@alice:example.com"
           schema:
             type: string
+            format: mx-user-id
+            pattern: "^@"
         - in: path
           name: filterId
           description: The filter ID to download.