diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index f9aec5197cb..ac0c3b162e1 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -147,14 +147,22 @@ paths: type: string description: The invitee's third party identifier. required: ["id_server", "medium", "address"] + 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 description: |- Extra keys, such as ``m.federate``, to be added to the content of the `m.room.create`_ event. The server will clobber the following - keys: ``creator``. Future versions of the specification may allow - the server to clobber other keys. + keys: ``creator``, ``room_version``. Future versions of the specification + may allow the server to clobber other keys. initial_state: type: array description: |- diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index e76a0aa60a4..4902ea9e12a 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -49,6 +49,15 @@ paths: description: The user ID the join event will be for. required: true x-example: "@someone:example.org" + - in: query + type: array + items: + type: string + name: ver + description: |- + The room versions the sending server has support for. Defaults + to ``[1]``. + x-example: ["1", "2"] responses: 200: description: |- @@ -142,6 +151,30 @@ paths: ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}] ] } + 400: + description: |- + The request is invalid or the room the server is attempting + to join has a version that is not listed in the ``ver`` + parameters. + + The error should be passed through to clients so that they + may give better feedback to users. + schema: + allOf: + - $ref: "../client-server/definitions/errors/error.yaml" + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the ``errcode`` + is ``M_INCOMPATIBLE_ROOM_VERSION``. + examples: + application/json: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server diff --git a/changelogs/client_server/newsfragments/1516.feature b/changelogs/client_server/newsfragments/1516.feature new file mode 100644 index 00000000000..8e9b26df3bc --- /dev/null +++ b/changelogs/client_server/newsfragments/1516.feature @@ -0,0 +1 @@ +Add support for Room Versions. diff --git a/event-schemas/schema/m.room.create b/event-schemas/schema/m.room.create index a07ab90fcd4..d12b9ccd708 100644 --- a/event-schemas/schema/m.room.create +++ b/event-schemas/schema/m.room.create @@ -11,6 +11,9 @@ properties: m.federate: description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist. type: boolean + room_version: + description: The version of the room. Defaults to ``"1"`` if the key does not exist. + type: string required: - creator type: object diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 7156c7d5774..fc89f031ba5 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -41,6 +41,37 @@ Examples of valid server names are: * ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port) +Room Versions +~~~~~~~~~~~~~ + +Room versions are used to change properties of rooms that may not be compatible +with other servers. For example, changing the rules for event authorization would +cause older servers to potentially end up in a split-brain situation due to them +not understanding the new rules. + +A room version is defined as a string of characters which MUST NOT exceed 32 +codepoints in length. Room versions MUST NOT be empty and SHOULD contain only +the characters ``a-z``, ``0-9``, ``.``, and ``-``. + +Room versions are not intended to be parsed and should be treated as opaque +identifiers. Room versions consisting only of the characters ``0-9`` and ``.`` +are reserved for future versions of the Matrix protocol. + +The complete grammar for a legal room version is:: + + room_version = 1*room_version_char + room_version_char = DIGIT + / %x61-7A ; a-z + / "-" / "." + +Examples of valid room versions are: + +* ``1`` (would be reserved by the Matrix protocol) +* ``1.2`` (would be reserved by the Matrix protocol) +* ``1.2-beta`` +* ``com.example.version`` + + Common Identifier Format ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 7cd14f7f5f2..71c6009759c 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -148,6 +148,13 @@ Some requests have unique error codes: :``M_SERVER_NOT_TRUSTED``: The client's request used a third party server, eg. ID server, that this server does not trust. +:``M_UNSUPPORTED_ROOM_VERSION``: + The client's request to create a room used a room version that the server does not support. + +:``M_INCOMPATIBLE_ROOM_VERSION``: + The client attempted to join a room that has a version the server does not support. Inspect the + ``room_version`` property of the error response for the room's version. + .. _sect:txn_ids: The client-server API typically uses ``HTTP PUT`` to submit requests with a