From fefa1a0073b275175c273d60a8e4fcc5e6d8cc32 Mon Sep 17 00:00:00 2001 From: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Date: Thu, 21 May 2026 23:21:46 +0200 Subject: [PATCH 1/5] propose non-sigil matrix.to Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- proposals/xxxx-matrix.to-encoding.md | 50 ++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/xxxx-matrix.to-encoding.md diff --git a/proposals/xxxx-matrix.to-encoding.md b/proposals/xxxx-matrix.to-encoding.md new file mode 100644 index 00000000000..2897292db70 --- /dev/null +++ b/proposals/xxxx-matrix.to-encoding.md @@ -0,0 +1,50 @@ +# MSC0000: Use characters in matrix.to + +The spec defines matrix.to navigation as a web-compatible way to link to Matrix room aliases, room ids, messages within +rooms, and user ids at . + +The spec prescribes proper URL encoding for them, which applies particularly to the special characters +("sigils") in the URL fragment. +At the same time, unencoded ones should also be supported for compatibility to the more "human readable form". + +This has some issues as noted e.g. at . + +## Proposal + +The spec also defines the Matrix URI scheme , +which uses a different format to differentiate between the different types of ID: + +- `#` -> `r/` +- `!` -> `roomid/` +- `$` -> `e/` +- `@` -> `u/` + +This MSC proposes to deprecate the current use of sigils in matrix.to's fragment. +Instead, the same `type` `segment-nz` is used. + +For example: + +- +- +- +- + +## Potential issues + +Needs to be implemented in first to ensure fallback support. + +## Alternatives + +Disallowing unencoded matrix.to URLs. + +## Security considerations + +None known. + +## Unstable prefix + +Not needed. + +## Dependencies + +Needs to be implemented in first. From c3aa5136eb633b015769be9906f324f6d4faded7 Mon Sep 17 00:00:00 2001 From: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Date: Thu, 21 May 2026 23:29:18 +0200 Subject: [PATCH 2/5] MSC title and number Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- .../{xxxx-matrix.to-encoding.md => 4481-matrix.to-encoding.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-matrix.to-encoding.md => 4481-matrix.to-encoding.md} (96%) diff --git a/proposals/xxxx-matrix.to-encoding.md b/proposals/4481-matrix.to-encoding.md similarity index 96% rename from proposals/xxxx-matrix.to-encoding.md rename to proposals/4481-matrix.to-encoding.md index 2897292db70..e1d595bc8ce 100644 --- a/proposals/xxxx-matrix.to-encoding.md +++ b/proposals/4481-matrix.to-encoding.md @@ -1,4 +1,4 @@ -# MSC0000: Use characters in matrix.to +# MSC4481: Use Matrix URI-style type segments in matrix.to The spec defines matrix.to navigation as a web-compatible way to link to Matrix room aliases, room ids, messages within rooms, and user ids at . From 5385e6d7967ad02ab1217dc6b4b69e26f65a6639 Mon Sep 17 00:00:00 2001 From: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Date: Wed, 3 Jun 2026 19:24:19 +0200 Subject: [PATCH 3/5] extend motivation for the MSC Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- proposals/4481-matrix.to-encoding.md | 35 +++++++++++++++++++++------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/proposals/4481-matrix.to-encoding.md b/proposals/4481-matrix.to-encoding.md index e1d595bc8ce..c1f357e3964 100644 --- a/proposals/4481-matrix.to-encoding.md +++ b/proposals/4481-matrix.to-encoding.md @@ -1,13 +1,32 @@ # MSC4481: Use Matrix URI-style type segments in matrix.to -The spec defines matrix.to navigation as a web-compatible way to link to Matrix room aliases, room ids, messages within -rooms, and user ids at . - -The spec prescribes proper URL encoding for them, which applies particularly to the special characters -("sigils") in the URL fragment. -At the same time, unencoded ones should also be supported for compatibility to the more "human readable form". - -This has some issues as noted e.g. at . +The spec defines [matrix.to navigation](https://spec.matrix.org/v1.18/appendices/#matrixto-navigation) NOT as a service +on the web, but instead as a namespace URI effectively piggybacking on HTTP before the `matrix:` schema was registered. +The intention is to have a clearly defined format to link to Matrix room aliases, room IDs, messages within rooms, and +user IDs. Clients are supposed to parse and handle this format internally to navigate between the aforementioned Matrix +entities similarly to links between pages on the web. + +Since it is based on HTTP URLs, the spec explicitly defines matrix.to as based on RFC 3986, including URL encoding. +For the purpose of this MSC, note this applies particularly to the special characters ("sigils" of the [different types +of Matrix IDs](https://spec.matrix.org/latest/appendices/#common-identifier-format)) in the URL fragment. +At the same time, the spec recommends clients also support matrix.to URLs "which are not fully encoded" for +compatibility to the more "human readable form" that some clients produced historically and continue to do today. +This includes the web service provided by the Foundation, which coincidentally sits at and can +resolve URLs in the matrix.to shape as a kind of fallback functionality on the web. + +Besides being technically incorrect, the unencoded fragments are known to cause practical issues, which are documented +and discussed across numerous issues in the ecosystem: + +- +- +- + +Issues commonly center around URI parsing libraries failing to interpret URLs as intended by the user sharing links +outside of Matrix due to incorrect encoding. This is particularly prevalent where the `#` character has another assigned +meaning, such as across most social media. For example, the Foundation's own YouTube video descriptions used to +unwittingly contain improperly encoded matrix.to links copied from common client implementations, which broke when +YouTube introduced hashtags to the platform, including a parser that prefers to detect the second `#` as start of a +hashtag rather than the technically incorrect contents of the URL fragment. ## Proposal From d5d79fdfcb4fdd56458ca9a8743c761b853badca Mon Sep 17 00:00:00 2001 From: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Date: Wed, 3 Jun 2026 19:24:59 +0200 Subject: [PATCH 4/5] mention backward-compatibility explicitly Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- proposals/4481-matrix.to-encoding.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/proposals/4481-matrix.to-encoding.md b/proposals/4481-matrix.to-encoding.md index c1f357e3964..b76d12ed147 100644 --- a/proposals/4481-matrix.to-encoding.md +++ b/proposals/4481-matrix.to-encoding.md @@ -38,8 +38,8 @@ which uses a different format to differentiate between the different types of ID - `$` -> `e/` - `@` -> `u/` -This MSC proposes to deprecate the current use of sigils in matrix.to's fragment. -Instead, the same `type` `segment-nz` is used. +This MSC proposes to deprecate the current use of sigils in matrix.to's fragment, entirely eliminating the question +around encoding. Instead, the same `type` `segment-nz` as defined for `matrix:` (see the list above) SHALL be used. For example: @@ -48,6 +48,14 @@ For example: - - +Additionally, clients are advised to continue to support parsing the now-deprecated format using URL percent encoding as +well as incompletely encoded fragments for backwards compatibility. Clients SHOULD further prefer the new format over +the now-deprecated format when generating such URLs fully automatically, and reasonably convert URLs in the +now-deprecated format to the new format under circumstances not undermining user intention, e.g. when auto-completing. +It would generally be reasonable for clients to handle matrix.to URLs they cannot interpret correctly as regular HTTP +URLs instead, so users automatically fall back to the web service, regardless of its official stance +wrt the spec. + ## Potential issues Needs to be implemented in first to ensure fallback support. From 76f54906b7c957a987fe6bceed801af1d06a864a Mon Sep 17 00:00:00 2001 From: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> Date: Wed, 3 Jun 2026 20:31:55 +0200 Subject: [PATCH 5/5] tweak wording Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com> --- proposals/4481-matrix.to-encoding.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/4481-matrix.to-encoding.md b/proposals/4481-matrix.to-encoding.md index b76d12ed147..891f170a2e4 100644 --- a/proposals/4481-matrix.to-encoding.md +++ b/proposals/4481-matrix.to-encoding.md @@ -1,7 +1,8 @@ # MSC4481: Use Matrix URI-style type segments in matrix.to The spec defines [matrix.to navigation](https://spec.matrix.org/v1.18/appendices/#matrixto-navigation) NOT as a service -on the web, but instead as a namespace URI effectively piggybacking on HTTP before the `matrix:` schema was registered. +on the web, but instead as a namespace URI piggybacking on the `https:` scheme before the `matrix:` scheme was +registered. The intention is to have a clearly defined format to link to Matrix room aliases, room IDs, messages within rooms, and user IDs. Clients are supposed to parse and handle this format internally to navigate between the aforementioned Matrix entities similarly to links between pages on the web. @@ -53,8 +54,8 @@ well as incompletely encoded fragments for backwards compatibility. Clients SHOU the now-deprecated format when generating such URLs fully automatically, and reasonably convert URLs in the now-deprecated format to the new format under circumstances not undermining user intention, e.g. when auto-completing. It would generally be reasonable for clients to handle matrix.to URLs they cannot interpret correctly as regular HTTP -URLs instead, so users automatically fall back to the web service, regardless of its official stance -wrt the spec. +URLs instead, so users automatically fall back to the web service, regardless of its official +relationship regarding the spec. ## Potential issues