Improvements to "Events" section (#2349)

* Clarify string formats of event endpoints and schemas

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

* Fix links to endpoints

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>

Author: zecakeh

changelogs/client_server/newsfragments/2349.clarification

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

content/client-server-api/_index.md

@@ -3348,8 +3348,8 @@ room at the start of the returned timeline. The response also includes a
 `next_batch` field, which should be used as the value of the `since`
 parameter in the next call to `/sync`. Finally, the response includes,
 for each room, a `prev_batch` field, which can be passed as a `from`/`to`
-parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier
-messages.
+parameter to the [`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
+API to retrieve earlier messages.
 
 For example, a `/sync` request might return a range of four events
 `E2`, `E3`, `E4` and `E5` within a given room, omitting two prior events
@@ -3368,7 +3368,8 @@ response to the previous call as the `since` parameter. The client
 should also pass a `timeout` parameter. The server will then hold open
 the HTTP connection for a short period of time waiting for new events,
 returning early if an event occurs. Only the `/sync` API (and the
-deprecated `/events` API) support long-polling in this way.
+deprecated [`/events`](#get_matrixclientv3events) API) support
+long-polling in this way.
 
 Continuing the example above, an incremental sync might report
 a single new event `E6`. The response can be visualised as:
@@ -3388,7 +3389,7 @@ containing only the most recent message events. A state "delta" is also
 returned, summarising any state changes in the omitted part of the
 timeline. The client may therefore end up with "gaps" in its knowledge
 of the message timeline. The client can fill these gaps using the
-[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API.
+[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages) API.
 
 Continuing our example, suppose we make a third `/sync` request asking for
 events since the last sync, by passing the `next_batch` token `x-y-z` as
@@ -3411,7 +3412,7 @@ The limited response includes a state delta which describes how the state
 of the room changes over the gap. This delta explains how to build the state
 prior to returned timeline (i.e. at `E7`) from the state the client knows
 (i.e. at `E6`). To close the gap, the client should make a request to
-[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
+[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
 with the query parameters `from=x-y-z` and `to=d-e-f`.
 
 {{% boxes/warning %}}

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

@@ -24,8 +24,9 @@ allOf:
       room_id:
         description: The ID of the room associated with this event.
         type: string
+        format: mx-room-id
+        pattern: "^!"
         example: '!jEsUZKDJdhlrceRyVU:example.org'
-
       unsigned:
         properties:
             redacted_because:
@@ -43,6 +44,6 @@ allOf:
                 "unsigned": {
                   "age": 1257,
                 }
-            }
+              }
     required:
       - room_id

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

@@ -28,6 +28,8 @@ properties:
   event_id:
     description: The globally unique identifier for this event.
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
     example: '$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45'
   type:
     description: The type of the event.
@@ -47,6 +49,8 @@ properties:
   sender:
     description: Contains the fully-qualified ID of the user who sent this event.
     type: string
+    format: mx-user-id
+    pattern: "^@"
     example: "@example:example.org"
   origin_server_ts:
     description: |-

data/api/client-server/definitions/m.relates_to.yaml

@@ -39,5 +39,7 @@ properties:
       such.
   event_id:
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
     description: The event ID of the event that this event relates to.
 required: ['rel_type', 'event_id']

data/api/client-server/message_pagination.yaml

@@ -37,6 +37,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: from
           x-changedInMatrixVersion:

data/api/client-server/old_sync.yaml

@@ -148,6 +148,8 @@ paths:
                       properties:
                         room_id:
                           type: string
+                          format: mx-room-id
+                          pattern: "^!"
                           description: The ID of this room.
                         membership:
                           type: string
@@ -337,6 +339,8 @@ paths:
           example: $asfDuShaf7Gafaw:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
       responses:
         "200":
           description: The full event.

data/api/client-server/redaction.yaml

@@ -43,13 +43,17 @@ paths:
           example: "!637q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventId
-          description: The ID of the event to redact
+          description: The ID of the event to redact.
           required: true
-          example: bai2b1i9:matrix.org
+          example: $bai2b1i9:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
         - in: path
           name: txnId
           description: |-
@@ -82,6 +86,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
               examples:
                 response:

data/api/client-server/relations.yaml

@@ -233,6 +233,8 @@ components:
       example: "!636q39766251:matrix.org"
       schema:
         type: string
+        format: mx-room-id
+        pattern: "^!"
     eventId:
       in: path
       name: eventId
@@ -241,6 +243,8 @@ components:
       example: $asfDuShaf7Gafaw
       schema:
         type: string
+        format: mx-event-id
+        pattern: "^\\$"
     from:
       in: query
       name: from

data/api/client-server/room_event_by_timestamp.yaml

@@ -56,6 +56,8 @@ paths:
           example: "!636q39766251:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: ts
           description: |-
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: The ID of the event found
                   origin_server_ts:
                     type: integer