1.1   Matrix versions

Matrix 1.0 (released June 10th, 2019) consists of the following minimum API versions:

2.1   Spec Change Proposals

To propose a change to the Matrix Spec, see the explanations at Proposals for Spec Changes to Matrix.

3.1   Users

Each client is associated with a user account, which is identified in Matrix using a unique "user ID". This ID is namespaced to the homeserver which allocated the account and has the form:

@localpart:domain

See 'Identifier Grammar' in the appendices for full details of the structure of user IDs.

3.2   Devices

The Matrix specification has a particular meaning for the term "device". As a user, I might have several devices: a desktop client, some web browsers, an Android device, an iPhone, etc. They broadly relate to a real device in the physical world, but you might have several browsers on a physical device, or several Matrix client applications on a mobile device, each of which would be its own device.

Devices are used primarily to manage the keys used for end-to-end encryption (each device gets its own copy of the decryption keys), but they also help users manage their access - for instance, by revoking access to particular devices.

When a user first uses a client, it registers itself as a new device. The longevity of devices might depend on the type of client. A web client will probably drop all of its state on logout, and create a new device every time you log in, to ensure that cryptography keys are not leaked to a new user. In a mobile client, it might be acceptable to reuse the device if a login session expires, provided the user is the same.

Devices are identified by a device_id, which is unique within the scope of a given user.

A user may assign a human-readable display name to a device, to help them manage their devices.

3.3   Events

All data exchanged over Matrix is expressed as an "event". Typically each client action (e.g. sending a message) correlates with exactly one event. Each event has a type which is used to differentiate different kinds of data. type values MUST be uniquely globally namespaced following Java's package naming conventions, e.g. com.example.myapp.event. The special top-level namespace m. is reserved for events defined in the Matrix specification - for instance m.room.message is the event type for instant messages. Events are usually sent in the context of a "Room".

3.4   Event Graphs

Events exchanged in the context of a room are stored in a directed acyclic graph (DAG) called an "event graph". The partial ordering of this graph gives the chronological ordering of events within the room. Each event in the graph has a list of zero or more "parent" events, which refer to any preceding events which have no chronological successor from the perspective of the homeserver which created the event.

Typically an event has a single parent: the most recent message in the room at the point it was sent. However, homeservers may legitimately race with each other when sending messages, resulting in a single event having multiple successors. The next event added to the graph thus will have multiple parents. Every event graph has a single root event with no parent.

To order and ease chronological comparison between the events within the graph, homeservers maintain a depth metadata field on each event. An event's depth is a positive integer that is strictly greater than the depths of any of its parents. The root event should have a depth of 1. Thus if one event is before another, then it must have a strictly smaller depth.

3.5   Room structure

A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event. Rooms are uniquely identified internally via "Room IDs", which have the form:

!opaque_id:domain

There is exactly one room ID for each room. Whilst the room ID does contain a domain, it is simply for globally namespacing room IDs. The room does NOT reside on the domain specified.

See 'Identifier Grammar' in the appendices for full details of the structure of a room ID.

The following conceptual diagram shows an m.room.message event being sent to the room !qporfwt:matrix.org:

 { @alice:matrix.org }                             { @bob:example.org }
         |                                                 ^
         |                                                 |
[HTTP POST]                                  [HTTP GET]
Room ID: !qporfwt:matrix.org                 Room ID: !qporfwt:matrix.org
Event type: m.room.message                   Event type: m.room.message
Content: { JSON object }                     Content: { JSON object }
         |                                                 |
         V                                                 |
 +------------------+                          +------------------+
 |   homeserver     |                          |   homeserver     |
 |   matrix.org     |                          |   example.org    |
 +------------------+                          +------------------+
         |                                                 ^
         |         [HTTP PUT]                              |
         |         Room ID: !qporfwt:matrix.org            |
         |         Event type: m.room.message              |
         |         Content: { JSON object }                |
         `-------> Pointer to the preceding message  ------`
                   PKI signature from matrix.org
                   Transaction-layer metadata
                   PKI Authorization header

               ....................................
              |           Shared Data              |
              | State:                             |
              |   Room ID: !qporfwt:matrix.org     |
              |   Servers: matrix.org, example.org |
              |   Members:                         |
              |    - @alice:matrix.org             |
              |    - @bob:example.org              |
              | Messages:                          |
              |   - @alice:matrix.org              |
              |     Content: { JSON object }       |
              |....................................|

Federation maintains shared data structures per-room between multiple homeservers. The data is split into message events and state events.

Message events:

These describe transient 'once-off' activity in a room such as an instant messages, VoIP call setups, file transfers, etc. They generally describe communication activity.

State events:

These describe updates to a given piece of persistent information ('state') related to a room, such as the room's name, topic, membership, participating servers, etc. State is modelled as a lookup table of key/value pairs per room, with each key being a tuple of state_key and event type. Each state event updates the value of a given key.

The state of the room at a given point is calculated by considering all events preceding and including a given event in the graph. Where events describe the same state, a merge conflict algorithm is applied. The state resolution algorithm is transitive and does not depend on server state, as it must consistently select the same event irrespective of the server or the order the events were received in. Events are signed by the originating server (the signature includes the parent relations, type, depth and payload hash) and are pushed over federation to the participating servers in a room, currently using full mesh topology. Servers may also request backfill of events over federation from the other servers participating in a room.

#room_alias:domain

     HTTP GET
#matrix:example.org      !aaabaa:matrix.org
        |                    ^
        |                    |
 _______V____________________|____
|          example.org           |
| Mappings:                      |
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|

3.6   Identity

Users in Matrix are identified via their Matrix user ID. However, existing 3rd party ID namespaces can also be used in order to identify Matrix users. A Matrix "Identity" describes both the user ID and any other existing IDs from third party namespaces linked to their account. Matrix users can link third-party IDs (3PIDs) such as email addresses, social network accounts and phone numbers to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the user IDs of their contacts. In order to ensure that the mapping from 3PID to user ID is genuine, a globally federated cluster of trusted "identity servers" (IS) are used to verify the 3PID and persist and replicate the mappings.

Usage of an IS is not required in order for a client application to be part of the Matrix ecosystem. However, without one clients will not be able to look up user IDs using 3PIDs.

3.7   Profiles

Users may publish arbitrary key/value data associated with their account - such as a human readable display name, a profile photo URL, contact information (email address, phone numbers, website URLs etc).

3.8   Private User Data

Users may also store arbitrary private key/value data in their account - such as client preferences, or server configuration settings which lack any other dedicated API. The API is symmetrical to managing Profile data.

4.1   Namespacing

Namespacing helps prevent conflicts between multiple applications and the specification itself. Where namespacing is used, m. prefixes are used by the specification to indicate that the field is controlled by the specification. Custom or non-specified namespaces used in the wild MUST use the Java package naming convention to prevent conflicts.

As an example, event types defined in the specification are namespaced under the special m. prefix, however any client can send a custom event type, such as com.example.game.score (assuming the client has rights to the com.example namespace) without needing to put the event into the m. namespace.

4.2   Timestamps

Unless otherwise stated, timestamps are measured as milliseconds since the Unix epoch. Throughout the specification this may be referred to as POSIX, Unix, or just "time in milliseconds".

5.1   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

5.2   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 5 as the default room version when creating new rooms.

The available room versions are:

• Version 1 - Stable. The current version of most rooms.
• Version 2 - Stable. Implements State Resolution Version 2.
• Version 3 - Stable. Introduces events whose IDs are the event's hash.
• Version 4 - Stable. Builds on v3 by using URL-safe base64 for event IDs.
• Version 5 - Stable. Introduces enforcement of signing key validity periods.
• Version 6 - Stable. Alters several authorization rules for events.