The Matrix protocol specification
Go to file
Johannes Marbach c8eb7f5526
Document the removal changelog category (#1907)
* Document the removal changelog category

Signed-off-by: Johannes Marbach <>

* Add changelog


Signed-off-by: Johannes Marbach <>
2024-07-16 18:15:44 -04:00
.github Update release documentation (Q2 2024 edition) (#1759) 2024-06-20 04:08:20 +00:00
assets Arrange rows in .basic-info tables vertically when horizontal space is constrained (#1771) 2024-04-09 13:31:46 +00:00
attic Add a hyphen between third and party when used as an adjective (#1447) 2023-03-08 09:58:29 +00:00
changelogs Document the removal changelog category (#1907) 2024-07-16 18:15:44 -04:00
content Spec for MSC2867 (Marking rooms as unread) (#1895) 2024-07-15 14:38:57 +01:00
data Spec for MSC2867 (Marking rooms as unread) (#1895) 2024-07-15 14:38:57 +01:00
data-definitions Update data-definitions 2023-08-22 12:04:56 -06:00
informal Update (#1140) 2022-06-30 15:58:22 -06:00
layouts Fix ToC of spec proposals (#1885) 2024-06-20 16:20:16 +00:00
meta Fix the table of content for room versions (#1884) 2024-06-20 15:47:09 +00:00
packages/npm Create @matrix-org/spec npm package containing sas-emoji.json (#1620) 2023-08-18 09:56:55 -06:00
scripts Upgrade CI scripts dependencies (#1786) 2024-04-16 17:59:12 +01:00
static Generate ToC with Hugo rather than JavaScript (#1851) 2024-06-11 22:24:23 +01:00
.gitignore Replace all mentions of Swagger by OpenAPI (#1633) 2023-09-19 18:26:07 +01:00
.htmltest.yaml Generate ToC with Hugo rather than JavaScript (#1851) 2024-06-11 22:24:23 +01:00
config.toml Return to unstable 2024-06-20 10:25:12 -06:00
CONTRIBUTING.rst Document the removal changelog category (#1907) 2024-07-16 18:15:44 -04:00
go.mod Update docsy to v0.8.0 (#1699) 2024-02-27 18:12:39 +00:00
go.sum Update docsy to v0.8.0 (#1699) 2024-02-27 18:12:39 +00:00
LICENSE Add a license to the spec 2016-07-12 17:28:30 +01:00 Add support for pattern formats for patternProperties (#1796) 2024-04-24 12:42:34 +01:00
package-lock.json Update docsy to v0.8.0 (#1699) 2024-02-27 18:12:39 +00:00
package.json Update docsy to v0.8.0 (#1699) 2024-02-27 18:12:39 +00:00 Generate ToC with Hugo rather than JavaScript (#1851) 2024-06-11 22:24:23 +01:00
redocly.yaml Simplify uses of resolve-refs partial (#1773) 2024-04-09 18:06:53 +01:00

Matrix Specification

This repository contains the Matrix Specification. The current release version is rendered at, while the latest available build of the main branch is at

Developers looking to use Matrix should join on Matrix for help.

Spec authors and proposal writers are welcome to join We welcome contributions! See CONTRIBUTING.rst for details.


The Matrix spec is compiled with Hugo (a static site generator) with the following structure:

  • /assets: assets that need postprocessing using Hugo Pipes. For example, Sass files would go here.

  • /content: files that will become pages in the site go here. Typically these are Markdown files with some YAML front matter indicating, among other things, what layout should be applied to this page. The organization of files under /content determines the organization of pages in the built site.

  • /data: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as data objects, so templates don't need to load them from a file and parse them. This is also where our OpenAPI definitions and schemas are.

  • /layouts: this contains Hugo templates. Some templates define the overall layout of a page: for example, whether it has header, footer, sidebar, and so on.

    • /layouts/partials: these templates can be called from other templates, so they can be used to factor out template code that's used in more than one template. An obvious example here is something like a sidebar, where several different page layouts might all include the sidebar. But also, partial templates can return values: this means they can be used like functions, that can be called by multiple templates to do some common processing.
    • /layouts/shortcodes: these templates can be called directly from files in /content.
  • /static: static files which don't need preprocessing. JS or CSS files could live here.

  • /themes: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are supplied in a /themes/$theme_name/layouts directory. You can use a theme but customise it by providing your own versions of any of the theme layouts in the base /layouts directory. That is, if a theme provides /themes/$theme_name/layouts/sidebar.html and you provide /layouts/sidebar.html, then your version of the template will be used.

It also has the following top-level file:

  • config.toml: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings defined here are available in templates. All these directories above are configurable via config.toml settings.

Additionally, the following directories may be of interest:

  • /attic: Here contains historical sections of specification and legacy drafts for the specification.
  • /changelogs: Various bits of changelog for the specification areas.
  • /data-definitions: Bits of structured data consumable by Matrix implementations.
  • /meta: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
  • /scripts: Various scripts for generating the spec and validating its contents.
  • /packages: Various packages for shipping spec files like OpenAPI bindings and data definitions.

Authoring changes to the spec

Please read CONTRIBUTING.rst before authoring a change to the spec. Note that spec authoring takes place after an MSC has been accepted, not as part of a proposal itself.

  1. Install the extended version (often the OS default) of Hugo: Note that at least Hugo v0.117.0 is required.

    Alternatively, use the Docker image at (The "extended edition" is required to process the SCSS.)

  2. Run npm i to install the dependencies. Note that this will require NodeJS to be installed.

  3. Run npm run get-proposals to seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required.

  4. Run hugo serve (or docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:ext serve) to run a local webserver which builds whenever a file change is detected. If watching doesn't appear to be working for you, try adding --disableFastRender to the commandline.

  5. Edit the specification 🙂

We use a highly customized Docsy theme for our generated site, which uses Bootstrap and Font Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in before opening a PR.

Building the specification

If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above steps for authoring changes to the specification and instead of hugo serve run hugo -d "spec" - this will generate the spec to /spec. If you'd like to serve the spec off a path instead of a domain root (eg: /unstable), add --baseURL "/unstable" to the hugo -d "spec" command.

For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run pip install -r ./scripts/requirements.txt and finally python ./scripts/ to generate it to ./scripts/openapi/api-docs.json. To make use of the generated file, there are a number of options:

  • You can open ./scripts/openapi-preview.html in your browser, and then open the file by clicking on Local JSON File.
  • You can run a local HTTP server by running ./scripts/, and then view the documentation by opening ./scripts/openapi-preview.html in your browser.

Issue tracking

Specification issues are tracked on github at

See meta/github-labels.rst for information on what the labels mean.