Specify how room versioning works

This is the spec PR for https://github.com/matrix-org/matrix-doc/issues/1425

Room version upgrades are not part of MSC1425.

Documented aspects:
* room_version on the create event
* creating a room with a specific version (useful for testing)
* make_join behaviour
* error code documentation
* grammar of room versions

Based upon https://docs.google.com/document/d/1urKgReoHqxX8R_XtySB17dPi-DZcKhqTEL2_s895Wz0/edit
pull/977/head
Travis Ralston 6 years ago
parent 669d526ea7
commit fde48e7ee8

@ -137,13 +137,21 @@ 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 to be added to the content of the ``m.room.create``.
The server will clobber the following keys: ``creator``. Future
versions of the specification may allow the server to clobber
The server will clobber the following keys: ``creator``, ``room_version``.
Future versions of the specification may allow the server to clobber
other keys.
initial_state:
type: array

@ -45,6 +45,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: |-
@ -138,6 +147,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

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

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

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

Loading…
Cancel
Save