Matrix Specification

Matrix defines a set of open APIs for decentralised communication, suitable for securely publishing, persisting and subscribing to data over a global open federation of servers with no single point of control. Uses include Instant Messaging (IM), Voice over IP (VoIP) signalling, Internet of Things (IoT) communication, and bridging together existing communication silos - providing the basis of a new open real-time communication ecosystem.

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

Matrix APIs

The specification consists of the following parts:

Introduction to Matrix provides a full introduction to Matrix and the spec.

API Version Description
Client-Server API unstable Interaction between clients and servers
Server-Server API unstable Federation between servers
Application Service API unstable Privileged server plugins
Identity Service API unstable Mapping of third party IDs to Matrix IDs
Push Gateway API unstable Push notifications for Matrix events

The Appendices contain supplemental information not specific to one of the above APIs.

Specification Versions

The specification for each API is versioned in the form rX.Y.Z.
  • A change to X reflects a breaking change: a client implemented against r1.0.0 may need changes to work with a server which supports (only) r2.0.0.
  • A change to Y represents a change which is backwards-compatible for existing clients, but not necessarily existing servers: a client implemented against r1.1.0 will work without changes against a server which supports r1.2.0; but a client which requires r1.2.0 may not work correctly with a server which implements only r1.1.0.
  • A change to Z represents a change which is backwards-compatible on both sides. Typically this implies a clarification to the specification, rather than a change which must be implemented.