-
Notifications
You must be signed in to change notification settings - Fork 54
Recommend registries, and give some guidance on how to define them. #596
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.
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
base: main
Are you sure you want to change the base?
Changes from all commits
6d8190a
d661fde
1a463d0
5546077
9b4f6fb
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -3708,6 +3708,137 @@ and makes it clear when the state described by the flags is reset. | |||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| <!-- TODO: add examples --> | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| <h3 id="registries">Use registries to allow constrained extensions outside the original standards track</h3> | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| When you expect a feature to need to be extended over time, | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This needs a punchy "Use an appropriate mechanism to manage the future extensibility of your work." Or similar. |
||||||||||||||||||||||||
| and it would be inappropriate to | ||||||||||||||||||||||||
| manage that change through the same standards process that defined the original feature, | ||||||||||||||||||||||||
| then a registry is usually the right design. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| [[spec-variability#variability|"Variability complicates interoperability."]] | ||||||||||||||||||||||||
| When a feature needs optional components, | ||||||||||||||||||||||||
| it is easiest to manage the complication if | ||||||||||||||||||||||||
| a single group is in charge of the whole design. | ||||||||||||||||||||||||
| This implies that most optional features should be defined | ||||||||||||||||||||||||
| in the same specification that defined the original feature. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Sometimes new extensions are expected to be needed in the future. | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||||||||||||||||||||
| It is often most appropriate | ||||||||||||||||||||||||
| to have to revise the specification to define an extension. | ||||||||||||||||||||||||
| This can reduce or avoid any need to precisely define requirements for extensions. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| However, if extensions need to be defined through | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If the substance of this section, the thing introducing it shouldn't start with "However,".
|
||||||||||||||||||||||||
| a different process than updating the full specification, | ||||||||||||||||||||||||
| a registry is usually the right way to manage the known extensions. | ||||||||||||||||||||||||
| Default to defining either | ||||||||||||||||||||||||
| an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]]. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| The place in a specification that dispatches to an extension's implementation | ||||||||||||||||||||||||
| is known as an <dfn export>extension point</dfn>. | ||||||||||||||||||||||||
| To maximize the chance that a specification with extension points is interoperably implemented, | ||||||||||||||||||||||||
| each extension point should | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
| * define how implementations can negotiate which extensions are acceptable, | ||||||||||||||||||||||||
| * define what to do with unrecognized extensions | ||||||||||||||||||||||||
| (see [[RFC6709#section-4|section 4 of RFC6709]]), | ||||||||||||||||||||||||
|
Comment on lines
+3741
to
+3743
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||||||||||||||||||||
| * define what interface extensions are supposed to implement, and | ||||||||||||||||||||||||
| * link to a specification of each extension that is | ||||||||||||||||||||||||
| detailed enough to support interoperable implementations of the extension, | ||||||||||||||||||||||||
| as is required by | ||||||||||||||||||||||||
| the IETF's [[RFC8126#section-4.6|Specification Required]] registration policy. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Registries help because they | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| * give each extension a unique name to use | ||||||||||||||||||||||||
| in negotiation and | ||||||||||||||||||||||||
| in recognizing what extension is in use, | ||||||||||||||||||||||||
|
Comment on lines
+3752
to
+3754
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Or
Suggested change
With the above point about unique identifiers, above. |
||||||||||||||||||||||||
| * provide a place to link to extension specifications | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
| (if the registry requires this), and | ||||||||||||||||||||||||
| * help readers find the name for a desired purpose. | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| It is tempting to additionally require that registry entries be | ||||||||||||||||||||||||
| "good" in some way beyond what is needed to achieve interoperability. | ||||||||||||||||||||||||
| Whether this can succeed depends on the ecosystem and the expected implementers. | ||||||||||||||||||||||||
| Implementers are most likely to be willing to | ||||||||||||||||||||||||
| navigate a demanding registration process and | ||||||||||||||||||||||||
| constrain their implementations to match strict registration requirements | ||||||||||||||||||||||||
| when they are a small set, wealthy, and generally-aligned, | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
| as in the case of web browser engines. | ||||||||||||||||||||||||
| The more diverse or constrained implementers become, | ||||||||||||||||||||||||
| the less you can expect them to consistently work to register extensions. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| At the limit, implementers might not even be willing to specify their extensions. | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
| If the specification authors consider this likely, it may be worth allowing | ||||||||||||||||||||||||
| [[rfc8126#section-4.4|first-come-first-served registrations without a specification]] | ||||||||||||||||||||||||
| just to reduce the risk of name collisions, | ||||||||||||||||||||||||
| although the registry should still encourage full specifications. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| In the case of a registry that doesn't require specifications, | ||||||||||||||||||||||||
| it can be tempting to identify extensions with URLs or URIs instead of registered strings. | ||||||||||||||||||||||||
| This has the effect of defining a [[rfc8126#section-4.3|hierarchical registration policy]] | ||||||||||||||||||||||||
| and making it very easy to extend the feature, | ||||||||||||||||||||||||
| by just picking a URL from a domain that the extender controls. | ||||||||||||||||||||||||
| This clearly loses the interoperability benefits of requiring a specification, | ||||||||||||||||||||||||
| and in the case of DNS-based URLs, | ||||||||||||||||||||||||
| it also risks that the entity that defined the extension may lose control of its domain. | ||||||||||||||||||||||||
| URIs are appropriate for a few kinds of very-low-coordination extension, | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
| but most of the time a WG-managed permissive registry table will work better. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Because an [=extension point=] defines an interface, | ||||||||||||||||||||||||
| and it's difficult to be confident in an interface definition | ||||||||||||||||||||||||
| before that interface has several implementations, | ||||||||||||||||||||||||
| any new registry should start with at least 2-3 entries defined. | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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. | ||||||||||||||||||||||||
|
Comment on lines
+3791
to
+3794
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
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. |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| <div class="example" heading="Link Relations" id="example-link-relation-registry"> | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Link relations are currently registered in a 3-part registry. | ||||||||||||||||||||||||
| [[rfc8288#procedure|RFC 8288]] defines the [[IANA-RELATIONS inline]] registry | ||||||||||||||||||||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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) |
||||||||||||||||||||||||
| which accepts entries that "reference a freely available, stable specification." | ||||||||||||||||||||||||
| [[MFREL inline]] defines a second registry | ||||||||||||||||||||||||
| to which anyone with a wiki account can add. | ||||||||||||||||||||||||
| This registry has a column for specifications, | ||||||||||||||||||||||||
| but nobody enforces that the column is filled in | ||||||||||||||||||||||||
| or that the specifications meet any particular quality requirements. | ||||||||||||||||||||||||
| [[html#linkTypes]] then repeats a subset of these relation types | ||||||||||||||||||||||||
| to define how they work in web browsers. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| In an ideal world, [[RFC8288]] and [[MFREL inline]] would probably be a single registry, | ||||||||||||||||||||||||
| with [[html#linkTypes|HTML]] defining browser behavior. | ||||||||||||||||||||||||
|
Comment on lines
+3809
to
+3810
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||||||||||||||||||||||||
| The current split is probably due to mistakes in the historical registry requirements. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| The idea of <{a/rel}> as list of externally-defined keywords | ||||||||||||||||||||||||
| dates to at least [[rfc1866 inline obsolete]], in 1995, which said | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| > The REL attribute gives the relationship(s) described by the hyperlink. | ||||||||||||||||||||||||
| > The value is a whitespace separated list | ||||||||||||||||||||||||
| > of relationship names. The semantics of link | ||||||||||||||||||||||||
| > relationships are not specified in this document. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| The [[html401 inline]], in 1999, | ||||||||||||||||||||||||
| defined a list of [known link relations](https://www.w3.org/TR/html401/types.html#type-links) | ||||||||||||||||||||||||
| but continued to encourage authors to invent their own. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| The IETF eventually defined the IANA registry in [[rfc4287 inline]], in 2005, | ||||||||||||||||||||||||
| and [[rfc5988 inline obsolete]], in 2010. | ||||||||||||||||||||||||
| These required specifications and expert review, | ||||||||||||||||||||||||
| but by this time too many custom link relations were in use | ||||||||||||||||||||||||
| to get them all specified and registered. | ||||||||||||||||||||||||
| Even if the registry had been in place from the beginning, | ||||||||||||||||||||||||
| we believe this is a case where implementers are too diverse | ||||||||||||||||||||||||
| to even know what kind of specification to expect for registered elements. | ||||||||||||||||||||||||
| The modern [[html#linkTypes|HTML]] table | ||||||||||||||||||||||||
| is a good way to align browser implementations | ||||||||||||||||||||||||
| on the subset of link relations that they react to. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| </div> | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| See [[qaframe-spec#extensions]] and [[RFC6709]] for | ||||||||||||||||||||||||
| more guidance on how to design extensibility. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| <h3 id="implementability">Resolving tension between interoperability and implementability</h3> | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| <!-- | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this really the right title now that you have done the work to change the focus?