Merge 0c557fe49c into 486a8f8764

* 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>

changelogs/client_server/newsfragments/2347.clarification

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

changelogs/client_server/newsfragments/2349.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).
@@ -3347,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
@@ -3367,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:
@@ -3387,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
@@ -3410,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 %}}

content/client-server-api/modules/end_to_end_encryption.md

@@ -1483,7 +1483,7 @@ potential new key backup algorithm version that would fix this issue.
 
 {{% added-in v="1.19" %}}
 
-This module enables clients to track a user's preference about enabling or
+This enables clients to track a user's preference about enabling or
 disabling [server-side backups of room keys](#server-side-key-backups). The data
 is stored in the [`m.key_backup`](#mkey_backup) global
 [account data](#client-config).

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/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/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/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.

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

data/api/client-server/room_initial_sync.yaml

@@ -27,6 +27,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The current state of the room
@@ -38,6 +40,8 @@ paths:
                 properties:
                   room_id:
                     type: string
+                    format: mx-room-id
+                    pattern: "^!"
                     description: The ID of this room.
                   membership:
                     type: string

data/api/client-server/room_send.yaml

@@ -49,6 +49,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of event to send.
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
                 required:
                   - event_id

data/api/client-server/room_state.yaml

@@ -49,6 +49,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of event to send.
@@ -86,6 +88,8 @@ paths:
                 properties:
                   event_id:
                     type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
                     description: A unique identifier for the event.
                 required:
                   - event_id

data/api/client-server/rooms.yaml

@@ -34,6 +34,8 @@ paths:
           example: "!636q39766251:matrix.org"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventId
           description: The event ID to get.
@@ -41,6 +43,8 @@ paths:
           example: $asfDuShaf7Gafaw:matrix.org
           schema:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
       responses:
         "200":
           description: The full event.
@@ -89,6 +93,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: path
           name: eventType
           description: The type of state to look up.
@@ -158,6 +164,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       responses:
         "200":
           description: The current state of the room
@@ -211,6 +219,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
         - in: query
           name: at
           description: |-
@@ -305,6 +315,8 @@ paths:
           example: "!636q39766251:example.com"
           schema:
             type: string
+            format: mx-room-id
+            pattern: "^!"
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []

data/api/client-server/sync.yaml

@@ -209,6 +209,8 @@ paths:
                                       field may be omitted.
                                     items:
                                       type: string
+                                      format: mx-user-id
+                                      pattern: "^@"
                                   m.joined_member_count:
                                     type: integer
                                     description: |-

data/event-schemas/schema/components/signed_third_party_invite.yaml

@@ -20,10 +20,13 @@ properties:
       The signatures are calculated using the process described at
       [Signing JSON](/appendices/#signing-json).
     type: object
-    additionalProperties:
-      type: object
-      additionalProperties:
-        type: string
+    patternProperties:
+      "":
+        x-pattern-format: mx-server-name
+        type: object
+        additionalProperties:
+          type: string
+          format: mx-unpadded-base64
     example: {
       "magic.forest": {
         "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"

data/event-schemas/schema/core-event-schema/room_event.yaml

@@ -11,5 +11,7 @@ allOf:
         The ID of the room associated with this event. Will not be present on events
         that arrive through `/sync`, despite being required everywhere else.
       type: string
+      format: mx-room-id
+      pattern: "^!"
   required:
   - room_id

data/event-schemas/schema/core-event-schema/stripped_state.yaml

@@ -39,6 +39,8 @@ properties:
   sender:
     description: The `sender` for the event.
     type: string
+    format: mx-user-id
+    pattern: "^@"
 required:
   - type
   - state_key

data/event-schemas/schema/core-event-schema/sync_room_event.yaml

@@ -29,9 +29,13 @@ allOf:
     event_id:
       description: The globally unique event identifier.
       type: string
+      format: mx-event-id
+      pattern: "^\\$"
     sender:
       description: Contains the fully-qualified ID of the user who sent this event.
       type: string
+      format: mx-user-id
+      pattern: "^@"
     origin_server_ts:
       description: Timestamp in milliseconds on originating homeserver
         when this event was sent.

data/event-schemas/schema/m.key_backup.yaml

@@ -1,25 +1,24 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "title": "Key Backup Event",
-  "description": "Allows clients to track user preferences about key backup.",
-  "allOf": [{
-    "$ref": "core-event-schema/event.yaml"
-  }],
-  "properties": {
-    "type": {
-      "type": "string",
-      "enum": ["m.key_backup"]
-    },
-    "content": {
-      "type": "object",
-      "properties": {
-        "enabled": {
-          "description": "True if the user chose to enable key backup. False if the user chose to disable key backup.",
-          "type": "boolean",
-        }
-      },
-      "required": ["enabled"]
-    }
-  },
-}
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  Allows clients to track user preferences about key backup.
+properties:
+  content:
+    type: object
+    properties:
+      enabled:
+        type: boolean
+        description: |-
+          True if the user chose to enable key backup. False if the user chose
+          to disable key backup.
+    required:
+      - enabled
+  type:
+    type: string
+    enum:
+      - m.key_backup
+title: Key Backup Event
+type: object

data/event-schemas/schema/m.room.canonical_alias.yaml

@@ -16,6 +16,8 @@ properties:
           The canonical alias for the room. If not present, null, or empty the
           room should be considered to have no canonical alias.
         type: string
+        format: mx-room-alias
+        pattern: "^#"
       alt_aliases:
         description: |
           Alternative aliases the room advertises. This list can have aliases
@@ -23,6 +25,8 @@ properties:
         type: array
         items:
           type: string
+          format: mx-room-alias
+          pattern: "^#"
     type: object
   state_key:
     description: A zero-length string.

data/event-schemas/schema/m.room.create.yaml

@@ -12,6 +12,8 @@ properties:
           The `user_id` of the room creator. **Required** for, and only present in, room versions 1 - 10. Starting with
           room version 11 the event `sender` should be used instead.
         type: string
+        format: mx-user-id
+        pattern: "^@"
       m.federate:
         description: Whether users on other servers can join this room. Defaults to `true` if key does not exist.
         type: boolean
@@ -32,9 +34,13 @@ properties:
         properties:
           room_id:
             type: string
+            format: mx-room-id
+            pattern: "^!"
             description: The ID of the old room.
           event_id:
             type: string
+            format: mx-event-id
+            pattern: "^\\$"
             deprecated: true
             x-changedInMatrixVersion:
               "1.16": |-
@@ -51,6 +57,8 @@ properties:
         type: array
         items:
           type: string
+          format: mx-user-id
+          pattern: "^@"
           description: Additional user ID to consider a creator of the room, if supported by the room version.
         x-addedInMatrixVersion: "1.16"
         description: |-

data/event-schemas/schema/m.room.join_rules.yaml

@@ -55,6 +55,8 @@ properties:
               enum: ['m.room_membership']
             room_id:
               type: string
+              format: mx-room-id
+              pattern: "^!"
               description: |-
                 Required if `type` is `m.room_membership`. The room ID to check the
                 user's membership against. If the user is joined to this room, they

data/event-schemas/schema/m.room.member.yaml

@@ -76,6 +76,8 @@ properties:
       join_authorised_via_users_server:
         x-addedInMatrixVersion: "1.2"
         type: string
+        format: mx-user-id
+        pattern: "^@"
         description: |-
           Usually found on `join` events, this field is used to denote which homeserver (through
           representation of a user with sufficient power level) authorised the user's join. More
@@ -127,6 +129,8 @@ properties:
       `join`, the user ID sending the event does not need to match the user ID in the `state_key`,
       unlike other events. Regular authorisation rules still apply.
     type: string
+    format: mx-user-id
+    pattern: "^@"
   type:
     enum:
       - m.room.member

data/event-schemas/schema/m.room.redaction.yaml

@@ -10,6 +10,8 @@ properties:
       redacts:
         description: The event ID that was redacted. Required for, and present starting in, room version 11.
         type: string
+        format: mx-event-id
+        pattern: "^\\$"
       reason:
         description: 'The reason for the redaction, if any.'
         type: string
@@ -17,6 +19,8 @@ properties:
   redacts:
     description: Required for, and only present in, room versions 1 - 10. The event ID that was redacted.
     type: string
+    format: mx-event-id
+    pattern: "^\\$"
   type:
     enum:
       - m.room.redaction

data/string-formats.yaml

@@ -66,6 +66,11 @@ mx-mxc-uri:
   url: client-server-api#matrix-content-mxc-uris
   # regex: "^mxc:\\/\\/"
 
+mx-unpadded-base64:
+  title: Unpadded Base64
+  url: appendices#unpadded-base64
+  # no regex
+
 uri:
   title: URI
   url: https://datatracker.ietf.org/doc/html/rfc3986