Skip to content

MSC4487: Deprecate internal use of matrix.to navigation #4487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HarHarLinks wants to merge 2 commits into
base: main
Choose a base branch
from
+65 −0
Open

MSC4487: Deprecate internal use of matrix.to navigation #4487

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a49fb0
propose deprecation of internal matrix.to
HarHarLinks Jun 3, 2026
af02230
MSC title and number
HarHarLinks Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions proposals/4487-deprecate-internal-matrix.to.md
View file
Open in desktop

@turt2live turt2live Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • Product teams from clients supporting this behaviour

@tulir tulir Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this have to do with product teams? 🤔 It's an entirely internal technical detail that shouldn't be visible to users at all

I don't think this needs any implementation, since the spec already allows using matrix URIs, there are already multiple clients that correctly handle matrix: URIs in <a> tags, and this is just a deprecation rather than a removal.

@MTRNord MTRNord Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I get where "Product teams" comes from I just wanted to mention that this feels a bit weird as a term considering a lot of clients are not done by companies in matrix ecosystem. So lots of them don't have such a team. This term feels almost a bit out of touch with the reality of matrix ecosystem. Sorry for being nitpicky. This isn't meant to be rude. I just wanted to mention this for next time maybe.

@HarHarLinks HarHarLinks Jun 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, the MSC is deliberately very conservative in that regard.

@turt2live turt2live Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this have to do with product teams? 🤔 It's an entirely internal technical detail that shouldn't be visible to users at all

Clients expose matrix.to in several places to users and this proposal requires that those clients don't do that. Why those clients haven't already made the switch is essentially the product decision to be made here.

The implementation requirements for a deprecation is typically evidence that it's safe to queue for removal. Because clients still actively use matrix.to by choice, we cannot queue this for removal.

If the proposal's purpose is to discourage use without targeting removal then it should not be using deprecation.

@turt2live turt2live Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd then need implementations of all of that to show it's feasible to rewrite matrix: URIs to matrix.to URLs.

  • Client (modern desktop)
  • Client (modern browser)
  • Client (iOS)
  • Client (Android)

@tulir tulir Jun 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was confused by why clients would need to rewrite matrix: URIs to matrix.to URLs, but apparently it's because at least Element X decided that pills need a "copy link" context menu option. It's technically an existing spec compliance issue (the spec already allows using matrix: for pills), but it's fair to consider those before having the spec recommend actively switching to matrix: URIs over matrix.to URLs, as such a recommendation will cause clients to hit the spec compliance issues a lot more.

It's probably also better to start with having the spec just recommend matrix: URIs ("Clients SHOULD use matrix: URIs when sending user and room mentions") before a formal deprecation of matrix.to in pills.

@TheOneWithTheBraid TheOneWithTheBraid Jun 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a client developer perspective (so-called product team 😂), I can confirm : Every major client supports the Matrix URI scheme. With the acceptance of matrix: as standardized scheme, even web-clients can register to handle incoming Matrix URLs simple as by including it into the web app manifest.

Matrix URIs are easier to handle since they tend to be less buggy. E.g., many Matrix clients as well as users manually writing links tend to fail at the URI component encoding of the sigils that's required according to the matrix.to scheme. With standardized Matrix URIs this issue is solved.

Imho, the following should be the way to go :

  • Clients MUST NOT try to handle incoming matrix.to links
  • Clients SHOULD for a transition period internally convert matrix.to links to Matrix URLs
  • Clients MUST NOT send any matrix.to links via Matrix
  • Clients SHOULD offer an option to share a matrix.to link to 3rd party applications (e.g. by email, share intent etc.)
  • Matrix.to MUST convert incorrectly encoded sigils on the fly to show the correct matrix.to URL in the User Agent address bar
  • Matrix.to MUST by default fallback on opening the User Agent's preferred client using a Matrix URL

@HarHarLinks HarHarLinks Jun 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pills need a "copy link" context menu option

Sure, per the MSC that is reasonable and even implied as intended.

Client (modern desktop)
Client (modern browser)
Client (iOS)
Client (Android)

I can't help but feel like asking for POC implementations on no less than 4 platforms is chicanery for something that is obviously™️ a trivial find-replace. Why would this be necessary? I would even argue it's so trivial that it doesn't need an implementation. Both parsing and generating of both matrix: and matrix.to URIs to/from IDs is already proven by their respective inclusion in the spec.

Anyway, here's an implementation in bash:

#!/usr/bin/env bash

function convert {
	id="$1"
	if [[ "${id:7:7}" == "roomid/" ]]; then
		id="${id//roomid\//!}"
	elif [[ "${id:7:2}" == "r/" ]]; then
		id="${id//r\//%23}"
	elif [[ "${id:7:2}" == "u/" ]]; then
		id="${id//u\//@}"
	fi
	if [[ "$id" == *"/e/"* ]]; then
		id="${id//\/e\///$}"
	fi
	id="${id//matrix:/https://matrix.to/#/}"
	echo "$id"
}

room_alias='matrix:r/somewhere:example.org'
room_v12='matrix:roomid/somewhere?via=elsewhere.ca'
room_v11='matrix:roomid/somewhere:example.org?via=elsewhere.ca'
user='matrix:u/alice:example.org?action=chat'
alias_event='matrix:r/somewhere:example.org/e/event?via=elsewhere.ca'
v12_event='matrix:roomid/somewhere/e/event?via=elsewhere.ca'

convert "$room_alias"
# https://matrix.to/#/%23somewhere:example.org
convert "$room_v12"
# https://matrix.to/#/!somewhere?via=elsewhere.ca
convert "$room_v11"
# https://matrix.to/#/!somewhere:example.org?via=elsewhere.ca
convert "$user"
# https://matrix.to/#/@alice:example.org?action=chat
convert "$alias_event"
# https://matrix.to/#/%23somewhere:example.org/$event?via=elsewhere.ca
convert "$v12_event"
# https://matrix.to/#/!somewhere/$event?via=elsewhere.ca

Note that while the examples in the spec for matrix.to percent-encode ALL special chars, aiui this isn't required by RFC 3986.

@KitsuneRal KitsuneRal Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Obligatory reminder that I wrote the steps to world domination matrix: URI scheme support 5 years ago: element-hq/element-web#16875 (comment) - and for as long as I remember, people mostly agreed by these steps, and nobody challenged them. This MSC (@HarHarLinks I owe you your favourite beverage at conf or somewhere for writing it) is a legislation for step 2 because apparently (and yes I'm looking at Element now) some "product teams" just can't prioritise it otherwise.

Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# MSC4487: Deprecate internal use of matrix.to navigation

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 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.

The <https://matrix.to> web service provided by the Foundation is available at and can resolve URLs in the matrix.to
shape as a kind of fallback functionality on the web. This is a very convenient workaround for any client not wanting to
spend the effort to special case internal navigation, and even when not showing a plain text matrix.to URL as a
clickable link many users understand the idea that they can copy this URL to their web browser to continue on.
Unfortunately this fallback remains a centralised crutch in an otherwise decentralised ecosystem when not resolved
inside of a client.

Matrix has introduced and registered the `matrix:` URI scheme as a parallel system with the major advantages of being
independent of the `https:` scheme, hence allowing deeper integration in URI handlers, while still remaining generalised
to fit the principle of free client choice in Matrix. It also simplifies parsing in clients significantly since special
casing `https://matrix.to` for internal routing is not a standard use case and often requires painful manual parsing.

## Proposal

Sending matrix.to URLs over Matrix is deprecated.

Clients SHALL instead generate `matrix:` URIs when it is clear that:

- a reference to a Matrix entity (room alias, room ID, event within a room, user ID) is going to be sent over Matrix,

@HarHarLinks HarHarLinks Jun 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- a reference to a Matrix entity (room alias, room ID, event within a room, user ID) is going to be sent over Matrix,
- a reference ("pill") to a Matrix entity (room alias, room ID, event within a room, user ID) is going to be sent over Matrix,

i.e. via message event, and
- unless breaking user intent, i.e. manually pasted links would not convert while tab-completed IDs would.

Features such as "share room by link" or a generic "right click to copy link" remain unchanged, since falling back to
the <https://matrix.to> web service remains reasonable outside of Matrix until browsers and/or operating systems widely
implement a default handler for `matrix:` to an appropriate onboarding experience.

This proposal is submitted in the hope that it supports the blanket adoption of `matrix:` URIs to work towards the
greater goal of maximising decentralisation per the [Matrix Manifesto](https://matrix.org/foundation/about/).

## Potential issues

There might be "growing pains" as implementing this MSC effectively forces the ecosystem to at least support parsing
`matrix:` URIs. In reality, most clients already support this as of today.

@HarHarLinks HarHarLinks Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

matrix URI (room alias) client support:

  • Nheko 0.12.1-1f083e25: supports both plain text and html formatted
  • Element web 1.12.20: plain text does not pillify and opens matrix.to instead (wtf??? this regressed from 1.11.112), HTML link pillifies and routes internally
  • fractal 13: supports both plain text and html formatted with pillification
  • SchildiNext 0.11.3-test3 (based on Element X 26.05.2) with message renderer rewrite enabled: plain text does not pillify nor linkify properly, HTML link does not pillify but offers to "open with" any installed Matrix client that registered the scheme, including itself
  • Element X Android 26.05.2: plain text does not pillify nor linkify properly, HTML link pillifies
  • Fluffychat 2.6.0: ?
  • Cinny v4.12.2: neither are supported
  • Polycule $current: ?
  • Tammy 2.0.6: supports both plain text and html formatted with pillification

@SpiritCroc SpiritCroc Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW SchildiChat Revenge recently got matrix URI (plaintext) linkification and deeplinking support (to be released soon), just need to bump the message formatting library on Next to get linkification and in-app navigation on that as well

@pixlwave pixlwave Jun 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Element X 26.05.2: plain text does not pillify nor linkify properly, HTML link pillifies

There might be a discrepancy between iOS and Android here - plain-text URIs will link & pillify as expected on iOS.

@HarHarLinks HarHarLinks Jun 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I clarified Android above!

@KitsuneRal KitsuneRal Jun 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The matrix URI scheme has had first-class support in Quotient-based clients (Quaternion and NeoChat) since 2021, ftr. Implementing this MSC is almost exactly down to changing a single default in the library for them.


## Alternatives

1. Use [plain IDs](https://spec.matrix.org/v1.18/appendices/#common-identifier-format) instead of `matrix:` URIs with the
RECOMMENDATION to display them as navigable UX (e.g. links, "pills").
2. The outcome of this MSC could be the decision to stay with the preference for matrix.to for the fallback-to-the-web
benefit even for what is supposed to be Matrix-internal communication, and live with the consequence of not reaching the
same level of deeplinking other platforms have.
3. A more radical approach to deprecate matrix.to not only internally, but also generally, would be possible. The author
believes the consequences of this would be too harsh, particularly towards onboarding, even though issues with the
current onboarding experience via <https://matrix.to> persist.

## Security considerations

None known.

## Unstable prefix

Not needed.

## Dependencies

None.
Loading