URI protocol scheme for Matrix

This is a proposal of a URI scheme to identify Matrix resources in a wide range of applications (web, desktop, or mobile) both throughout Matrix
software and (especially) outside of it.
Further text uses “Matrix identifier” with a meaning of identifiers as described by the ​Matrix Specification​, and “Matrix URI” with a meaning of an
identifier following the RFC-compliant format proposed hereby.

Background
While Matrix has its own resource naming system that allows it to identify resources without resolving them, there is a common need to provide
URIs to Matrix resources (e.g., rooms, users, PDUs) that could be transferred outside of Matrix and then resolved in a uniform way - the same
case as for URLs in WWW. Specific use cases include:
1. Representation in UI: as a Matrix user I want to refer to Matrix entities in the same way as for web pages, so that others could “follow
the link” I sent them (not necessarily through Matrix, it can be, e.g., a web page or email) in order to access the referred resource.
2. Inbound integration: as an author of Matrix software, I want to have a way to invoke my software from the operating environment to
resolve a Matrix URI passed from another program. This is a case of, e.g., opening a Matrix client by clicking on a link in an email
program.
3. Outbound integration: as an author of Matrix software, I want to have a way to export identifiers of Matrix resources as URIs to
non-Matrix environment so that they could be resolved in another time-place in a uniform way. This is a case of “Share via…” action in a
mobile Matrix client.

Prior discussion of the topic can be found in the ​issue at GitHub​: in particular, it mentions an approach that strives to standardise URNs, not
URLs/URIs, with the list of resolvers being user-specific. While a URN namespace such as urn:matrix:, along with a URN scheme, may be
deemed useful once we shift to (even) more decentralised structure of the network, the more pressing problem is to actually resolve Matrix
identifiers without having to appeal to the user for additional information or interaction. This proposal deals with URIs, not with URNs.
https://matrix.to​ has been made to somehow augment the lack of URIs; its downsides are that:
● it addresses use case (1) in a somewhat clumsy way (resolving a link needs two steps from the user), and
● can only deal with (2) within a web browser (basically limiting the list of actually invoked desktop clients to browser-based ones).
Requirements
MUST/SHOULD/MAY conventions from ​RFC 2119​ are used.
1. Matrix URI MUST comply with ​RFC 3986​ and ​RFC 7595​.
2. By definition, Matrix URI MUST ​unambiguously ​ identify a resource in a Matrix network, across servers and types of resources. This, in
particular, means that two Matrix identifiers distinct by the ​Matrix specification​ MUST NOT have Matrix URIs that are equal by ​RFC
3986​.
3. The following classes MUST be supported:
a. User IDs (@user:example.org)
b. Room IDs (!roomid:example.org)
c. Room aliases (#roomalias:example.org)
d. Event IDs ($eventid:example.org)
e. Community/group IDs (+group:example.org)
4. The mapping MUST take into account that some identifiers (e.g. aliases) can have non-ASCII characters - reusing ​RFC 3987​ is
RECOMMENDED but an alternative encoding can be used if there are reasons for that.
5. The mapping between Matrix identifiers and Matrix URIs MUST be extensible to:
a. new classes of identifiers (there MUST be a rule to produce a mapping for IDs like &somethingnew:example.org)
b. other ways of navigating to Matrix objects (e.g., resolving a room-specific user profile).
6. Matrix URI SHOULD have a human-readable (to allow visual sanity-checks), if not necessarily human-friendly, representation; in
particular, characters escaping/encoding should be reduced to bare minimum in that representation. As a food for thought, see
Wikipedia: Clean URL, aka SEF URL​ and a ​ very relevant use case from RFC 3986​.
7. It SHOULD be easy to parse Matrix URI in popular programming languages: e.g., in JavaScript one should be able to use parseUri() to
dissect Matrix URI.
8. The mapping SHOULD be consistent across different classes of Matrix identifiers.
9. The mapping SHOULD be tolerant to eventual introduction of decentralised IDs (that might or might not have serverpart).
Examples of possible usage
A typical case of using a matrix.to link​ where a Matrix URI would be used.

Proposed design
The generic Matrix URI syntax follows the generic URI syntax ​as defined by RFC 3986​:

MatrixURI = “matrix:” path [ “?” query ] [ “#” fragment ]

hier-part = [ “//” authority “/” ] path

Scheme name
The proposed scheme name is “matrix”. ​RFC 7595​ states: “if there’s one-to-one correspondence between a service name and a scheme name
then the scheme name should be the same as the service name”. Other considered options were “mx” and “web+matrix” (the ​discussion at
GitHub​ has two scheme names proposed and one more has been mentioned in #matrix-core:matrix.org).

Authority
The authority part is used for the specific case of resolving a room or a user through a given server.

authority = host [ “:” port ]

A Matrix URI that includes authority may look like matrix://example.org:682/room/roomid:example2.org

Path

path = type “/” id “/” hier-part ; id is defined

type = “user” / “roomid” / “room” / “event” / “group”
 ; see ​Appendix 4 of Matrix Specification​ for id definitions

This proposal defines the general outlooks of the path part The hierarchical part is 1 or more type-id pairs separated by slash character. While
most of the current ids do not need any sort of hierarchy, there’s a notable exception: as of now, events need rooms in order to be properly
resolved so an event URI for $eventid:example.org in the room !roomid:example2.org would be
matrix:room/roomid:example2.org/event/eventid:example.org. Clients MUST resolve all Matrix entities that they support

Further proposals may add more objects residing under a top-level entity; e.g., one could conceive a mapping of avatars in the form of
matrix:user/uid:matrix.org/avatar/room:matrix.org (a user’s avatar for a given room).

This proposal defines the following standard type values: “user” (user id, sigil @), “roomid” (room id, sigil !), “room” (room alias, sigil #), “event”
(event id, sigil $), and “group” (group/community id, sigil +).

Query
Regardless from the chosen option for ​path​ (see below) Matrix URI can optionally have the ​query​ part (delimited from ​path​ by the ASCII
question mark character) with additional action or request specified, such as opening a direct chat (?action=chat, following the existing
convention in Riot), leaving a room (?action=leave) or selecting a fragment in the timeline (?from=$evtid1&to=$evtid2). As of this proposal,
clients MAY ignore the ​query​ part; recommending/enforcing to process specific actions is left for further proposals. Clients SHOULD consider
asking the user for a confirmation if an action leads to any considerable change in the state of the user account or any other resources (e.g.
opening a direct chat potentially adds a new room to the user’s roomlist).

Questions
1. [CLOSED] Should we use double-slash?
○ RFC 3986 says that double-slash marks the beginning of an authority followed by an absolute or empty path. As a corollary,
unless a domain name is put immediately after the scheme name, double-slash need not be used.
2. [CLOSED] Singular vs. plural - Singular
 ○ Plural follows the widely accepted practice of RESTful APIs (see, e.g., ​this article on the topic​).
○ On the other hand, unlike in actual RESTful APIs, rooms/ or users/ are not really containers that could be browsed in their own
right - their function is to specify which id follows in the URI. Besides, “matrix:rooms/” URI could mean a link to the list of all
rooms reachable from this user, or a list of joined rooms; and “matrix:roomids/” is just awful while linking to the same resource
(with the same ambiguity). Instead “matrix://example.org/publicRooms” could be used for the room directory as provided by a
certain server (mimicking the client-server API), and “matrix:joinedRooms” could be used to navigate to the list of rooms joined
by the user.
3. Should URIs to collections such as in the previous question be made as ​queries​ rather than just paths?
○ “matrix://example.org/publicRooms” and “matrix:joinedRooms” as opposed to (e.g.)
“matrix://example.org/directory?type=publicRooms” and “matrix:?show=joinedRooms” (with empty ​path)​ .
4. [CLOSED] Should an event URI supply the event id in ​fragment​ rather than in ​path? ​ - No.
○ Having events under rooms is a current network implementation detail rather than deliberate design. If/when event ids become
globally-unique, supplying the room id in the URI will be extraneous, events can be navigated to using their id.
5. [CLOSED] Should we consider interoperability with ​https://en.wikipedia.org/wiki/Linked_data​? - Out of scope of this proposal.

Examples
Class Matrix identifier Matrix URI

User ID @me:example.org matrix:user/me:example.org

Decentralised @me_in_matrix matrix:user/me_in_matrix

user ID (future)

Room ID !rid:example.org matrix:roomid/rid:example.org

Decentralised !lol823y4bcp3qo4 matrix:roomid/lol823y4bcp3qo4

room ID
 Room alias #us:example.org matrix:room/us:example.org

Event ID $evtid:example1.org in room matrix:room/us:example.org/event/evtid:example1.org

!rid:example.org with alias matrix:roomid/rid:example.org/event/evtid:example1.org?via=example2.org
#us:example.org, routable via
example2.org

Event ID as $UnpaddedBase64 in room with matrix:room/us:example.org/event/UnpaddedBase64

hash (​MSC1659​) alias #us:example.org

Group ID +them:example.org matrix:group/them:example.org

IRI support TODO TODO

Generic &id:example.org matrix:type/id:example.org

&decentralised-id matrix:type/decentralised-id
(‘type’ defines the resource type name corresponding to sigil &)

Dismissed alternatives
1. Dissecting the “RESTful” URI further, putting serverparts before localparts so that serverparts form a separate level of hierarchy
(matrix:room/example.org/us) - dismissed because it makes assumptions about a Matrix identifier structure and effectively mandates
having two different ways to parse centralised and decentralised ids.
2. A NID under “urn:” (“urn:matrix:”), on top of problems concerned with URN-styled representation (see below) has been turned down for
two reasons: first, urn: URIs are supposed to be managed entities (see ​RFC 8141​) which is not quite the case for Matrix identifiers
(consider room aliases and groups); second, it’s just clumsy.
3. URN-styled option: this one has been a strong contender due to its clarity and
4.

References
Issues for clients: ​Revolt​, ​Quaternion​, ​Seaglass​, ​Fractal