Skip to content
Open
Changes from all commits
Commits
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
131 changes: 131 additions & 0 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Contributor

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?


When you expect a feature to need to be extended over time,
Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

The 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,".

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* define how extensions are uniquely identified,

* 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
Copy link
Contributor

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* give each extension a unique name to use
in negotiation and
in recognizing what extension is in use,
* give each extension a unique identifier to use
either in negotiation or
in recognizing when an extension is in use,

Copy link
Contributor

Choose a reason for hiding this comment

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

Or

Suggested change
* give each extension a unique name to use
in negotiation and
in recognizing what extension is in use,
* create a place where extension developers can coordinate
the allocation of identifiers for their extensions,

With the above point about unique identifiers, above.

* provide a place to link to extension specifications
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* provide a place to link to extension specifications
* provide a place for implementers to find extension specifications

(if the registry requires this), and
* help readers find the name for a desired purpose.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* help readers find the name for a desired purpose.
* help readers discover when existing extensions address their needs.


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,
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
when they are a small set, wealthy, and generally-aligned,
when they are a small set, well-resourced, and generally-aligned,

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.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
At the limit, implementers might not even be willing to specify their extensions.
At the limit, implementers might not even be willing to document their extensions.

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,
Copy link
Contributor

Choose a reason for hiding this comment

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

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]],

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.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

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
Copy link
Contributor

Choose a reason for hiding this comment

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


<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
Copy link
Contributor

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

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

<!--
Expand Down