From d8d2d65c936ef670ef7fba2255f0d122bc896f2d Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Sun, 21 Sep 2025 21:12:07 +0000 Subject: [PATCH] Recommend registries, and give some guidance on how to define them. --- index.bs | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/index.bs b/index.bs index 29be67e4..31f8ed62 100644 --- a/index.bs +++ b/index.bs @@ -3567,6 +3567,80 @@ and makes it clear when the state described by the flags is reset. +

Use registries to allow constrained extensions outside the original standards track

+ +When you expect a feature to need to be extended over time, +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. +In this case, the right plan is often to +have the original standards body continue or restart +a working group to produce an update to the feature's full specification. + +However, if extensions need to be defined through +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]], +but another similar mechanism is also acceptable. + +Registries are helpful because they + +1. Reduce name collisions. +1. Help readers find the name for a desired purpose. +1. Direct readers to a specification for each name + (if the registry requires this). + +Items in a registry generally need to implement a defined interface +in order to plug into the specification they're extending. +The definition of the registry must be clear about this interface, +and it should require new entries to include a specification that follows it. +This roughly corresponds to +the IETF's [[RFC8126#section-4.6|Specification Required]] registration policy. +It's difficult to be confident in an interface definition +before that interface has several implementations, +so any new registry should start with at least 2-3 entries defined. + +It is tempting to additionally require that registry entries be +"good" in some way beyond simply being specified. +Use a permissive registration policy instead of doing this +unless the feature includes +some way to enforce that no implementation can use an unregistered name. +The IETF has found that +when it's too hard to add entries to a registry, +implementers will often simply use names without registering them. + +When a feature's main specification defines some initial registry entries, +each one can be either required or optional for implementations to recognize. +If implementations need to pick an understood registry entry to send to their recipients, +then the registry should include at least 1 required entry. +If implementations can be +divided into distinct [[spec-variability#subdivision-profile|profiles]] +that tend not to need to communicate with other profiles, +it can be sufficient for each profile to require a registry entry +even if the main specification leaves them all optional. + +It can be tempting to use URLs instead of registered strings to identify extensions. +This has the benefit of making it very easy to extend the feature, +by just picking a URL from a domain that the extender controls. +However, there's no way to ensure that +these URLs point to a specification for the extension they name, +or even that the domain stays under the control of the entity that defined the extension. +URLs are appropriate for a few kinds of completely-permissionless extension, +but most of the time a WG-managed permissive registry table will work better. + +See [[qaframe-spec#extensions]] for +more guidance on how to design extensibility. +

Resolving tension between interoperability and implementability