The Matrix protocol specification

hacktoberfest

You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

Go to file

Travis Ralston f97d2944ae Room version 12 (#2193 ) * Placeholder * i++ * Room version 12 Template out a v12 room version Make v12 default, per MSC4304 Update PDU checks and auth event selection per MSC4291 Describe new room_id format per MSC4291 Move v6 depth definition to a component for easier referencing Move room_id to a component to prep for v12, per MSC4291 Create and use a new room_id component for v12+ per MSC4291 Reflect auth events selection change onto all room versions per MSC4291 The MSC asks the `description` of `auth_events` to be adjusted, however this feels like a better representation of the change. Add `room_id` format rules and renumber per MSC4291 Reflect change to rule 1.2 per MSC4291 Insert same room_id check to v1-12 auth rules per MSC4307 and MSC4291 Deprecate `predecessor.event_id` per MSC4291 Insert auth rule to validate `additional_creators` per MSC4289 Insert rule for `users` validation of creators and renumber per MSC4289 Define "room creator(s)" per MSC4289 Spec `additional_creators` on create events per MSC4289 Spec `additional_creators` on `/upgrade` per MSC4289 The MSC doesn't mention how to handle unsupported room versions, but the Synapse implementation used for FCP ignores the field in such room versions. This feels like a good approach, and will need clarifying in the MSC too (if accepted at the spec level). Add notes to `/upgrade` behaviour per MSC4289 and MSC4291 Describe how additional creators work during room creation per MSC4289 Fix default user power level descriptions per MSC4289 Describe tombstone power level changes per MSC4289 Warn clients about event format changes in v12 per MSC4289 and MSC4291 Flag additional room creators support for client reference per MSC4289 Remove TODO now that it's fully addressed Copy state res into v12 as-is for modification Apply Modification 1 to SR2.1 per MSC4297 Apply Modification 2 to SR2.1 per MSC4297 Add summary box to the top of SR2.1 for ease of developer reference Modification 2 was split into items 2 and 3 for further ease of understanding. Add all the changelogs `x` is used until a real PR number can be assigned. Some changelogs are duplicated to the Client-Server API to increase visibility of the changes to v12. Review: Minor phrasing adjustments in changelogs Review: Clarify that v12 isn't quite the default yet in the changelog Review: Clarify to clients that creators are immutable Review: Improve 'how to parse a domain' advice for legacy apps Review: Add a bit more detail as to why a room ID might be required Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Clarify that clients can override the tombstone default Mention creatorship UI label by finishing the Permissions section We probably should have removed the WIP note in v1.0, but alas. Add changelog for tombstone changes Use assigned spec PR number in changelogs (cherry picked from commit ec81eea7e4532fd398b8013071d6981c97117d9e)		4 months ago
.github	ci(build-openapi): indentity routes were missing (#2172 )	4 months ago
assets	Adjust margins in rendered endpoints (#2081 )	8 months ago
attic	Add a hyphen between third and party when used as an adjective (#1447 )	3 years ago
changelogs	Room version 12 (#2193 )	4 months ago
config	become unstable	5 months ago
content	Room version 12 (#2193 )	4 months ago
data	Room version 12 (#2193 )	4 months ago
data-definitions	Update data-definitions	2 years ago
informal	Update idp-brands.md (#1140 )	3 years ago
layouts	Look for examples in all possible locations (#2076 )	9 months ago
meta	Specify a correct spelling for "display name" (#2189 )	4 months ago
packages/npm	Create @matrix-org/spec npm package containing sas-emoji.json (#1620 )	2 years ago
scripts	Replace Hugo shortcodes in OpenAPI output (#2088 )	7 months ago
static	Create funding-manifest-urls (#2115 )	8 months ago
.gitignore	Optimize generated CSS by removing unused selectors (#2008 )	12 months ago
.htmltest.yml	Rename `.htmltest.yaml` to `.htmltest.yml` (#1985 )	1 year ago
CONTRIBUTING.rst	update DCO, no legal name needed (#1914 )	1 year ago
LICENSE	Add a license to the spec	10 years ago
README.md	Upgrade docsy to 0.11.0 and hugo to 0.139.0 (#1996 )	1 year ago
go.mod	Upgrade docsy to 0.11.0 and hugo to 0.139.0 (#1996 )	1 year ago
go.sum	Upgrade docsy to 0.11.0 and hugo to 0.139.0 (#1996 )	1 year ago
openapi_extensions.md	Rename `custom-formats.yaml` to `string-formats.yaml` (#1977 )	1 year ago
package-lock.json	Optimize generated CSS by removing unused selectors (#2008 )	12 months ago
package.json	Optimize generated CSS by removing unused selectors (#2008 )	12 months ago
postcss.config.js	Fix syntax highlighting and click-to-copy buttons for code blocks (#2049 )	11 months ago
redocly.yaml	Simplify uses of `resolve-refs` partial (#1773 )	2 years ago

README.md

Matrix Specification

This repository contains the Matrix Specification. The current release version is rendered at https://spec.matrix.org, while the latest available build of the main branch is at https://spec.matrix.org/unstable.

Developers looking to use Matrix should join #matrix-dev:matrix.org on Matrix for help.

Spec authors and proposal writers are welcome to join #matrix-spec:matrix.org. We welcome contributions! See CONTRIBUTING.rst for details.

Structure

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.

Install the extended version (often the OS default) of Hugo: https://gohugo.io/getting-started/installing. Note that at least Hugo v0.123.1 is required.

Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required to process the SCSS.)
Run npm i to install the dependencies. Note that this will require NodeJS to be installed.
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.
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.
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 #matrix-docs:matrix.org 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/dump-openapi.py 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/openapi-http-server.py, and then view the documentation by opening ./scripts/openapi-preview.html in your browser.

Issue tracking

Specification issues are tracked on github at https://github.com/matrix-org/matrix-spec/issues.

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