From cbbbeeedfce2374a26a881ecb1f56e3d7654d376 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 22 Apr 2026 12:02:59 +0200 Subject: [PATCH] Clarify string formats of rooms endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/banning.yaml | 8 ++++++++ data/api/client-server/create_room.yaml | 4 ++++ .../definitions/third_party_signed.yaml | 4 ++++ data/api/client-server/directory.yaml | 15 +++++++++++++++ data/api/client-server/inviting.yaml | 4 ++++ data/api/client-server/joining.yaml | 15 ++++++++++++++- data/api/client-server/kicking.yaml | 4 ++++ data/api/client-server/knocking.yaml | 11 ++++++++++- data/api/client-server/leaving.yaml | 4 ++++ data/api/client-server/list_joined_rooms.yaml | 2 ++ data/api/client-server/list_public_rooms.yaml | 6 ++++++ 11 files changed, 75 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml index 3cb9a540..d57f7c34 100644 --- a/data/api/client-server/banning.yaml +++ b/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 diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 2abe963f..99bf7375 100644 --- a/data/api/client-server/create_room.yaml +++ b/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: diff --git a/data/api/client-server/definitions/third_party_signed.yaml b/data/api/client-server/definitions/third_party_signed.yaml index 071d9491..6522b58a 100644 --- a/data/api/client-server/definitions/third_party_signed.yaml +++ b/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 diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index f5c357d9..e0e92b56 100644 --- a/data/api/client-server/directory.yaml +++ b/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: diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 89e3e08e..6a2f69f4 100644 --- a/data/api/client-server/inviting.yaml +++ b/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 diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 8ba488e4..aabbbb07 100644 --- a/data/api/client-server/joining.yaml +++ b/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: diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml index eb5b02d2..6b2c1af1 100644 --- a/data/api/client-server/kicking.yaml +++ b/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: |- diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 06b93ddf..b0dbe934 100644 --- a/data/api/client-server/knocking.yaml +++ b/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: diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index edb8ffd3..a3351e2d 100644 --- a/data/api/client-server/leaving.yaml +++ b/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. diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml index cec458c8..1c24e122 100644 --- a/data/api/client-server/list_joined_rooms.yaml +++ b/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: { diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index c3e54403..c3f0280f 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/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: