diff --git a/changelogs/client_server/newsfragments/2358.clarification b/changelogs/client_server/newsfragments/2358.clarification new file mode 100644 index 00000000..bdcce777 --- /dev/null +++ b/changelogs/client_server/newsfragments/2358.clarification @@ -0,0 +1 @@ +Clarify formats of string types. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b74a0ee2..0f436751 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -3940,24 +3940,24 @@ room is determined by the room config key `m.room.join_rules`. It can have one of the following values: `public` -This room is free for anyone to join without an invite. +: This room is free for anyone to join without an invite. `invite` -This room can only be joined if you were invited. +: This room can only be joined if you were invited. `knock` -This room can only be joined if you were invited, and allows anyone to +: This room can only be joined if you were invited, and allows anyone to request an invite to the room. Note that this join rule is only available in room versions [which support knocking](/rooms/#feature-matrix). -{{% added-in v="1.2" %}} `restricted` -This room can be joined if you were invited or if you are a member of another +`restricted` +: {{% added-in v="1.2" %}} This room can be joined if you were invited or if you are a member of another room listed in the join rules. If the server cannot verify membership for any of the listed rooms then you can only join with an invite. Note that this rule is only expected to work in room versions [which support it](/rooms/#feature-matrix). -{{% added-in v="1.3" %}} `knock_restricted` -This room can be joined as though it was `restricted` *or* `knock`. If you +`knock_restricted` +: {{% added-in v="1.3" %}} This room can be joined as though it was `restricted` *or* `knock`. If you interact with the room using knocking, the `knock` rule takes effect whereas trying to join the room without an invite applies the `restricted` join rule. Note that this rule is only expected to work in room versions 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: