mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-20 16:38:37 +01:00
f97d2944ae
Some checks failed
Spec / 🔎 Validate OpenAPI specifications (push) Has been cancelled
Spec / 🔎 Check Event schema examples (push) Has been cancelled
Spec / 🔎 Check OpenAPI definitions examples (push) Has been cancelled
Spec / 🔎 Check JSON Schemas inline examples (push) Has been cancelled
Spec / ⚙️ Calculate baseURL for later jobs (push) Has been cancelled
Spec / 📢 Run towncrier for changelog (push) Has been cancelled
Spell Check / Spell Check with Typos (push) Has been cancelled
Spec / 🐍 Build OpenAPI definitions (push) Has been cancelled
Spec / 📖 Build the spec (push) Has been cancelled
Spec / 🔎 Validate generated HTML (push) Has been cancelled
Spec / 📖 Build the historical backup spec (push) Has been cancelled
* Placeholder * i++ * Room version 12 Template out a v12 room version Make v12 default, per MSC4304 Update PDU checks and auth event selection per MSC4291 Describe new room_id format per MSC4291 Move v6 depth definition to a component for easier referencing Move room_id to a component to prep for v12, per MSC4291 Create and use a new room_id component for v12+ per MSC4291 Reflect auth events selection change onto all room versions per MSC4291 The MSC asks the `description` of `auth_events` to be adjusted, however this feels like a better representation of the change. Add `room_id` format rules and renumber per MSC4291 Reflect change to rule 1.2 per MSC4291 Insert same room_id check to v1-12 auth rules per MSC4307 and MSC4291 Deprecate `predecessor.event_id` per MSC4291 Insert auth rule to validate `additional_creators` per MSC4289 Insert rule for `users` validation of creators and renumber per MSC4289 Define "room creator(s)" per MSC4289 Spec `additional_creators` on create events per MSC4289 Spec `additional_creators` on `/upgrade` per MSC4289 The MSC doesn't mention how to handle unsupported room versions, but the Synapse implementation used for FCP ignores the field in such room versions. This feels like a good approach, and will need clarifying in the MSC too (if accepted at the spec level). Add notes to `/upgrade` behaviour per MSC4289 and MSC4291 Describe how additional creators work during room creation per MSC4289 Fix default user power level descriptions per MSC4289 Describe tombstone power level changes per MSC4289 Warn clients about event format changes in v12 per MSC4289 and MSC4291 Flag additional room creators support for client reference per MSC4289 Remove TODO now that it's fully addressed Copy state res into v12 as-is for modification Apply Modification 1 to SR2.1 per MSC4297 Apply Modification 2 to SR2.1 per MSC4297 Add summary box to the top of SR2.1 for ease of developer reference Modification 2 was split into items 2 and 3 for further ease of understanding. Add all the changelogs `x` is used until a real PR number can be assigned. Some changelogs are duplicated to the Client-Server API to increase visibility of the changes to v12. Review: Minor phrasing adjustments in changelogs Review: Clarify that v12 isn't quite the default yet in the changelog Review: Clarify to clients that creators are immutable Review: Improve 'how to parse a domain' advice for legacy apps Review: Add a bit more detail as to why a room ID might be required Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Clarify that clients can override the tombstone default Mention creatorship UI label by finishing the Permissions section We probably should have removed the WIP note in v1.0, but alas. Add changelog for tombstone changes Use assigned spec PR number in changelogs (cherry picked from commit ec81eea7e4532fd398b8013071d6981c97117d9e)
297 lines
13 KiB
YAML
297 lines
13 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
# Copyright 2018 New Vector Ltd
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
openapi: 3.1.0
|
|
info:
|
|
title: Matrix Client-Server Room Creation API
|
|
version: 1.0.0
|
|
paths:
|
|
/createRoom:
|
|
post:
|
|
summary: Create a new room
|
|
description: |-
|
|
Create a new room with various configuration options.
|
|
|
|
The server MUST apply the normal state resolution rules when creating
|
|
the new room, including checking power levels for each event. It MUST
|
|
apply the events implied by the request in the following order:
|
|
|
|
1. The `m.room.create` event itself. Must be the first event in the
|
|
room.
|
|
|
|
2. An `m.room.member` event for the creator to join the room. This is
|
|
needed so the remaining events can be sent.
|
|
|
|
3. A default `m.room.power_levels` event. Overridden by the
|
|
`power_level_content_override` parameter.
|
|
|
|
In [room versions](/rooms) 1 through 11, the room creator (and not
|
|
other members) will be given permission to send state events.
|
|
|
|
In room versions 12 and later, the room creator is given infinite
|
|
power level and cannot be specified in the `users` field of
|
|
`m.room.power_levels`, so is not listed explicitly.
|
|
|
|
**Note**: For `trusted_private_chat`, the users specified in the
|
|
`invite` parameter SHOULD also be appended to `additional_creators`
|
|
by the server, per the `creation_content` parameter.
|
|
|
|
If the room's version is 12 or higher, the power level for sending
|
|
`m.room.tombstone` events MUST explicitly be higher than `state_default`.
|
|
For example, set to 150 instead of 100.
|
|
|
|
4. An `m.room.canonical_alias` event if `room_alias_name` is given.
|
|
|
|
5. Events set by the `preset`. Currently these are the `m.room.join_rules`,
|
|
`m.room.history_visibility`, and `m.room.guest_access` state events.
|
|
|
|
6. Events listed in `initial_state`, in the order that they are
|
|
listed.
|
|
|
|
7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic`
|
|
state events).
|
|
|
|
8. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with
|
|
`membership: invite` and `m.room.third_party_invite`).
|
|
|
|
The available presets do the following with respect to room state:
|
|
|
|
| Preset | `join_rules` | `history_visibility` | `guest_access` | Other |
|
|
|------------------------|--------------|----------------------|----------------|-------|
|
|
| `private_chat` | `invite` | `shared` | `can_join` | |
|
|
| `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. |
|
|
| `public_chat` | `public` | `shared` | `forbidden` | |
|
|
|
|
The server will create a `m.room.create` event in the room with the
|
|
requesting user as the creator, alongside other keys provided in the
|
|
`creation_content` or implied by behaviour of `creation_content`.
|
|
operationId: createRoom
|
|
x-changedInMatrixVersion:
|
|
"1.16": Added server behaviour for how the initial power levels change depending on room version.
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"preset": "public_chat",
|
|
"room_alias_name": "thepub",
|
|
"name": "The Grand Duke Pub",
|
|
"topic": "All about happy hour",
|
|
"creation_content": {
|
|
"m.federate": false
|
|
}
|
|
}
|
|
properties:
|
|
visibility:
|
|
type: string
|
|
enum:
|
|
- public
|
|
- private
|
|
description: |-
|
|
The room's visibility in the server's
|
|
[published room directory](/client-server-api#published-room-directory).
|
|
Defaults to `private`.
|
|
room_alias_name:
|
|
type: string
|
|
description: |-
|
|
The desired room alias **local part**. If this is included, a
|
|
room alias will be created and mapped to the newly created
|
|
room. The alias will belong on the *same* homeserver which
|
|
created the room. For example, if this was set to "foo" and
|
|
sent to the homeserver "example.com" the complete room alias
|
|
would be `#foo:example.com`.
|
|
|
|
The complete room alias will become the canonical alias for
|
|
the room and an `m.room.canonical_alias` event will be sent
|
|
into the room.
|
|
name:
|
|
type: string
|
|
description: |-
|
|
If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
|
|
will be sent into the room to indicate the name for the room.
|
|
This overwrites any [`m.room.name`](/client-server-api/#mroomname)
|
|
event in `initial_state`.
|
|
topic:
|
|
type: string
|
|
description: |-
|
|
If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
|
|
event with a `text/plain` mimetype will be sent into the room
|
|
to indicate the topic for the room. This overwrites any
|
|
[`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
|
|
invite:
|
|
type: array
|
|
description: |-
|
|
A list of user IDs to invite to the room. This will tell the
|
|
server to invite everyone in the list to the newly created room.
|
|
items:
|
|
type: string
|
|
invite_3pid:
|
|
type: array
|
|
description: |-
|
|
A list of objects representing third-party IDs to invite into
|
|
the room.
|
|
items:
|
|
$ref: definitions/invite_3pid.yaml
|
|
room_version:
|
|
type: string
|
|
description: |-
|
|
The room version to set for the room. If not provided, the homeserver is
|
|
to use its configured default. If provided, the homeserver will return a
|
|
400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not
|
|
support the room version.
|
|
example: "1"
|
|
creation_content:
|
|
title: CreationContent
|
|
type: object
|
|
x-changedInMatrixVersion:
|
|
"1.16": Added server behaviour for how to handle `trusted_private_chat` and invited users.
|
|
description: |-
|
|
Extra keys, such as `m.federate`, to be added to the content
|
|
of the [`m.room.create`](/client-server-api/#mroomcreate) event.
|
|
|
|
The server will overwrite the following
|
|
keys: `creator`, `room_version`. Future versions of the specification
|
|
may allow the server to overwrite other keys.
|
|
|
|
When using the `trusted_private_chat` preset, the server SHOULD combine
|
|
`additional_creators` specified here and the `invite` array into the
|
|
eventual `m.room.create` event's `additional_creators`, deduplicating
|
|
between the two parameters.
|
|
initial_state:
|
|
type: array
|
|
description: |-
|
|
A list of state events to set in the new room. This allows
|
|
the user to override the default state events set in the new
|
|
room. The expected format of the state events are an object
|
|
with type, state_key and content keys set.
|
|
|
|
Takes precedence over events set by `preset`, but gets
|
|
overridden by `name` and `topic` keys.
|
|
items:
|
|
type: object
|
|
title: StateEvent
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: The type of event to send.
|
|
state_key:
|
|
type: string
|
|
description: The state_key of the state event. Defaults to an empty string.
|
|
content:
|
|
type: object
|
|
description: The content of the event.
|
|
required:
|
|
- type
|
|
- content
|
|
preset:
|
|
type: string
|
|
enum:
|
|
- private_chat
|
|
- public_chat
|
|
- trusted_private_chat
|
|
description: |-
|
|
Convenience parameter for setting various default state events
|
|
based on a preset.
|
|
|
|
If unspecified, the server should use the `visibility` to determine
|
|
which preset to use. A visibility of `public` equates to a preset of
|
|
`public_chat` and `private` visibility equates to a preset of
|
|
`private_chat`.
|
|
is_direct:
|
|
type: boolean
|
|
description: |-
|
|
This flag makes the server set the `is_direct` flag on the
|
|
`m.room.member` events sent to the users in `invite` and
|
|
`invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
|
|
power_level_content_override:
|
|
title: Power Level Event Content
|
|
type: object
|
|
description: |-
|
|
The power level content to override in the default power level
|
|
event. This object is applied on top of the generated
|
|
[`m.room.power_levels`](/client-server-api/#mroompower_levels)
|
|
event content prior to it being sent to the room. Defaults to
|
|
overriding nothing.
|
|
description: The desired room configuration.
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Information about the newly created room.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
description: Information about the newly created room.
|
|
properties:
|
|
room_id:
|
|
type: string
|
|
description: The created room's ID.
|
|
required:
|
|
- room_id
|
|
examples:
|
|
response:
|
|
value: {
|
|
"room_id": "!sefiuhWgwghwWgh:example.com"
|
|
}
|
|
"400":
|
|
description: |-
|
|
|
|
The request is invalid. A meaningful `errcode` and description
|
|
error text will be returned. Example reasons for rejection include:
|
|
|
|
- The request body is malformed (`errcode` set to `M_BAD_JSON`
|
|
or `M_NOT_JSON`).
|
|
|
|
- The room alias specified is already taken (`errcode` set to
|
|
`M_ROOM_IN_USE`).
|
|
|
|
- The initial state implied by the parameters to the request is
|
|
invalid: for example, the user's `power_level` is set below
|
|
that necessary to set the room name (`errcode` set to
|
|
`M_INVALID_ROOM_STATE`).
|
|
|
|
- The homeserver doesn't support the requested room version, or
|
|
one or more users being invited to the new room are residents
|
|
of a homeserver which does not support the requested room version.
|
|
The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these
|
|
cases.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
tags:
|
|
- Room creation
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8008
|
|
basePath:
|
|
default: /_matrix/client/v3
|
|
components:
|
|
securitySchemes:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|