{"id":13555295,"url":"https://github.com/matrix-org/matrix-spec-proposals","last_synced_at":"2026-01-15T22:19:43.806Z","repository":{"id":21677543,"uuid":"24998719","full_name":"matrix-org/matrix-spec-proposals","owner":"matrix-org","description":"Proposals for changes to the matrix specification","archived":false,"fork":false,"pushed_at":"2024-11-06T15:34:01.000Z","size":19075,"stargazers_count":1007,"open_issues_count":499,"forks_count":379,"subscribers_count":100,"default_branch":"main","last_synced_at":"2024-11-06T22:02:52.376Z","etag":null,"topics":["matrix","spec"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-09T16:41:02.000Z","updated_at":"2024-11-05T16:40:17.000Z","dependencies_parsed_at":"2023-02-18T10:46:56.837Z","dependency_job_id":"5d8d7b3d-4362-40d1-bdf4-e20b311c6a25","html_url":"https://github.com/matrix-org/matrix-spec-proposals","commit_stats":null,"previous_names":["matrix-org/matrix-doc"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-spec-proposals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-spec-proposals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-spec-proposals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-spec-proposals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-spec-proposals/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241654966,"owners_count":19997964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["matrix","spec"],"created_at":"2024-08-01T12:03:08.061Z","updated_at":"2026-01-15T22:19:43.764Z","avatar_url":"https://github.com/matrix-org.png","language":null,"funding_links":[],"categories":["JavaScript","Uncategorized","others","Others"],"sub_categories":["Uncategorized"],"readme":"# Matrix Specification Proposals\n\nThis repository contains proposals for changes to the [Matrix\nProtocol](http://spec.matrix.org), aka \"Matrix Spec Changes\" (MSCs). The\n[`proposals`](./proposals) directory contains MSCs which have been accepted.\n\nSee below for instructions for creating new\nproposals. See also https://spec.matrix.org/proposals/ for more\ninformation on the MSC process, in particular\nhttps://spec.matrix.org/proposals/#process.\n\nThe source of the Matrix specification itself is maintained at\nhttps://github.com/matrix-org/matrix-spec.\n\n## The Matrix Spec Process\n\nAn MSC is meant to be a **technical document that unambiguously describes a\nchange to the Matrix Spec**, while also justifying _why_ the change should be\nmade.\n\nThe document is used both to judge whether the change should be made as\ndescribed *and* by developers to actually implement the changes. This is why\nit's important for an MSC to be fully fleshed out in technical detail, as once\nmerged it's immediately part of the formal spec (even though it still needs to\nbe transcribed into the actual spec itself).\n\n### What changes need to follow this process?\n\nIn most cases a change to [the Matrix protocol](https://spec.matrix.org) will\nrequire an MSC. Changes that would not require an MSC are typically small and\nuncontentious, or are simply clarifications to the spec. Fixing typos in the\nspec do not require an MSC. In most cases, removing ambiguities do not either.\nThe exception may be if implementations in the ecosystem have differing views\non clarifying the ambiguity. In that case, an MSC is typically the best place\nto reach consensus.\n\nUltimately, the [Spec Core Team](https://matrix.org/foundation) have the final\nsay on this, but generally if the change would require updates to a\nnon-insignificant portion of the Matrix implementation ecosystem or would be\nmet with contention, an MSC is the best route to take. You can also ask in the\n[Matrix Spec](https://matrix.to/#/#matrix-spec:matrix.org) or [Office of the\nSpec Core Team](https://matrix.to/#/#sct-office:matrix.org) Matrix rooms for\nclarification.\n\n### Summary of the process\n\nThe MSC process consists of three basic steps:\n\n1. **Write up the proposal** in a\n   [markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#GitHub-flavored-markdown)\n   document. (There's a [proposal\n   template](proposals/0000-proposal-template.md), but don't feel bound by it.)\n2. **Submit it as a Pull Request** to this repo, marking it as a draft until\n   it's ready for wider review.\n3. **Seek review** from the community. Once people are generally happy with it,\n   ask the [Spec Core Team](https://matrix.org/foundation) to look at it in\n   [the Office of the SCT Matrix\n   room](https://matrix.to/#/#sct-office:matrix.org). When the SCT are happy\n   with the proposal, and after a successful voting process, your pull request\n   is merged and the **MSC is now officially accepted** as part of the Matrix\n   Spec and can be used 🎉\n\nFor simple changes this is really all you need to know. For larger or more\ncontroversial changes, getting an MSC merged can take more time and effort, but\nthe overall process remains the same.\n\nBelow is various guidance to try and help make the experience smoother.\n\n### Guidance on the process\n\n#### 1. Writing the proposal\n\nCome up with an idea. The idea can be for anything, but the solution (MSC)\nneeds to benefit the Matrix ecosystem rather than yourself (or your company)\nspecifically. Sometimes this means that the solution needs to be more generic\nthan the specific itch that you are trying to scratch.\n\nRemember that an MSC is a formal technical document which will be used by\nothers in the wider community to judge if the proposal should be accepted *and*\nto actually implement the changes in clients and servers. This means that for\nan MSC to be accepted it should include justifications and describe the\ntechnical changes unambiguously, including specifying what happens in any and\nall edge cases.\n\nThere's a [proposal template](proposals/0000-proposal-template.md) under\n`docs/0000-proposal.md`, but you don't necessarily need to use it. Covering the\nsame major points is fine.\n  * Note: At this stage, you won't have an MSC number, so feel free to use\n    `0000`, `XXXX`, or whatever other placeholder you feel comfortable with.\n\nSome tips for MSC writing:\n\n* Please wrap your lines to 120 characters maximum.\n  This allows readers to review your markdown without needing to horizontally\n  scroll back and forth. Many markdown text editors have this feature.\n* If you are referencing an existing endpoint in the spec, or another MSC, it\n  is very helpful to add a link to them so the reader does not need to search\n  themselves. Examples:\n    * \"This MSC proposals an alternative to\n      [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).\"\n    * \"A new field will be added to the response body of\n      [`/_matrix/client/v3/sync`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3sync)\".\n        * Note: it is best to link to the latest stable version of the spec\n          (e.g. /v1.3, not /latest) - failing that,\n          [/unstable](https://spec.matrix.org/unstable/) if the change is not\n          yet in a released spec version.\n* GitHub supports rendering fancy diagrams from text with very little\n  effort using [Mermaid](https://mermaid-js.github.io/mermaid/#/). See [this\n  guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)\n  for more information.\n* Take a look at the [MSC Checklist](MSC_CHECKLIST.md). When it comes time for\n  the Spec Core Team to review your MSC for acceptance, they'll use the items\n  on this checklist as a guide.\n\n#### 2. Submitting a Pull Request\n\n1. Open a [Pull\n   Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)\n   to add your proposal document to the [`proposals`](proposals) directory.\n   Note that this will require a GitHub account.\n      * [Mark your Pull Request as a\n        draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)\n        for now.\n2. The MSC number is the number of the pull request that is automatically\n   assigned by GitHub. Go back through and edit the document accordingly. Don't\n   forget the file name itself!\n3. Edit the pull request title to fit the format \"MSC1234: Your proposal\n   title\".\n4. Once your proposal is correctly formatted and ready for review from the\n   wider ecosystem, [take your Pull Request out of draft\n   status](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review).\n\nThe Spec Core Team will notice this and apply various labels/status tracking to\nyour MSC, which will announce it to the wider world.\n\n#### 3. Seeking review\n\nSeek review from the Matrix community. Generally this will happen naturally,\nbut if you feel that your proposal is lacking review then ask for people's\nopinion in the [Matrix Spec room on\nMatrix](https://matrix.to/#/#matrix-spec:matrix.org).\n\nReviews can take many forms, and do not need to be done solely by members of\nthe Spec Core Team. Getting other people who are familiar with the area of\nMatrix you are proposing changes to is a great first step; especially those who\nmay be implementing these changes in clients and/or homeservers.\n\nWhile the proposal is a work in progress, it's fine for it to be high level\nand hand-wavy in places, but remember that before it can be accepted it needs\nto be expanded to fully flesh out all the technical detail and edge cases.\n\nAt this stage the proposal should also be implemented as a proof of concept\nsomewhere to show that it _actually_ works in practice. This can be done on any\nclient or server and doesn't need to be merged or released.\n\n#### 4. Entering Final Comment Period\n\nAfter the MSC has been implemented, fully fleshed out, and generally feels\nready for final review, you should ask a member of the Spec Core Team to review it in\nthe public [Spec Core Team Office room on\nMatrix](https://matrix.to/#/#sct-office:matrix.org). Someone from the SCT will\nthen review it, and if all looks well will propose FCP\nto start.\n\nAt this point, other members of the SCT will look at the proposal and consider\nit for inclusion in the spec.\n\nAfter enough SCT members have approved the proposal, the MSC will enter\nsomething called _Final Comment Period_. This is a 5 calendar day countdown to\ngive anyone one last chance to raise any blockers or concerns about the\nproposed change. Typically MSCs pass this stage without incident, but it\nnevertheless serves as a safeguard.\n\n#### 5. The MSC is accepted\n\nOnce FCP has ended and the MSC pull request is merged, the proposed change is\nconsidered officially part of the spec. Congratulations!\n\nClients and servers can now start using the change, even though at this stage\nit still needs to be transcribed into the spec document. This happens over in\nhttps://github.com/matrix-org/matrix-spec/ and you are very welcome to do it\nyourself! Otherwise it will be handled by a Spec Core Team member. If you would\nlike help with writing spec PRs, feel free to join and ask questions in the\n[Matrix Spec and Docs Authoring Room on Matrix](https://matrix.to/#/#matrix-docs:matrix.org).\n\n### Other useful information\n\n#### Unstable prefixes\n\n\"Unstable prefixes\" are the namespaces which are used by implementations while\nan MSC is not yet accepted.\n\nFor instance, an MSC might propose that a `m.space`\nevent type or an `/_matrix/client/v1/account/whoami` endpoint should exist.\nHowever, implementations cannot use these *stable* identifiers until the MSC\nhas been accepted, as the underlying design may change at any time; the design is\n*unstable*.\n\nInstead, an MSC can define a namespace such as `org.matrix.msc1234` (using the real\nMSC number once known) which is added to the stable identifier, allowing for\nbreaking changes between edits of the MSC itself, and preventing clashes with other\nMSCs that might attempt to add the same stable identifiers. \n\nFor the above examples, this would mean using `org.matrix.msc1234.space` and\n`/_matrix/client/unstable/org.matrix.msc1234/account/whoami`. It is also fine to\nuse more traditional forms of namespace prefixes, such as `com.example.*` (e.g.\n`com.example.space`).\n\nNote: not all MSCs need to make use of unstable prefixes. They are only needed if\nimplementations of your MSC need to exist in the wild before your MSC is accepted,\n*and* the MSC defines new endpoints, field names, etc.\n\n#### Unstable feature flags\n\nIt is common when implementing support for an MSC that a client may wish to check\nif the homeserver it is communicating with supports an MSC.\nTypically, this is handled by the MSC defining an\nentry in the `unstable_features` dictionary of the\n[`/_matrix/client/versions`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientversions)\nendpoint, in the form of a new entry:\n\n```json5\n{\n  \"unstable_features\": {\n    \"org.matrix.msc1234\": true\n  }\n}\n```\n\n... with a value of `true` indicating that the feature is supported, and `false`\nor lack of the field altogether indicating the feature is not supported.\n\n#### When can I use stable identifiers?\n\n[According to the spec\nprocess](https://spec.matrix.org/proposals/#early-release-of-an-mscidea): once\nan MSC has been accepted, implementations are allowed to switch to *stable*\nidentifiers. However, the MSC is still not yet part of a released spec version.\n\nIn most cases, this is not an issue. For instance, if your MSC specifies a new\nevent type, you can now start sending events with those types!\n\nSome MSCs introduce functionality where coordination between implementations is\nneeded. For instance, a client may want to know whether a homeserver supports\nthe stable version of a new endpoint before actually attempting to request it.\nOr perhaps the new event type you're trying to send relies on the homeserver\nrecognising that new event type, and doing some work when it sees it.\n\nAt this point, it may be best to wait until a new spec version is released with\nyour changes. Homeservers that support the changes will eventually advertise\nthat spec version under `/versions`, and your client can check for that.\n\nBut if you really can't wait, then there is another option: the homeserver can\ntell clients that it supports *stable* indentifiers for your MSC before it\nenters a spec version, using yet another `unstable_features` flag:\n\n```json5\n{\n  \"unstable_features\": {\n    \"org.matrix.msc1234\": true,\n    \"org.matrix.msc1234.stable\": true\n  }\n}\n```\n\nIf a client sees that `org.matrix.msc1234.stable` is `true`, it knows that it\ncan start using stable identifiers for the new MSC, and the homeserver will\naccept and act on them accordingly.\n\nNote: While the general pattern of using the text \".stable\" has emerged from\nprevious MSCs, you can pick any name you like. You need only to clearly state\ntheir meaning, usually under an \"Unstable prefixes\" header in your MSC.\n\nSee\n[MSC3827](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3827-space-explore.md#unstable-prefix)\nfor a good example of an MSC that wanted to use such a flag to speed up\nimplementation rollout, and how it did so.\n\n#### Room versions\n\nTo summarize [the spec](https://spec.matrix.org/latest/rooms/) on room\nversions: they are how servers agree upon algorithms in a decentralized world\nlike ours. Examples of changes that require a new room version include anything that changes:\n * The format of the core event structure (such as renaming a top-level field,\n   or modifying [the redaction\n   algorithm](https://spec.matrix.org/latest/client-server-api/#redactions)),\n   therefore altering the [reference\n   hash](https://spec.matrix.org/latest/server-server-api/#calculating-the-reference-hash-for-an-event)\n   of an event.\n * [The authorisation of\n   events](https://spec.matrix.org/latest/server-server-api/#authorization-rules)\n   (such as changes to power levels).\n\nUnstable prefixes (see above) for room versions work the same as they do for\nother identifiers; your unstable room version may be called\n\"org.matrix.msc1234\".\n\nIn order for the changes to end up in a \"real\" room version (the ones listed in\nthe spec), it will need a second MSC which aggregates a bunch of functionality\nfrom various MSCs into a single room version. Typically these sorts of curating\nMSCs are written by the Spec Core Team given the complexity in wording, but\nyou're more than welcome to bring an MSC forward which makes the version real.\n\nFor an example of what introducing a new room version-required feature can look\nlike, see [MSC3667](https://github.com/matrix-org/matrix-doc/pull/3667). For an\nexample of what making a new \"real\" room version looks like, see\n[MSC3604](https://github.com/matrix-org/matrix-doc/pull/3604).\n\n#### Ownership of MSCs and closing them\n\nIf an author decides that they would no longer like to pursue their MSC, they\ncan either pass ownership of it off to someone else, or close it themselves.\n\n* The author of an MSC can close their MSC at any time before FCP by simply\n  closing the pull request.\n* To appoint another user as an author of the MSC (either to replace the author\n  entirely or to provide additional help), make a note in the MSC's PR\n  description by writing the following on its own line:\n\n  ```\n  Author: @username\n  ```\n\n  where `@username` is a valid GitHub username. Multiple such lines can be\n  added.\n\n  Finally, [give that user access to write to your fork of\n  matrix-spec-proposals on\n  GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository),\n  which your PR originates from. This will allow them to change the text of\n  your MSC.\n\nSimilar to accepting an MSC, the Spec Core Team may propose a Final Comment\nPeriod with a disposition of \"close\". This can happen if the MSC appears\nabandoned by its author, or the idea is widely rejected by the community. A\nvote and final comment period will still be required for the motion to pass.\n\nAdditionally, FCP can be also proposed with a disposition of \"postpone\". This\nmay be done for MSCs for which the proposed changes do not make sense for the\ncurrent state of the ecosystem, but may make sense further down the road.\n\n## Asking for help\n\nThe Matrix community and members of the Spec Core Team are here to help guide\nyou through the process!\n\nIf you'd just like to get initial feedback about an idea that's not fully\nfleshed out yet, creating an issue at\nhttps://github.com/matrix-org/matrix-spec/issues is a great place to start. Be\nsure to search for any existing issues first to see if someone has already had\nthe same idea!\n\nA few official rooms exist on Matrix where your questions can be answered, or\nfeedback on your proposal can be requested:\n\n* [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) -\n  General chat for MSCs, the spec, and pretty much anything in that sphere.\n* [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org) - Where\n  the Spec Core Team hangs out and is available. This room is intended to have\n  extremely high signal and low noise, primarily to ensure that MSCs are not\n  falling through the cracks. If an MSC requires attention or comment from Spec\n  Core Team members, bring it up here.\n* [#matrix-spec-process:matrix.org](https://matrix.to/#/#matrix-spec-process:matrix.org) - A\n  room dedicated to [the spec process\n  itself](https://spec.matrix.org/proposals/#process). If you have any\n  questions about or suggestions to improve the Matrix Spec process, ask them\n  here.\n* [#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) - A\n  quieter room for discussion of the [formal spec\n  text](https://spec.matrix.org) and [matrix.org](https://matrix.org) website.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-spec-proposals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-spec-proposals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-spec-proposals/lists"}