Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-05-01 22:54:10 +02:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Improvements to CS API "Rooms" section (#2358)
Some checks are pending
Spec / 🔎 Validate OpenAPI specifications (push) Waiting to run
Details
Spec / 🔎 Check Event schema examples (push) Waiting to run
Details
Spec / 🔎 Check OpenAPI definitions examples (push) Waiting to run
Details
Spec / 🔎 Check JSON Schemas inline examples (push) Waiting to run
Details
Spec / ⚙️ Calculate baseURL for later jobs (push) Waiting to run
Details
Spec / 🐍 Build OpenAPI definitions (push) Blocked by required conditions
Details
Spec / 📢 Run towncrier for changelog (push) Waiting to run
Details
Spec / 📖 Build the spec (push) Blocked by required conditions
Details
Spec / 🔎 Validate generated HTML (push) Blocked by required conditions
Details
Spec / 📖 Build the historical backup spec (push) Blocked by required conditions
Details
Spec / Create release (push) Blocked by required conditions
Details
Spell Check / Spell Check with Typos (push) Waiting to run
Details

Browse source 
* Clarify string formats of rooms endpoints

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

* Use description list for room memberships

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

* Add changelog

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

* Add link to m.room.join_rules definition

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
This commit is contained in:
Kévin Commaille 2026-05-01 07:49:59 +02:00 committed by GitHub
parent 9fd3c00086
commit 160339e580
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 85 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2358.clarification Normal file
View file

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

18
content/client-server-api/_index.md
View file

@ -3936,28 +3936,28 @@ room to send events in the room:
Some rooms require that users be invited to it before they can join;
others allow anyone to join. Whether a given room is an "invite-only"
room is determined by the room config key `m.room.join_rules`. It can
have one of the following values:
room is determined by the room state event [`m.room.join_rules`](#mroomjoin_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

8
data/api/client-server/banning.yaml
View file

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

4
data/api/client-server/create_room.yaml
View file

@ -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:

4
data/api/client-server/definitions/third_party_signed.yaml
View file

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

15
data/api/client-server/directory.yaml
View file

@ -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:

4
data/api/client-server/inviting.yaml
View file

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

15
data/api/client-server/joining.yaml
View file

@ -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:

4
data/api/client-server/kicking.yaml
View file

@ -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: |-

11
data/api/client-server/knocking.yaml
View file

@ -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:

4
data/api/client-server/leaving.yaml
View file

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

2
data/api/client-server/list_joined_rooms.yaml
View file

@ -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: {

6
data/api/client-server/list_public_rooms.yaml
View file

@ -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: