Recommend registries, and give some guidance on how to define them.

[jyasskin]

Here is a "define registries" principle, based on the discussion in Hong Kong last week. It will fix #583 once it's polished and merged.

---

Preview | Diff

[martinthomson]

What other mechanism do you think might be appropriate? What criteria do you think apply to the selection of process?

[jyasskin]

My thought here was that, if we were writing this several years ago I would have put just the IANA process here. When the W3C process arrived, I would have wanted it to be written in such a way that the W3C process were also acceptable. I don't know of another process that would fit now, but there's also no reason that only 2 organizations would be acceptable.

On the other hand, maybe this is an extensibility point for the design principles, and we can just update the design principles instead of defining a registry of registry mechanisms with criteria for adding new ones.

Suggested change

	Default to defining either
	an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
	but another similar mechanism is also acceptable.
	Default to defining either
	an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]].

[martinthomson]

The extension point that is governed by a registry needs to be fully-specified. That includes a definition of what to do if an item is not understood (is there a negotiation mechanism? is there feature detection? is the extension ignored when it is not understood? or, does it cause a failure of some sort?)

RFC 6709 goes into some detail about some of the extension models that might apply. Those are for protocols, but the same principles broadly apply to APIs as well.

Then, the requirements for what it takes to define the extension need to be clearly defined, as you say here.

[jyasskin]

I've rearranged some things to add this in, and to defer to RFC 6790 for details. How does it look?

[martinthomson]

This isn't quite the angle I'd use here. The extent to which you can add tighter constraints varies based on the ecosystem you are deploying into. If your implementers are browsers, then you might imagine that a tighter set of restrictions might be respected and therefore it would be more reasonable to at least try it on.

If you are looking at websites implementing, then you can almost guarantee that registrations won't happen, even if the constraints are very lightweight.

Getting that nuance in might be a good idea.

[jyasskin]

Good point. I replaced the tail of this paragraph with this discussion, and added a paragraph saying (roughly) that if this is likely, then it can justify a FCFS-with-no-spec policy.

[martinthomson]

Extensions for optional features - ones that are simply ignored if not understood - don't need this.

You should say that where the functioning of a specification depends on choosing and using an registered value, then you have three choices:

• One party implements all the options.
• You mandate a baseline that all parties implement.
• Risk interoperability failure if the intersection of options between entities is empty.

And that's for a two-party negotiation. There are many things that the W3C documents where there are more than two potential actors involved.

[jyasskin]

I tried to incorporate optional features.

I feel like we should only endorse one of your three choices:

• having 1 party implement all options means that party gets a veto on new options ... maybe it's saying that all values have to be marked as required for one side of the protocol so that the other side can make a free choice ... and in that case, values can only be added in a revision of the main spec, so it's not a registry anymore.
• the baseline is equivalent to requiring at least 1 entry
• We shouldn't endorse a plan that leads to interoperability failures.

[martinthomson]

XML namespaces use URIs (not URLs). They are not using URIs for their ability to resolve to something; most XML namespace URIs, if they are resolved, point to nothing useful. You seem to imply that they could point to something; some do, but that's never been the goal.

They use URIs because the domain into which they are being deployed does not benefit from centralized coordination. They need identifiers and a way to generate them without coordination or - save us all - namecoin-style consensus. Indeed, it would be a mistake to require centralized coordination for those (doubly so for a wasteful distributed consensus). XML is a file format that is used by many people for many reasons. There is no value in asking people to coordinate identifier allocation. The same applies to JSON-LD, for similar reasons ¹.

But the question we need to answer here is different. If you are specifying an extension to a protocol, why would you use a registry rather than letting the proverbial thousand flowers bloom? That all comes down to how you conceive of the interoperability goals of the extension point.

An optional, ignorable extension might benefit from a registry if there is a greater need to have different implementations agree on what the meaning of the extension is. In TLS, we have a registry for extensions, not just because there is a limited space available, but because the goal of defining an extension is to enable a shared understanding of the space.

In comparison, the IPTC metadata format uses URLs, because they don't see a need to constrain the space of options. There, the risk that people define multiple identifiers that are close, or even identical, in meaning is something that is tolerated so that there is a low-coordination way of adding metadata for limited or proprietary uses.

An extension point that determines everything that follows, like TLS ciphersuites or digital credential protocols, benefits more from coordination than something that can be readily ignored. Those are places where mandating implementation of a core by all (or a subset by browsers) is necessary.

Footnotes

1. Even if you don't think that JSON-LD is solving a problem that matters, this choice is not one that is really in contention, to my mind. ↩

[annevk]

XML namespaces use strings that by convention often look like URLs and might parse as one, if we're going to quibble about details.

[jyasskin]

After some of the rewrites above, the paragraph about URIs/URLs wound up fitting in as a thing one might do if the alternative is a specification-less registry. They're hierarchical in the IETF sense, but they also tend to risk a DNS entry being bought out from under the original creator. And they're usually more bytes than really necessary, but that's petty and I didn't find a convenient way to work it in.

The IPTC example seems like a case where they should have defined the main terms in the main spec, or possibly done a hierarchical space where each "Recommended/used Prefix" is controlled by a particular entity.

Or are you thinking that we should call out the case of enabling local/proprietary extensions as a time when URLs are actually the right way to go?

[martinthomson]

That's not interoperability in the sense that we should care about here.

https://www.w3.org/TR/ethical-web-principles/#oneweb

[jyasskin]

I'm happy to drop this sentence, although DIDs might be an example where there are many specifications (protocols) that have fields in which a DID could appear, and each of those specifications needs to mandate at least 1 DID Method to be implemented, but not all of those specifications need to agree on the same Method. I don't think that would violate the One Web principle, although it also wouldn't be ideal.

[jyasskin]

Sorry for the long delay. How's it look now?

[jyasskin]

My thought here was that, if we were writing this several years ago I would have put just the IANA process here. When the W3C process arrived, I would have wanted it to be written in such a way that the W3C process were also acceptable. I don't know of another process that would fit now, but there's also no reason that only 2 organizations would be acceptable.

On the other hand, maybe this is an extensibility point for the design principles, and we can just update the design principles instead of defining a registry of registry mechanisms with criteria for adding new ones.

Suggested change

	Default to defining either
	an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
	but another similar mechanism is also acceptable.
	Default to defining either
	an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]].

[jyasskin]

I've rearranged some things to add this in, and to defer to RFC 6790 for details. How does it look?

[jyasskin]

Good point. I replaced the tail of this paragraph with this discussion, and added a paragraph saying (roughly) that if this is likely, then it can justify a FCFS-with-no-spec policy.

[jyasskin]

I'm happy to drop this sentence, although DIDs might be an example where there are many specifications (protocols) that have fields in which a DID could appear, and each of those specifications needs to mandate at least 1 DID Method to be implemented, but not all of those specifications need to agree on the same Method. I don't think that would violate the One Web principle, although it also wouldn't be ideal.

[jyasskin]

I tried to incorporate optional features.

I feel like we should only endorse one of your three choices:

• having 1 party implement all options means that party gets a veto on new options ... maybe it's saying that all values have to be marked as required for one side of the protocol so that the other side can make a free choice ... and in that case, values can only be added in a revision of the main spec, so it's not a registry anymore.
• the baseline is equivalent to requiring at least 1 entry
• We shouldn't endorse a plan that leads to interoperability failures.

[jyasskin]

After some of the rewrites above, the paragraph about URIs/URLs wound up fitting in as a thing one might do if the alternative is a specification-less registry. They're hierarchical in the IETF sense, but they also tend to risk a DNS entry being bought out from under the original creator. And they're usually more bytes than really necessary, but that's petty and I didn't find a convenient way to work it in.

The IPTC example seems like a case where they should have defined the main terms in the main spec, or possibly done a hierarchical space where each "Recommended/used Prefix" is controlled by a particular entity.

Or are you thinking that we should call out the case of enabling local/proprietary extensions as a time when URLs are actually the right way to go?

[matatk]

This is great.

Do you think that some concrete examples might help?

In terms of positive examples, there are a few that seem to work well, including: link types/rel attribute values, and Well-known URIs.

But are there any non-contentious, and preferably not recent, examples of where a registry was implemented, but wasn't a good idea, or was decided against?

[jyasskin]

Examples could help. Some that come to mind:

• link relations, whose registry is a combination of https://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1 and https://microformats.org/wiki/existing-rel-values, with browser behavior defined by https://html.spec.whatwg.org/multipage/links.html#linkTypes on a subset of the relations.
• Media types, which initially had an onerous registration procedure (https://www.mnot.net/blog/2003/08/23/registering_media_types) and were significantly relaxed in RFC 6836 in 2013 with the addition of the provisional registration type and the https://www.iana.org/form/media-types form.

[jyasskin]

I ran out of time to write up both examples this week, but the Link Relations registry turns out to be pretty instructive: https://pr-preview.s3.amazonaws.com/jyasskin/design-principles/pull/596.html#example-link-relation-registry.

[martinthomson]

Is this really the right title now that you have done the work to change the focus?

[martinthomson]

This needs a punchy "Use an appropriate mechanism to manage the future extensibility of your work." Or similar.

[martinthomson]

This paragraph isn't really about the expectation that extensions might be needed, but about keeping control within the group that defined the original feature. To that end, it belongs with the previous paragraph. I'd still use a new paragraph, but use a bridging statement, not something like what you have here, which implies the situation is very different.

[martinthomson]

If the substance of this section, the thing introducing it shouldn't start with "However,".

Where there is strong reason to believe that a feature will be used and extended by a diverse set of users, including those who might not be involved in its original creation, a registry is usually the right way to manage extensibility.

A registry is a central location for identifying and managing extensions. Registries can be defined as a [[...|W3C Registry]], where the W3C as a whole, often delegated to a working group, is responsible for the maintenance of the registry. IANA might also be asked to establish and maintain registries, following the procedures in [[RFC8126]].

[martinthomson]

These two points are an "or" situation. If you negotiate, then you might never have to deal with unrecognized extensions, except to the extent they might be mentioned in negotiation. Or, you might not negotiate, in which case you might need to deal with unrecognized extension in different places.

[martinthomson]

Suggested change

	URIs are appropriate for a few kinds of very-low-coordination extension,
	URIs are appropriate for a few kinds of very-low-coordination extension,
	such as the definition of an XML namespace [[XML-NAMES]],

[martinthomson]

Suggested change

	any new registry should start with at least 2-3 entries defined.
	any new registry should start with more than one entry defined.

[martinthomson]

Suggested change

	Each of these initial registry entries
	can be either required or optional for implementations to recognize.
	For extension points that can't just be ignored when their extension isn't recognized,
	the registry should include at least 1 required entry.
	Specifications that include extension points for mandatory features,
	such as a core function that can have an alternative implementation
	that is selected by identifying the extension,
	must include at least one entry that all implementations are required to support.

I think that you are referring here to DC and the protocol choice. But this also applies to TLS key exchange methods or cipher suites. You don't have a functional specification if you don't at least one thing that everyone supports.

[martinthomson]

Interesting. The RFC 8288 link goes to the actual section. The same is not true for https://datatracker.ietf.org/doc/html/rfc8288#procedure though that is where I would expect many RFC links to use. (Failing that: https://www.rfc-editor.org/rfc/rfc8288.html#procedure)

[martinthomson]

I sort of agree with this statement, though this entire example makes me a little uncomfortable. It is not exactly a simple and straightforward example that illustrates the principles on hand. Instead, it's a complicated situation that has evolved over time, mostly as an object lesson in how NOT to do registries.

So, while I appreciate the history lesson, I'm not sure that we're doing our readers the favour that they came here for. We're unloading a lot of nuance on them instead.

Do we have a simple, relatively old, straightforward registry that we can point to? I can point to a lot of IETF work that fits that neatly, but I'm less able to point to a good example from the W3C. That might say something, of course.