From 758c57b0214c9823306db0dcfa41ad002cdbd5dd Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 1 Oct 2020 14:33:03 +0200 Subject: [PATCH] More cleanup --- proposals/2312-matrix-uri.md | 50 +++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/proposals/2312-matrix-uri.md b/proposals/2312-matrix-uri.md index fa65e1d4..f9620701 100644 --- a/proposals/2312-matrix-uri.md +++ b/proposals/2312-matrix-uri.md @@ -160,8 +160,8 @@ The proposed generic Matrix URI syntax is a subset of the generic URI syntax [defined by RFC 3986](https://tools.ietf.org/html/rfc3986#section-3): ```text -MatrixURI = “matrix:” hier-part [ “?” query ] [ “#” fragment ] -hier-part = [ “//” authority “/” ] path +MatrixURI = "matrix:" hier-part [ "?" query ] [ "#" fragment ] +hier-part = [ "//" authority "/" ] path ``` As mentioned above, this MSC assumes client-side URI processing (i.e. mapping to Matrix identifiers and CS API requests). @@ -200,7 +200,7 @@ 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 ] +authority = host [ ":" port ] ``` Here's an example of a Matrix URI with an authority part @@ -218,10 +218,10 @@ 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 = entity-descriptor [“/” entity-descriptor] +path = entity-descriptor ["/" entity-descriptor] entity-descriptor = nonid-segment / type-qualifier id-without-sigil -non-id-segment = segment-nz ; as defined in RFC3986, see also below -type-qualifier = segment-nz “/” ; as defined in RFC3986, see also below +non-id-segment = segment-nz ; as defined in RFC 3986, see also below +type-qualifier = segment-nz "/" ; as defined in RFC 3986, see also below id-without-sigil = string ; as defined in Matrix identifier spec, see below ``` The path component consists of 1 or more descriptors separated by a slash @@ -231,7 +231,7 @@ extensions. This MSC only proposes mappings along `type-qualifier id-without-sigil` syntax; `nonid-segment` is unused and reserved for future use. For the sake of integrity future `nonid-segment` extensions must follow -[the ABNF for `segment-nz` as defined in RFC3986](https://tools.ietf.org/html/rfc3986#appendix-A). +[the ABNF for `segment-nz` as defined in RFC 3986](https://tools.ietf.org/html/rfc3986#appendix-A). This MSC defines the following `type` specifiers: `user` (user id, sigil `@`), `roomid` (room id, sigil `!`), @@ -265,13 +265,13 @@ See the rationale behind dropping sigils and the respective up/downsides in Matrix URI can optionally have [the query part](https://tools.ietf.org/html/rfc3986#section-3.4). -This MSC defines only two specific forms for the query; further MSCs -may add to this as long as RFC 3986 is followed. +This MSC defines the general form for the query and two "standard" query items; +further MSCs may add to this as long as RFC 3986 is followed. ```text -query = query-element *( “&” query-element ) +query = query-element *( "&" query-element ) query-element = action / routing -action = “action=" ( "join" / "chat" ) -routing = “via=” authority +action = "action=" ( "join" / "chat" ) +routing = "via=” authority ``` The `action` query item is used in contexts where, on top of identifying @@ -291,9 +291,9 @@ describes two possible actions: 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 to opening a room that the user -already has in the room list. +confirmation or at least notify the user before joining or creating a new room. +Conversely, no additional confirmation/notification is necessary when +the action leads to opening a room the user is already a member of. The routing query (`via=`) indicates servers that are likely involved in the room (see also @@ -562,7 +562,8 @@ With that said, a URN-styled (`matrix:room:example.org:roomalias`) option was considered. However, Matrix already uses colon (`:`) as a delimiter of id parts and, as can be seen above, reversing the parts to meet the URN's hierarchical order would look confusing for Matrix -users. +users (as in example above - is `room` a part of the identifier or +the type signifier?). ### "Full REST" @@ -580,12 +581,13 @@ the URI). ### Minimal syntax -One early but still viable proposal was to simply prepend `matrix:` to -a Matrix identifier (without encoding it), assuming that it will only be -processed on the client side. The massive downside of this option is that -such strings are not actual URIs even though they look like ones: most -URI parsers won't handle them correctly. Bare Matrix identifiers have -the same applicable range without deceptive looks. +One early proposal was to simply prepend `matrix:` to a Matrix identifier +(without encoding it), assuming that it will only be processed on the client +side. The massive downside of this option is that such strings are not actual +URIs even though they look like ones: most URI parsers won't handle them +correctly. As laid out in the beginning of this proposal, Matrix URIs are +not striving to preempt Matrix identifiers; instead of trying to produce +an equally readable string, one should just use identifiers where they work. ### Minimal syntax based on path and percent-encoding @@ -594,7 +596,7 @@ A simple modification of the previous option is much more viable: proper percent-encoding of the Matrix identifier allows to use it as a URI path part. A single identifier packed in a URI could look like `matrix:/encoded_id_with_sigil`; an event-in-a-room URI would be something -like `matrix:/roomid_or_alias/$event_id` (NB: RFC3986 doesn't require `$` +like `matrix:/roomid_or_alias/$event_id` (NB: RFC 3986 doesn't require `$` to be encoded). This is considerably more concise and encoding is only needed for `#` - quite unfortunately, this is one of the most used sigils in Matrix. E.g., `matrix:/%23matrix:matrix.org` would be a URI for @@ -619,7 +621,7 @@ to represent arbitrary sub-objects (with or without Matrix identifier) such as user profiles or a notifications feed for the room - and also, if ever needed, as an escape hatch to a bigger namespace if we hit shortage of sigils. -The current proposal is also flexible enough to even incorporate the minimal +The current proposal is also flexible enough to incorporate the minimal syntax of this option as an alternative to its own notation - e.g., a further MSC could enable `matrix:id/%23matrix:matrix.org` as a synonym for `matrix:room/matrix:matrix.org`.