MSC4518: Registries

[turt2live]

Rendered

---

SCT Stuff:

MSC checklist

FCP tickyboxes

[turt2live]

Implementation requirements:

• Ideally 2+ MSCs wanting to use this

[turt2live]

#4519
#4456

[erikjohnston]

Mostly looks sane, though I have a few concerns with it as drafted.

[turt2live]

MSCs proposed for Final Comment Period (FCP) should meet the requirements outlined in the checklist prior to being accepted into the spec. This checklist is a bit long, but aims to reduce the number of follow-on MSCs after a feature lands.

SCT members: please check off things you check for, and raise a concern against FCP if the checklist is incomplete. If an item doesn't apply, prefer to check it rather than remove it. Unchecking items is encouraged where applicable.

MSC authors: feel free to ask in a thread on your MSC or in the#matrix-spec:matrix.org room for clarification of any of these points.

• Are appropriate implementation(s) specified in the MSC’s PR description?
• Are all MSCs that this MSC depends on already accepted?
• For each new endpoint that is introduced:
  • Have authentication requirements been specified?
  • Have rate-limiting requirements been specified?
  • Have guest access requirements been specified?
  • Are error responses specified?
    • Does each error case have a specified errcode (e.g. M_FORBIDDEN) and HTTP status code?
      • If a new errcode is introduced, is it clear that it is new?
• Will the MSC require a new room version, and if so, has that been made clear?
  • Is the reason for a new room version clearly stated? For example, modifying the set of redacted fields changes how event IDs are calculated, thus requiring a new room version.
• Are backwards-compatibility concerns appropriately addressed?
• Are the endpoint conventions honoured?
  • Do HTTP endpoints use_underscores_like_this?
  • Will the endpoint return unbounded data? If so, has pagination been considered?
  • If the endpoint utilises pagination, is it consistent with the appendices?
• An introduction exists and clearly outlines the problem being solved. Ideally, the first paragraph should be understandable by a non-technical audience.
• All outstanding threads are resolved
  • All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative
• While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely:
  • Introduction
  • Proposal text
  • Potential issues
  • Alternatives
  • Dependencies
• Stable identifiers are used throughout the proposal, except for the unstable prefix section
  • Unstable prefixes consider the awkward accepted-but-not-merged state
  • Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”).
• Changes have applicable Sign Off from all authors/editors/contributors
• There is a dedicated "Security Considerations" section which detail any possible attacks/vulnerabilities this proposal may introduce, even if this is "None.". See RFC3552 for things to think about, but in particular pay attention to the OWASP Top Ten.

[turt2live]

Having addressed primarily Erik's review, I think this is ready to enter FCP.

@mscbot fcp merge

[mscbot]

This FCP proposal has been cancelled by #4518 (comment).

Team member @mscbot has proposed to merge this. The next step is review by the rest of the tagged people:

• @clokep
• @dbkr
• @uhoreg
• @turt2live
• @ara4n
• @anoadragon453
• @richvdh
• @tulir
• @erikjohnston
• @KitsuneRal

Once at least 75% of reviewers approve (and there are no outstanding concerns), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for information about what commands tagged team members can give me.

[HarHarLinks]

This appears to be out of scope or I didn't understand if the intention was to include this, but anyway it's related enough to ask here: has the author/SCT considered indexing entirely off-spec registries as well? E.g. could say Nordeck establish a registry of Nordeck widget event types, or gematik a registry of medical event types, or FITKO of administration event types, etc, that would end up listed on spec.matrix.org in the interest of increasing discoverability.

[turt2live]

The overall intention is that registries are used for specified features, not for off-spec things. However, the event types registry, when/if it exists, would likely support all of your examples. Where things don't fit in a registry and aren't destined for the main spec itself, the intention is that those external parties create their own specification and publish it external to Matrix.

[clokep]

These don't really sound "implementation-specific"? I'm a bit confused by the rationale here.

[turt2live]

I did struggle to define what this stuff is: alternative wording suggestions are welcome. The general idea is we probably won't put livekit into the main spec, nor would we put org.example.xray event types into the main spec. We would instead put them somewhere else for the main spec to reference ("hey, if you want to do VoIP, check out the transports registry for common transports").

[Johennes]

I can see how "implementation-specific" could be misinterpreted. In my mind, what we could use registries for are features that are too specialized to be included in the main spec but used widely enough to make a plain unmerged MSC insufficient for coordinating compatibility. Maybe something like this would help express that?

Suggested change

	As Matrix continues to grow and expand its capability, there is increased want for a structured place
	to put coordinated implementation-specific details. For example, event types which cover a feature
	that wouldn't necessarily be accepted into the "main" spec, transport options for VoIP media, or a
	set of common identifiers which aren't explicitly needed in Matrix itself.
	As Matrix continues to grow and expand its capability, there is increased want for a structured place
	to coordinate details of features that are too specialized to warrant inclusion in Matrix itself but have
	a large enough user base to require coordination in a more regulated form than a plain unmerged MSC.
	Examples for this include event types that wouldn't necessarily be accepted into the "main" spec (such
	as the FHIR events from [MSC4302]), transport options for VoIP media, or a set of common identifiers
	which aren't explicitly needed in Matrix itself.
	[MSC4302]: https://github.com/matrix-org/matrix-spec-proposals/pull/4302

[HarHarLinks]

I am increasingly confused about what ridge this MSC is trying to walk. The spec leading me to discover an SCT-sanctioned list of VoIP transports sounds very in-spec to me, except with less bureaucracy to update said list.

[richvdh]

Honestly I'm finding this a bit hard to draw any conclusions over. Everything of value seems to be left up to the MSC that introduces the actual registry (which I think is fine). It ends up feeling like a rather process-heavy way to say "MSC4519 is allowed to add a section to the Appendices and define how it will be maintained".

On which basis: no objections, but I feel like we could live without an MSC to do this. Let MSC4519 do its thing, and we'll learn from it and apply any conclusions next time we want to do something similar (MSC4456, I guess).

Perhaps I'm missing something though. In fairness I think I missed the SCT meeting when this idea was discussed.

[turt2live]

The end goal here is to not use appendices, but rather something adjacent. It's certainly nuanced, but I think an MSC for this is important to get broad agreement that we're okay with the concept of registries.

Registries shouldn't be any more process heavy than the rest of the spec. If we want to do different though, that's where commentary on this MSC is important.

[richvdh]

It's certainly nuanced, but I think an MSC for this is important to get broad agreement that we're okay with the concept of registries.

I find it very hard to have an opinion on this in the abstract. Feels like the devil is in the detail, and there is no detail here.

[turt2live]

I don't feel it's fair to say there's no detail - time has been put into trying to collect the wide range of opinions and thoughts into something workable. If more detail is required in particular places, happy to add it, but it's hard to respond to "fix all of it".

[Johennes]

I think for practical reasons we should probably consider this and #4519 in tandem rather than in isolation. In hindsight, one MSC might have sufficed but I think this proposal still helps in fleshing out a joint understanding of registries and help decide whether we want to pursue this path or not.

For added context, some of the core ideas came out of conversations between the VoIP and backend teams at Element and @turt2live thankfully volunteered to codify the thoughts into MSC(s) to help us move things along.

[richvdh]

I don't feel it's fair to say there's no detail - time has been put into trying to collect the wide range of opinions and thoughts into something workable.

I appreciate that you've put a bunch of time and effort into this, and it certainly wasn't my intention to belittle that -- apologies if it came across that way.

But it's precisely because you've detailed a bunch of different options and opinions that I'm finding it hard to reach a conclusion on this MSC. Effectively, the MSC says "We could do A, or B, or C, or D," and -- particularly without concrete examples of how any of those options might best be used -- I find each of those options hard to picture.

[Johennes]

I think there's a word missing here?

Suggested change

	The main specification continues to describe namespacing characteristics of its fields, including
	whether it uses a registry. When a registry is used is not strictly defined, but are most useful to
	describe allowed extensions, such as event types and VoIP transports. Registries MUST NOT be used to
	record required functionality, like join rules.
	The main specification continues to describe namespacing characteristics of its fields, including
	whether it uses a registry. When a registry is used is not strictly defined, but registries are most useful to
	describe allowed extensions, such as event types and VoIP transports. Registries MUST NOT be used to
	record required functionality, like join rules.

[Johennes]

This appears to be at odds with the requirement for SCT involvement from above?

If the curation happens outside of the MSC process, SCT review MUST happen elsewhere in that curation process.

[turt2live]

Per SCT internal discussion, we do not believe this is required for Matrix 2.0. It also likely needs more thought, so:

@mscbot fcp cancel