1   Proposals for Spec Changes to Matrix

The process for submitting a Matrix Spec Change (MSC) Proposal is as follows:

  • Produce a publicly-accessible proposal describing your change:
    • Please use Google Docs, or an equivalent system capable of collaborative editing, with versioned history, suggestions ('track changes'), threaded comments, and good mobile support. Please ensure the document is world-commentable or -editable.
    • We do not use Github issues (or Etherpad) for the design process of the proposal, as the document review/commenting capabilities aren't good enough.
    • We also don't jump straight to PRing against the spec itself, as it's much faster to iterate on a proposal in freeform document form than in the terse and formal structure of the spec.
    • In the proposal, please clearly state the problem being solved, and the possible solutions being proposed for solving it and their respective trade-offs.
    • Proposal documents are intended to be as lightweight and flexible as the author desires; there is no formal template; the intention is to iterate as quickly as possible to get to a good design.
    • A template with suggested headers is available.
  • Make a new issue at https://github.com/matrix-org/matrix-doc/issues, whose description should list the metadata as per below. Use the github search function to attempt to locate any related github issues, and link any that are found in the body of the new issue.
  • Gather feedback as widely as possible from the community and core team on the proposal.
    • The aim is to get maximum consensus on the trade-offs chosen to get an optimal solution.
    • A good place to ask for feedback on a specific proposal is #matrix-spec:matrix.org. However, authors/shepherds are welcome to use an alternative room if they prefer - please advertise it in #matrix-spec:matrix.org though and link to it on the github issue. N.B. that #matrix-dev:matrix.org is for developers using existing Matrix APIs, #matrix:matrix.org is for users trying to run matrix apps (clients & servers); #matrix-architecture:matrix.org is for cross-cutting discussion of Matrix's architectural design.
    • The point of the spec proposal process is to be collaborative rather than competitive, and to try to solve the problem in question with the optimal set of trade-offs. Ideally the author would neutrally gather the various viewpoints and get consensus, but this can sometimes be time-consuming (or the author may be biased), in which case an impartial 'shepherd' can be assigned to help guide the proposal through this process. A shepherd is typically a neutral party from the core team or an experienced member of the community.
  • Once the proposal has sufficient consensus and passed review, you must show an implementation to prove that it works well in practice, before a spec PR will be accepted. Iterate on the proposal if needed.
  • Finally, please make a new spec PR which includes the changes as implemented against https://github.com/matrix-org/matrix-doc/tree/master/specification. This will then be reviewed and hopefully merged! Please sign off the spec PR as per the CONTRIBUTING.rst guidelines.

Final decisions on review are made by the Matrix core team (+matrix:matrix.org), acting on behalf of the whole Matrix community.

Proposals must act to the greater benefit of the entire Matrix ecosystem, rather than benefiting or privileging any single player or subset of players - and must not contain any patent encumbered IP. The Matrix core team pledges to act as a neutral custodian for Matrix on behalf of the whole ecosystem, just as it has since Matrix's inception in May 2014.

For clarity: the Matrix ecosystem is anyone who uses the Matrix protocol. That includes client users, server admins, client developers, bot developers, bridge and AS developers, users and admins who are indirectly using Matrix via 3rd party networks which happen to be bridged, server developers, room moderators and admins, companies/projects building products or services on Matrix, spec contributors, translators, and the core team who created it in the first place.

"Greater benefit" could include maximising:

  • the number of end-users reachable on the open Matrix network.
  • the number of regular users on the Matrix network (e.g. 30-day retained federated users)
  • the number of online servers in the open federation.
  • the number of developers building on Matrix.
  • the number of independent implementations which use Matrix
  • the quality and utility of the Matrix spec.

The guiding principles of the overall project are being worked on as part of the upcoming governance proposal, but could be something like:

  • Supporting the whole long-term ecosystem rather than individual stakeholder gain
  • Openness rather than proprietariness
  • Collaboration rather than competition
  • Accessibility rather than elitism
  • Transparency rather than stealth
  • Empathy rather than contrariness
  • Pragmatism rather than perfection
  • Proof rather than conjecture

The above directions are intended to be simple and pragmatic rather than exhaustive, and aim to provide guidelines until we have a formal spec governance process in place that covers the whole Matrix community. In order to get Matrix out of beta as quickly as possible, as of May 2018 we are prioritising spec and reference implementation development over writing formal governance, but a formal governance document will follow as rapidly as possible.

The process for handling proposals is described in the following diagram. Note that the lifetime of a proposal is tracked through the corresponding labels for each stage in the matrix-doc issue tracker.

                       +                            +
     Proposals         |          Spec PRs          |   Other States
     +-------+         |          +------+          |   +----------+
                       |                            |
                       |                            |
    +----------+       |         +---------+        |    +---------+
    |          |       |         |         |        |    |         |
    | Proposal |       |  +------> Spec PR |        |    | Blocked |
    |   WIP    |       |  |      | Missing |        |    |         |
    |          |       |  |      |         |        |    +---------+
    +----+-----+       |  |      +----+----+        |
         |             |  |           |             |
         |             |  |           |             |  +-----------+
+--------v----------+  |  |           |             |  |           |
|                   |  |  | +---------v--------+    |  | Abandoned |
|      Proposal     |  |  | |                  |    |  |           |
|  Ready for Review |  |  | |     Spec PR      |    |  +-----------+
|                   |  |  | | Ready for Review |    |
+----------+--------+  |  | |                  |    |  +-----------+
           |           |  | +---------+--------+    |  |           |
           |           |  |           |             |  | Obsolete  |
    +------v----+      |  |           |             |  |           |
    |           |      |  |     +-----v-----+       |  +-----------+
    | Proposal  |      |  |     |           |       |
    | In Review |      |  |     |  Spec PR  |       |
    |           |      |  |     | In Review |       |   +----------+
    +----+------+      |  |     |           |       |   |          |
         |             |  |     +-----+-----+       |   | Rejected |
         |             |  |           |             |   |          |
  +------v--------+    |  |           |             |   +----------+
  |               |    |  |           |             |
  |   Proposal    |    |  |      +----v----+        |
  | Passed Review |    |  |      |         |        |
  |               |    |  |      | Merged! |        |
  +-------+-------+    |  |      |         |        |
          |            |  |      +---------+        |
          |            |  |                         |
          +---------------+                         |
                       |                            |
                       +                            +

2   Lifetime States

Proposal WIP A proposal document which is still work-in-progress but is being shared to incorporate feedback
Proposal Ready for Review A proposal document which is now ready and waiting for review by the core team and community
Proposal In Review A proposal document which is currently in review
Proposal Passed Review A proposal document which has passed review as worth implementing and then being added to the spec
Spec PR Missing A proposal which has been implemented and has been used in the wild for a few months but hasn't yet been added to the spec
Spec PR Ready for Review A proposal which has been PR'd against the spec and is awaiting review
Spec PR In Review A proposal which has been PR'd against the spec and is in review
Merged A proposal whose PR has merged into the spec!
Blocked A proposal which is temporarily blocked on some external factor (e.g. being blocked on another proposal first being approved)
Abandoned A proposal where the author/shepherd has not been responsive for a few months
Obsolete A proposal which has been overtaken by other proposals
Rejected A proposal which is not going to be incorporated into Matrix

3   Proposal Tracking

This is a living document generated from the list of proposals at matrix-doc/issues on GitHub.

We use labels and some metadata in the issues' descriptions to generate this page. Labels are assigned by the core team whilst triaging the issues based on those which exist in the matrix-doc repo already.

Other metadata:

  • the MSC (Matrix Spec Change) number is taken from the github issue ID. This is carried for the lifetime of the proposal, including the PR creation phase. N.B. They are not in chronological order!
  • Please use the github issue title to set the title.
  • Please link to the proposal document by adding a "Documentation: <url>" line in the issue description.
  • Please link to the spec PR (if any) by adding a "PRs: #1234" line in the issue description.
  • The creation date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the issue description.
  • Updated Date is taken from github.
  • Author is the creator of the github issue, but can be overriden by adding a "Author: @username" line in the body of the issue description. Please make sure @username is a github user (include the @!)
  • A shepherd can be assigned by adding a "Shepherd: @username" line in the issue description. Again, make sure this is a real Github user.

4   Tables of Tracked Proposals

4.1   proposal-wip

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC586 Federation API for canonicalising MXIDs 2014-10-27 2018-05-15 586-1 @ara4n None  
MSC489 Extensible Profiles. (SPEC-93) 2015-01-19 2018-09-06 489-1 @erikjohnston None  
MSC1148 Support for websockets 2015-11-16 2018-06-04 1148-1, 1148-2 @richvdh, @krombel None  
MSC1238 Push to Talk 2016-04-13 2018-05-15 1238-1 @aviraldg None PR#310
MSC1198 Threading API 2016-05-23 2018-05-15 1198-1 @Half-Shot None  
MSC1207 Publishing Room Lists for 3rd party networks 2016-10-21 2018-05-31 1207-1 @erikjohnston None  
MSC1237 Improving m.location with GeoJSON and accuracy 2017-05-19 2018-05-15 1237-1 @Half-Shot None PR#919
MSC1215 Groups as Rooms 2017-10-17 2018-05-15 1215-1 @ara4n None  
MSC1218 Bridging group membership with 3rd party group sources 2017-11-15 2018-05-15 1218-1 @lukebarnard1 None  
MSC1219 Proposal for storing megolm keys serverside 2017-11-23 2018-08-13 1219-1 @ara4n None  
MSC1221 Improving Presence 2017-12-26 2018-05-24 1221-1 @ara4n None  
MSC1100 Refine and clarify how presence works 2017-12-26 2018-09-06 1100-1 @ara4n None  
MSC1222 Pushing updates about Groups (Communities) to clients 2018-01-02 2018-05-24 1222-1 @ara4n None  
MSC1225 Extensible event types & fallback in Matrix 2018-02-18 2018-09-06 1225-1 @ara4n None  
MSC1228 Removing MXIDs from events 2018-04-19 2018-09-06 1228-1 @richvdh None  
MSC1231 Handling Consent for Privacy Policy 2018-05-02 2018-05-15 1231-1 @neilisfragile None  
MSC1267 Interactive Key Verification 2018-05-28 2018-05-28 1267-1 @uhoreg None  
MSC1280 Mechanisms for communicating erasure requests to bots and federated homeservers 2018-06-05 2018-06-05 1280-1 @richvdh None  
MSC1287 spec lazy_load_members and include_redundant_members 2018-06-10 2018-09-05   @ara4n None  
MSC1322 Mechanism to communicate 3PID binding updates or deletions to homeservers 2018-06-20 2018-06-20 1322-1 @babolivier None  
MSC1410 Proposal for Rich Bridging 2018-07-12 2018-08-02 1410-1 @Half-Shot None  
MSC1453 Antivirus support 2018-07-26 2018-07-26   @ara4n None  
MSC1485 Hint buttons in messages 2018-08-04 2018-08-04 1485-1 @tulir None  
MSC1488 MSC Suggested Mentions 2018-08-06 2018-08-30 1488-1 @Half-Shot None  
MSC1501 Room version upgrades 2018-08-10 2018-08-30 1501-1 @richvdh None  
MSC1543 Key verification using QR codes 2018-08-20 2018-08-30 1543-1 @uhoreg None PR#1544
MSC1608 Better spec for room aliases 2018-08-29 2018-09-14 1608-1 @richvdh None  
MSC1646 MSC: Better specify how to validate events 2018-08-31 2018-09-14   @richvdh None  
MSC1640 MSC: Replace event IDs with hashes 2018-08-31 2018-09-06 1640-1 @erikjohnston None  
MSC1680 MSC: cross-signing of devices to simplify key verification 2018-09-20 2018-09-20 1680-1 @uhoreg None  

4.2   proposal-ready-for-review

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC1206 Proposal for improved bot support 2018-03-14 2018-07-26 1206-1 @turt2live None  
MSC1256 Custom emoji and sticker packs in matrix 2018-05-23 2018-05-24 1256-1 @turt2live None  
MSC1270 Proposal Add /_matrix/media/v1/resolve_url to Client-Server API: download and preview urls in the clients despite CORS 2018-05-31 2018-06-19 1270-1 @oivoodoo None  
MSC701 Auth for content repo (and enforcing GDPR erasure) 2018-06-04 2018-06-07 701-1 @ara4n None  
MSC1301 Proposal for improving authorization for the matrix profile API 2018-06-13 2018-09-06 1301-1 @turt2live None  
MSC1309 Proposal for an application service management API 2018-06-14 2018-07-10 1309-1 @turt2live None  
MSC1308 Proposal for speeding up review of simple spec changes 2018-06-14 2018-07-06   @ara4n None  
MSC1306 Proposal to filter out traffic to Appservices based on filters 2018-06-14 2018-07-10 1306-1 @Half-Shot None  
MSC1310 Proposal for a media information API 2018-06-17 2018-07-10 1310-1 @turt2live None  
MSC1316 Proposal to have the appservice registration type be optional 2018-06-18 2018-07-10 1316-1 @turt2live None  
MSC1330 Proposal to improve /createRoom 2018-06-22 2018-09-06 1330-1 @turt2live None  
MSC1337 Proposal to improve /members and /joined_rooms 2018-06-23 2018-09-06 1337-1 @turt2live None  
MSC1354 Widget API extension: Always-on-screen 2018-07-03 2018-07-10 1354-1 @dbkr None  
MSC1504 Homeserver resource limiting error codes 2018-08-13 2018-08-13 1504-1 @neilisfragile None  

4.3   proposal-in-review

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC1227 Proposal for lazy-loading room members to improve initial sync speed and client RAM usage 2018-03-05 2018-09-05 1227-1 @ara4n None  
MSC1194 A way for HSes to remove bindings from ISes (aka unbind) 2018-05-09 2018-06-05 1194-1 @dbkr None  
MSC688 Room Summaries (was: Calculate room names server-side) 2018-06-10 2018-09-05 688-1 @ara4n None  
MSC1318 Proposal for Open Governance of Matrix.org 2018-06-20 2018-07-10 1318-1 @ara4n None  
MSC1339 Proposal to add a GET method to read account data 2018-06-24 2018-09-06   @ananace None  
MSC1426 Proposal for clarifying and improving review process for MSCs 2018-07-17 2018-07-21 1426-1 @ara4n None  
MSC1452 Homeserver Warning Messages 2018-07-25 2018-08-21 1452-1 @dbkr None  
MSC1466 MSC Soft Logout 2018-08-01 2018-08-16 1466-1 @erikjohnston None  
MSC1497 Capabilities support in the CS API 2018-08-08 2018-09-05 1497-1 @ara4n None  
MSC1597 Better spec for matrix identifiers 2018-08-29 2018-09-14 1597-1 @richvdh None  

4.4   proposal-passed-review

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC1229 Mitigating abuse of the event depth parameter over federation 2018-04-30 2018-07-13 1229-1 @ara4n None  

4.5   spec-pr-missing

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC1211 Megolm session export format 2017-01-03 2018-09-15 1211-1 @richvdh None  
MSC971 Add groups stuff to spec 2017-08-10 2018-07-24 971-1, 971-2, 971-3 @erikjohnston None  
MSC1214 Related Groups (i.e. flair) 2017-10-03 2018-05-15 1214-1 @lukebarnard1 None  
MSC1236 Matrix Widget API v2 2018-05-13 2018-07-26 1236-1 @rxl881 None  

4.6   merged

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC433 Support for discovering API endpoints via .well-known URIs (SPEC-121) 2015-03-08 2018-08-29 433-1, 433-2 @maxidor, others @uhoreg  
MSC1197 Ignoring Users 2016-05-03 2018-05-18 1197-1 @erikjohnston None PR#1142
MSC1199 Notifications API 2016-05-23 2018-06-25 1199-1 @dbkr None  
MSC1200 Configuration of E2E encryption in a room 2016-06-16 2018-08-24 1200-1 @richvdh None PR#1284
MSC1201 Device Management API 2016-07-14 2018-08-15 1201-1 @richvdh None  
MSC1203 3rd Party Entity lookup API 2016-07-21 2018-08-14 1203-1 @leonerd None PR#1353
MSC1204 Access Token Semantics (refresh and macaroons) - aka Auth Sept 2016 Edition 2016-09-29 2018-06-25 1204-1 @richvdh None  
MSC1205 Proposal for multi-device deletion API 2016-10-12 2018-06-25 1205-1 @richvdh None PR#1239
MSC1208 Encrypted attachment format 2016-10-26 2018-08-31 1208-1 @NegativeMjark None PR#1420
MSC739 Reporting inappropriate content in Matrix 2016-11-21 2018-07-03 739-1 @ara4n None  
MSC1212 Device List Update Stream 2017-01-18 2018-09-18 1212-1 @richvdh None PR#1284, PR#1648
MSC829 Need to spec msisdn login API 2017-03-08 2018-08-17 829-1 @dbkr None PR#1390
MSC855 spec m.login.msisdn UI auth type 2017-03-24 2018-08-14 855-1 @dbkr None  
MSC910 Add new Read Marker API to docs 2017-05-08 2018-09-17 910-1 @lukebarnard1 None  
MSC953 Add /user_directory/search API 2017-05-31 2018-07-26 953-1 @erikjohnston None  
MSC1067 Spec @mentions 2017-07-14 2018-08-30 1067-1 @lukebarnard1 None  
MSC1033 Doc @room notifications 2017-10-23 2018-08-30 1033-1 @dbkr None  
MSC1183 Document key-share requests 2018-04-30 2018-08-30 1183-1 @richvdh None  
MSC1230 Temporary mitigation for depth parameter abuse 2018-05-01 2018-08-30 1230-1 @ara4n None  
MSC1232 Media limits API 2018-05-04 2018-07-06 1232-1 @Half-Shot None PR#1189
MSC1233 A proposal for organising spec proposals 2018-05-10 2018-06-25 1233-1 @ara4n None PR#1240
MSC1234 Rich Replies format 2018-05-12 2018-09-17 1234-1 @t3chguy None  
MSC1304 Proposal to simplify the auth rules of m.room.power_level events. 2018-06-13 2018-09-04 1304-1 @richvdh, @ara4n None  
MSC1323 AS traffic rate-limiting 2018-06-20 2018-08-28 1323-1 @anoadragon453 None  
MSC1383 Proposal for ACLing servers from rooms 2018-07-05 2018-08-30 1383-1 @richvdh, @ara4n None  
MSC1425 Room Versioning 2018-07-17 2018-08-24 1425-1 @richvdh None  
MSC1442 State Resolution: Reloaded 2018-07-20 2018-09-04 1442-1 @erikjohnston None  

4.7   abandoned

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC531 Homeservers as OAuth authorization endpoints (resource owners) (SPEC-206) 2015-07-25 2018-05-15 531-1 @Kegsay None  
MSC1202 Profile Personae 2016-07-15 2018-05-15 1202-1 @erikjohnston None  
MSC1209 Server Side Profile API 2016-11-01 2018-05-15 1209-1 @erikjohnston None  
MSC1213 Set defaults for m.federate 2017-04-10 2018-05-18 1213-1 @psaavedra None  
MSC1217 Visibility of groups to group members and their non-members 2017-10-30 2018-08-13 1217-1 @lampholder None  

4.8   obsolete

MSC Proposal Title Creation Date Update Date Documentation Author Shepherd PRs
MSC1196 Matrix Escape Hatch (Versioned Rooms) 2015-10-22 2018-07-17 1196-1 @leonerd None  
MSC1223 Replies event format 2018-02-01 2018-05-15 1223-1 @t3chguy None  
MSC1224 Replies - next steps 2018-02-03 2018-05-15 1224-1 @t3chguy None  
MSC1235 Proposal for Calendar Events 2018-02-06 2018-05-15 1235-1 @Half-Shot None  
MSC1226 State Reset mitigation proposal 2018-02-20 2018-07-17 1226-1 @richvdh None  
MSC1220 Rich quoting proposal 2018-05-10 2018-05-15 1220-1 @t3chguy None  
MSC1324 Custom protocol definitions for application services 2018-06-20 2018-08-30 1324-1 @anoadragon453 None  
MSC1421 Make a Discourse forum the canonical location for spec discussions 2018-07-16 2018-08-05 1421-1 @non-Jedi None