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

api/client-server/create_room.yaml

@@ -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
+                  The server will clobber the following keys: ``creator``, ``room_version``.
-                  versions of the specification may allow the server to clobber
+                  Future versions of the specification may allow the server to clobber
                   other keys.
               initial_state:
                 type: array

api/server-server/joins.yaml

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

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

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

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