matrix-spec-proposals/content/rooms/_index.md

---
title: Room Versions
type: docs
weight: 60
---

Rooms are central to how Matrix operates, and have strict rules for what
is allowed to be contained within them. Rooms can also have various
algorithms that handle different tasks, such as what to do when two or
more events collide in the underlying DAG. To allow rooms to be improved
upon through new algorithms or rules, "room versions" are employed to
manage a set of expectations for each room. New room versions are
assigned as needed.

There is no implicit ordering or hierarchy to room versions, and their
principles are immutable once placed in the specification. Although
there is a recommended set of versions, some rooms may benefit from
features introduced by other versions. Rooms move between different
versions by "upgrading" to the desired version. Due to versions not
being ordered or hierarchical, this means a room can "upgrade" from
version 2 to version 1, if it is so desired.

## Feature matrix

Some functionality is only available in specific room versions, such
as knocking. The table below shows which versions support which features
from a client's perspective. Server implementations are still welcome
to reference the following table, however the detailed per-version
specifications are more likely to be of interest.

<!--
Dev note: When the room version columns get overwhelming, merge versions
1 through 6 as "1 ... 6" or similar given they don't add any features.

Alternatively, consider flipping the column/row organization to be features
up top and versions on the left.
-->

| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|-------------------|---|---|---|---|---|---|---|
| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |

## Complete list of room versions

Room versions are divided into two distinct groups: stable and unstable.
Stable room versions may be used by rooms safely. Unstable room versions
are everything else which is either not listed in the specification or
flagged as unstable for some other reason. Versions can switch between
stable and unstable periodically for a variety of reasons, including
discovered security vulnerabilities and age.

Clients should not ask room administrators to upgrade their rooms if the
room is running a stable version. Servers SHOULD use **room version 6** as
the default room version when creating new rooms.

The available room versions are:

-   [Version 1](/rooms/v1) - **Stable**. The current version of most
    rooms.
-   [Version 2](/rooms/v2) - **Stable**. Implements State Resolution
    Version 2.
-   [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs
    are the event's hash.
-   [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using
    URL-safe base64 for event IDs.
-   [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
    signing key validity periods.
-   [Version 6](/rooms/v6) - **Stable**. Alters several
    authorization rules for events.
-   [Version 7](/rooms/v7) - **Stable**. Introduces knocking.

## Room version grammar

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