Merge d9d14dcfe2 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/2348.clarification

@@ -0,0 +1 @@
+Fix ordering of common error codes.

changelogs/client_server/newsfragments/2349.clarification

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

changelogs/server_server/newsfragments/2334.clarification

@@ -0,0 +1 @@
+Clarify that server ACLs are case-insensitive.

content/client-server-api/_index.md

@@ -126,6 +126,25 @@ state (e.g.: sending messages, account data, etc) and not routes which
 only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
 [`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
 
+`M_UNKNOWN`
+: An unknown error has occurred.
+
+`M_UNKNOWN_DEVICE`
+: {{% added-in v="1.17" %}} The device ID supplied by the application service does
+not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
+
+`M_UNKNOWN_TOKEN`
+: The access or refresh token specified was not recognised.
+
+: An additional response parameter, `soft_logout`, might be present on the
+response for 401 HTTP status codes. See [the soft logout
+section](#soft-logout) for more information.
+
+`M_UNRECOGNIZED`
+: The server did not understand the request. This is expected to be returned with
+a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
+code if the endpoint is implemented, but the incorrect HTTP method is used.
+
 `M_USER_LIMIT_EXCEEDED`
 : {{% added-in v="1.18" %}} The request cannot be completed because the user has
 exceeded (or the request would cause them to exceed) a limit associated with
@@ -157,25 +176,6 @@ limit is a hard limit that cannot be increased.
   }
   ```
 
-`M_UNKNOWN`
-: An unknown error has occurred.
-
-`M_UNKNOWN_DEVICE`
-: {{% added-in v="1.17" %}} The device ID supplied by the application service does
-not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
-
-`M_UNKNOWN_TOKEN`
-: The access or refresh token specified was not recognised.
-
-: An additional response parameter, `soft_logout`, might be present on the
-response for 401 HTTP status codes. See [the soft logout
-section](#soft-logout) for more information.
-
-`M_UNRECOGNIZED`
-: The server did not understand the request. This is expected to be returned with
-a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
-code if the endpoint is implemented, but the incorrect HTTP method is used.
-
 `M_USER_LOCKED`
 : The account has been [locked](#account-locking) and cannot be used at this time.
 
@@ -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 %}}

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.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/event-schemas/schema/m.room.server_acl.yaml

@@ -62,8 +62,9 @@ properties:
       allow:
         type: array
         description: |-
-          The server names to allow in the room, excluding any port information.
-          Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching).
+          The case-insensitive [glob expressions](/appendices#glob-style-matching) that are
+          evaluated against server names excluding any port information to determine the servers
+          to allow in the room.
 
           **This defaults to an empty list when not provided, effectively disallowing
           every server.**
@@ -72,8 +73,9 @@ properties:
       deny:
         type: array
         description: |-
-          The server names to disallow in the room, excluding any port information.
-          Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching).
+          The case-insensitive [glob expressions](/appendices#glob-style-matching) that are
+          evaluated against server names excluding any port information to determine the servers
+          to disallow in the room.
 
           This defaults to an empty list when not provided.
         items:

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