matrix-org / matrix-org/matrix-spec

Expose metadata about a homeserver, useful for server discovery and general experience

Open
#1,258 5 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-Client-Server improvement
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

## Context

I was thinking about the way the Mastodon community handled the general server discovery issue, and if we could profit from that. Generally speaking, the problem was solved late on Mastodon and two separate mechanism are in place:
- metadata exposed by a server (user count, owner contact, description, etc.)
- metadata declared on ``instances.social``.

Unfortunately, the declarative bit is what causes most of the bias and I read that most Mastodon users where either choosing a server recommended by a friend/community/company/whatever, which is good, or one of the flagship instances, which is less good for distribution.

## Goals

I think it would bring some consistency to the Matrix federation if we could have the following set of resulting properties:
- users can chose a homeserver based on various types of criteria (ideological, geographical, etc.)
- users do not have to worry too much about reliability or security, unless they explicitely ask about it
- users have a generic way of contacting their homeserver admins or technical support (see matrix-org/matrix-spec#1257)
- homeserver owners can make announcements to their community of users
- homeserver owners can discover similar servers and contact their owners

## Technical implementation

I think all of the goals can be met with a single and pretty simple feature: a client/server API endpoint that displays the server metadata. These metadata could be setup in configuration first, and simply displayed as a JSON dictionary. All fields would be optional of course.

Some of the metadata would be normalized, including:
- the main language code,
- the country codes for where data is hosted,
- the type of structure managing the server (foundation, company, etc.)
- whether or not registration is public,
- whether or not registration requires interaction with the technical support,
- whether or not this homeserver should be displayed in public lists (see later, and that could also apply to Voyager or similar projects)
- whether or not this homeserver provides commercial support,
- a level of confidence the admins have in their server,

Some fields would have a more flexible form:
- the list of homeservers managed by the same entity,
- the list of optional features provided, with codenames maybe (bridges, turn, web client, etc.) and probably a way to display a related resource (address of the web client for instance)
- the list of contacts, per contact type (administrative, technical, legal, commercial), could be displayed as a dictionary where keys are normalized, and values could be mxids, room aliases, email addresses or Web addresses; this would include the project website (commercial url) as well as an emergency email address for legal requests,
- the list of entrypoints for discovering the community (basically structured list of rooms and users that would generate the homepage)
- the markdown description of the instance (limited length?)
- the markdown text including an ethical statement/set of rules for the homeserver (limited length?)
- a list of free tags for later searches (political, ideological, community names, etc.)

Regarding announcements, I was simply thinking that among contact points, there could be a "communication" type, and that clients could suggest the user joins that room for announcements. Or maybe the client could silently join that room and display messages in a special way that makes them look a bit more like announcements.

## Resulting experience

Matrix clients could first display relevant metadata to the users of a homeserver, for instance contacts could be included on the homepage, as well of the entrypoints that currently make the list of general purpose rooms. If the homeserver becomes unavailable, the client could display technical contact information, when reporting an illegal message, the client could display legal contacts, etc.

On top of that, a third party, or many third party fwiw, could build an instance list without the homeserver owners having to explicitely register, thanks to the flag that tells whether or not the server should be publicly listed. These lists could be consolidated with technical data, including the current server version, average response time from various places in the world, average reliability, and basically everything that [Hello Matrix](https://www.hello-matrix.net/public_servers.php) has been doing for some time now.

Finally, clients could use those lists and consolidated meta to perform searches. Then, upon registration, the user could be greated with a couple fields to fill in, then a list of candidate servers.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No file, test, or implementation entry point is named. Start by reviewing the proposed client/server API endpoint, the metadata categories in this issue, and the related matrix-org/matrix-spec#1257 discussion. Done would require an agreed metadata schema and endpoint specification rather than only a list of possible fields.

Written by the indexing model from the issue text.

Assessment

Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.