diff --git a/proposals/2312-matrix-uri.md b/proposals/2312-matrix-uri.md index dbd80ef14..75c565922 100644 --- a/proposals/2312-matrix-uri.md +++ b/proposals/2312-matrix-uri.md @@ -13,69 +13,80 @@ outside of Matrix and then resolved in a uniform way - matching URLs in World Wide Web. 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. +1. Representation: as a Matrix user I want to refer to Matrix entities + in the same way as for web pages, so that others could unambiguously identify + the resource, regardless of the context or used medium to identify it to them + (within or outside Matrix, e.g., in a web page or an email message). 1. 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. + opening a Matrix client by clicking on a link from an email message. 1. 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 + to export identifiers of Matrix resources 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. + An example of this case is the "Share via…" action in a mobile Matrix client. -https://matrix.to somehow compensates for the lack of dedicated URIs; however: -* it addresses use case (1) in a somewhat clumsy way (resolving a link needs - two interactions with the user instead of one), and -* it can only deal with (2) within a web browser (basically limiting - first-class support to browser-based clients). +Matrix identifiers as defined by the current specification have a form distinct +enough from other identifiers to mostly fulfil the representation use case. +Since they are not URIs they can not cover the two integration use cases. +https://matrix.to somehow compensates for this; however: +* it requires a web browser to run JavaScript code that resolves identifiers + (basically limiting first-class support to browser-based clients), and +* it relies on matrix.to as an intermediary that provides that JavaScript code. To cover the use cases above, the following scheme is proposed for Matrix URIs (`[]` enclose optional parts, `{}` enclose variables): ```text -matrix:[//{authority}/]{type}/{id without sigil}[/{more type/id pairs}][?{query}] +matrix:[//{authority}/]{type}/{id without sigil}[/{type}/{id without sigil}...][?{query}][#{fragment}] ``` -with `type` defining the resource type (such as `user` or `roomid` - see -the "Path" section in the proposal) and `query` containing additional hints +with `{type}` defining the resource type (such as `user` or `roomid` - see +the "Path" section in the proposal) and `{query}` containing additional hints or request details on the Matrix entity (see "Query" in the proposal). -The Matrix identifier (or identifiers) can be reconstructed from the URI by -taking the sigil that corresponds to `type` and appending `id without sigil` -to it. To support a hierarchy of Matrix resources, `more type/id pairs` series -is used to reconstruct inner identifiers (as of now, there can be only one -inner identifier, pointing to an event in a room). +`{authority}` and `{fragment}` parts are reserved for future use; this proposal +does not define them and implementations SHOULD ignore them for now. -This proposal defines initial mapping of URIs to Matrix identifiers and actions -on corresponding resources; the scheme and mapping are subject -to further extension. +This MSC does not introduce new Matrix entities, nor API endpoints - +it merely defines a mapping between URIs with the scheme name `matrix:` +and Matrix identifiers, as well as operations on them. The MSC should be +sufficient to produce an implementation that would convert Matrix URIs to +a series of CS API calls, entirely on the client side. It is recognised, +however, that most of URI processing logic can and should (eventually) +be on the server side in order to facilitate adoption of Matrix URIs; +further MSCs are needed to define details for that, as well as to extend +the mapping to more resources (including those without equivalent +Matrix identifiers, such as room state or user profile data). + +The Matrix identifier (or identifiers) can be reconstructed from +`{id without sigil}` by prepending a sigil character corresponding to `{type}`. +To support a hierarchy of Matrix resources, more `/{type}/{id without sigil}` +pairs can be appended, identifying resources inside of other resources. +As of now, there's only one such case, with exactly one additional pair - +pointing to an event in a room. Examples: * Room `#someroom:example.org`: `matrix:room/someroom:example.org` -* Unfederated room `#internalroom:internal.example.org`: - `matrix:room/internalroom:internal.example.org`. This can only be resolved by a client connected to the appropriate server, likely internal.example.org in this case, so it can be hinted at: `matrix:room/internalroom:internal.example.org&via=internal.example.org`. See the [Discussion points and tradeoffs](#discussion-points-and-tradeoffs) section. +* User `@me:example.org`: + `matrix:user/me:example.org` * Event in a room: `matrix:room/someroom:example.org/event/Arbitrary_Event_Id` * [A commit like this](https://github.com/her001/steamlug.org/commit/2bd69441e1cf21f626e699f0957193f45a1d560f) could make use of a Matrix URI in the form of `{Matrix identifier}`. - -This MSC does not introduce new Matrix entities, nor API endpoints - -it merely defines a mapping from a URI with the scheme name `matrix:` -to Matrix identifiers and actions on them. It is deemed sufficient to -produce an implementation that would convert Matrix URIs to a series -of CS API calls, entirely on the client side. It is recognised, -however, that most of URI processing logic can and should (eventually) -be on the server side in order to facilitate adoption of Matrix URIs; -further MSCs are needed to define details for that. + ## Proposal -Further text uses “Matrix identifier” with a meaning of identifiers -as described by [Matrix Specification](https://matrix.org/docs/spec/), -and “Matrix URI” with a meaning of an identifier following -the RFC-compliant URI format proposed hereby. +### Definitions + +Further text uses the following terms: +- Matrix identifier - one of identifiers defined by the current +[Matrix Specification](https://matrix.org/docs/spec/appendices.html#identifier-grammar), +- Matrix URI - a uniform resource identifier proposed hereby, following + the RFC-compliant URI format. +- MUST/SHOULD/MAY etc. follow the conventions of + [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + ### Requirements @@ -88,9 +99,7 @@ The following considerations drive the requirements for Matrix URIs: you cannot rewrite them once they are released to the world. 1. Ease of implementation, allowing reuse of existing codes. -The following requirements resulted from these drivers -(see [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) for conventions -around MUST/SHOULD/MAY): +The following requirements resulted from these drivers: 1. Matrix URI MUST comply with [RFC 3986](https://tools.ietf.org/html/rfc3986) and [RFC 7595](https://tools.ietf.org/html/rfc7595). @@ -121,19 +130,18 @@ around MUST/SHOULD/MAY): room-specific user profiles). 1. The mapping MUST support decentralised as well as centralised IDs. This basically means that the URI scheme MUST have provisions - for mapping of `:` but it MUST NOT require + for mapping of identifiers with `:` but it MUST NOT require `:` to be there. -1. Matrix URI SHOULD allow encoding of action requests such as joining - a room. +1. Matrix URI SHOULD allow encoding of action requests such as joining a room. 1. Matrix URI SHOULD have a human-readable, if not necessarily human-friendly, representation - to allow visual sanity-checks. 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](https://en.wikipedia.org/wiki/Clean_URL) and - [a very relevant use case from RFC 3986](https://tools.ietf.org/html/rfc3986#section-1.2.1). + [a use case from RFC 3986](https://tools.ietf.org/html/rfc3986#section-1.2.1). 1. It SHOULD be easy to parse Matrix URI in popular programming languages: e.g., one should be able to use `parseUri()` - to dissect a Matrix URI in JavaScript. + to dissect a Matrix URI into components in JavaScript. 1. The mapping SHOULD be consistent across different classes of Matrix identifiers. 1. The mapping SHOULD support linking to unfederated servers/networks @@ -141,8 +149,10 @@ around MUST/SHOULD/MAY): [matrix-doc#2309](https://github.com/matrix-org/matrix-doc/issues/2309) that calls for such linking). -The syntax and mapping discussed below meet all these requirements. -Further extensions MUST comply to them as well. +The syntax and mapping discussed below meet all these requirements except +the last one that will be addressed separately. +Further extensions MUST NOT reduce the supported set of requirements. + ### Syntax and high-level processing @@ -156,8 +166,8 @@ hier-part = [ “//” authority “/” ] path As mentioned above, this MSC assumes client-side URI processing (i.e. mapping to Matrix identifiers and CS API requests). However, even when URI processing is shifted to the server side -the client will still have to parse the URI at least to find -the authority part (or lack of it) and remove the fragment part +the client will still have to parse the URI at least to remove +the authority and fragment parts (if either exists) before sending the request to the server (more on that below). #### Scheme name @@ -179,14 +189,16 @@ references](https://tools.ietf.org/html/rfc3986#section-4.2) and omitting the scheme name makes them indistinguishable from a local path that might have nothing to do with Matrix. Clients MUST NOT try to parse pieces like `room/MyRoom:example.org` as Matrix URIs; instead, -users should be encouraged to use Matrix IDs for in-text references -(`#MyRoom:example.org`) and client applications should do -the heavy-lifting of turning them into hyperlinks to Matrix URIs. +users should be encouraged to use Matrix identifiers for in-text references +(`#MyRoom:example.org`) and client applications SHOULD turn them into +hyperlinks to Matrix URIs. #### Authority -The authority part is used for the specific case of getting access -to a Matrix resource (such as a room or a user) through a given server. +The authority part will eventually be used to indicate access to a Matrix +resource (such as a room or a user) specifically through a given server, +addressing a case described in +[matrix-org/matrix-doc#2309](https://github.com/matrix-org/matrix-doc/issues/2309). ```text authority = host [ “:” port ] ``` @@ -200,10 +212,11 @@ Clients SHOULD NOT use data from the authority part other than for experimental or further research purposes. #### Path -Unlike the very wide definition of path in RFC 3986, this MSC -restricts the path component of a Matrix URI to a simple -pattern that allows to easily reconstruct a Matrix identifier or -a chain of identifiers: +This MSC restricts +[the very wide definition of path in RFC 3986](https://tools.ietf.org/html/rfc3986#section-3.3), +to a simple pattern that allows to easily reconstruct a Matrix identifier or +a chain of identifiers and also to locate a certain sub-resource in the scope +of a given Matrix entity: ```text path = type “/” id-without-sigil [“/” path] type = “user” / “roomid” / “room” / “event” / “group” @@ -252,18 +265,21 @@ the Matrix entity, a certain action is requested on it. This proposal describes two possible actions: * `action=join` is only valid in a URI resolving to a Matrix room; applications MUST ignore it if found in other contexts and MUST NOT generate - it for other Matrix resources. This action means that client applications - SHOULD attempt to join it using the standard CS API means. + it for other Matrix resources. This action means that a client application + SHOULD attempt to join the room specified by the URI path using the standard + CS API means. * `action=chat` is only valid in a URI resolving to a Matrix user; applications MUST ignore it if found in other contexts and MUST NOT generate - it for other Matrix resources. A URI with this action that a client application - SHOULD open a direct chat window with the user; clients supporting + it for other Matrix resources. This action means that a client application + SHOULD open a direct chat window with the user specified by the URI path; + clients supporting [canonical direct chats](https://github.com/matrix-org/matrix-doc/pull/2199) SHOULD open the canonical direct chat. For both actions, where applicable, client applications SHOULD ask for user confirmation or at least make the user aware if the action leads -to joining or creating a new room rather than switching to a prior one. +to joining or creating a new room rather than to opening a room that the user +already has in the room list. The routing query (`via=`) indicates servers that are likely involved in the room (see also @@ -459,7 +475,7 @@ further discussion should happen in GitHub comments. the authority part in generated URIs for a given user account.~~ Use `via=` in order to point to a homeserver in the closed federation. The authority part may eventually be used for that but further discussion - is needed on how clients should support without compromising privacy + is needed on how clients should support it without compromising privacy (see https://github.com/matrix-org/matrix-doc/pull/2312#discussion_r348960282 for the original concern).