Early draft of "best practices for registries"

Technical specifications for languages, formats and protocols make use
of identifiers -- names chosen from a set of values.  In many cases,
there are parameters or values which are allowed as extensibility
points, where the interpretation of the value cannot be directly
determined by the specification and the value itself... instead the
meaning is to be discovered by some other process.

To contrast a "direct" value from an "enumerated value"

For example:
  Color chosen from a set of color names:
        (purple, orange, light yellow, red ...)
the names "purple" "orange" "light yellow" are enumerated values.

While
  Color supplied by three values (R, G, B), e.g.:  11,24,255

the values 11, 24, 255 have a direct value.

Technical specifications intended as long-lived standards often
provide extensibility points which allow new identifiers and values to
be used, such that even after the language, protocol, or format has
been defined and deployed, new values may be assigned, without
updating the protocol standard or specification, or creating a new
version of the specification and the concurrent cost of
protocol/format version management.

There are a variety of ways of managing extensibility of sets of
enumerated values, and establishing a mechanism for introducing
private and/or public extensions.

* Requiring extensions names to be named by URIs, with
  the URI itself providing a mechanism for determining
  the "meaning" of the extension (cf. httpRange-14).
* Establishing a registry maintained by a registry organization
* Allowing organizations ("vendors") to create registries
  and descriptions of extensions, and then naming those
  extensions using a short prefix for the organization
  (a "vendor prefix").


updating the protocol standard or specification, or creating a new
version of the specification and the concurrent cost of
protocol/format version management.

There are a variety of ways of managing extensibility of sets of
enumerated values, and establishing a mechanism for introducing
private and/or public extensions.

* Establishing a registry maintained by a registry organization
* Requiring extensions names to be named by URIs, with
  the URI itself providing a mechanism for determining
  the "meaning" of the extension. [ref httpRange-14]
* Allowing organizations ("vendors") to create registries
  and descriptions of extensions, and then naming those
  extensions using a short prefix for the organization
  (a "vendor prefix").

Additional means of combining these in a meaningful way 
are possible; for example, XML namespaces [ref] allows 
the definition of identifiers in a self-describing way
such that the space of extensibility points (within a namespace)
is idnetified by a URI.

This document is about best practices for using registries.

A registry consists of the documentation for a set of registered
values and their meaning, where the registry maintained by an
organization (the registrar) with a commitment to maintain the
registry and make it publically available.

To ensure that quantities have consistent values and interpretations
across all implementations, their assignment must be administered by
an "authority": an organization or consortium which manages the values
and insures proper administration.

The Internet Assigned Numbers Authority (IANA)[ref] is the primary
organization whose charter and purpose is to maintain registries of
values needed for Internet protocols and languages as defined by the
IETF.[ref BCP from which this was quoted]

IANA administers the registry of many parameters in the core of the
Web architecture: the space of URI (and IRI) scheme names, the space
of media type identifiers ("MIME types"), a registry of HTTP protocol
header values, HTTP result codes, names of character sets and
character encoding schemes (charsets) and so forth.

The architecture of the world wide web relies on extension points
using "registration", even in W3C-specified protocols, languages, and
formats which are not reviewed or published within the IETF.

... more stuff? ...
... talk about vendor prefixes? ...
... case histories of non-IANA registries in W3C protocols? ...

FINDINGS:

Finding.explicit:
*  Any extensibility points in a W3C specification MUST be
  explicit about the method and management of the registration 
  of new values in a public, fair, and transparent way.

Finding.use-URIs:  
* The simplest and most effective way of providing extensibility
  is to use the space of URIs as the way of naming individual
  extensibility points, and the "meaning" of the URI as a way of
  discovering what the value means. 

... recommend http: URIs? ...

Finding.use-Namespaces-or-prefixes:  
  
* In some situations, registration of individual extensibility points
  is awkward or cumbersome, and instead a set of extensibility names
  are defined using

  * namespaces (in XML)
  * vendor prefixes
    (a company or organization can define its own extensibility
    points with a registry or set of assumptions about the vendor
    prefix space).
  
... do we recommend one over the other? ...

Finding.use-IANA:  
  
* W3C specifications SHOULD use IANA registration methods 
  for those extensibility points which are shared with other
  (IETF-managed) application protocols, rather than inventing their
  own extensibility points.

The "best current practice" specification in IETF BCP 26:
  http://tools.ietf.org/html/bcp26 [RFC 5226]
gives guidelines to protocol designers for establishing the registry
rules associated with an IANA registry. Note that IANA acts as the
operator of each registry, but itself does not evalute registry
requests, but merely adminmisters a process by which the organization
or individuals authorized to review or approve registry entries are
accepted. These guidelines apply to IANA namespaces established or
requested by W3C working groups or task forces.

For extensibility points which are named by URIs, the "URN" mechanism
provides a way of registration using a URI-named extensibility point.
... some IETF specs use URNs as a way of combining registry
    and URI ...


Sniffing, "Willful Violations", Incomplete Inaccurate Registries

In some cases, community practice has evolved and the registries have
not followed: the registries have not tracked the use of extensibility
parameters, or where extensibility values are often ignored. In some
cases, the registry is percieved as a bottleneck.

Sniffing: the registry has not tracked, or the right extensibility
parameter is not used. [ref mime-sniff]

"willfull violations": the registry values have been misused,
and the technical specification contains new values that do not
agree with the registry.

Finding.newRegistry:
Technical specifications that wish to override an existing registry
for some values and use it for another should (a) attempt to correct
the extensiting registry; in cases where it cannot, the group
should (b) establish a new "override" registry with new values,
where the spec points to the new registry.

Finding.evolveTowardSimplicity:
The specifications and standards process should be managed so that
over the long term sniffing is minmimized and deployment of further
misconfigured values is discouraged.

Registry status:

Registry values typically go through a life-cycle, where a parameter
is introduced experimentally, deployed in a limited or vendor-specific
context, and then adopted more broadly.

Frequently, groups with registries or registered values attempt to
convey status of a registered value in the name chosen within the
registry, e.g., using an "x-" prefix for experimental names, "vnd."
prefixes in internet medai types, etc. In practice, these conventions
are failures, counter-productive, because there is no simple
deployment path when status changes, e.g., vendor proposed extension
become public standards, experiments succeed, etc.

Finding.noStatusInName:
* Do NOT attempt to encode parameter status in the name.

... discussion of "vendor prefix" guidelines ...


Organizational structure:


W3C staff & working group participants must manage the registration
information, and that the process itself needs revisions.  Other
registrations have their own administrative procedure.

If there is a registry, it is only useful if values are registered. A
registry which does not match actual use (as is currently the
case with URI schemes, Media Types) is not very useful.


Other references:

http://tools.ietf.org/html/draft-iab-extension-recs-09  “Design Considerations for Protocol Extensions”

http://lists.w3.org/Archives/Public/www-tag/2011May/0006.html

https://www.ietf.org/mailman/listinfo/happiana)

http://www.w3.org/wiki/FriendlyRegistries (requirements and a place to gather explicit proposals)

http://lists.w3.org/Archives/Public/www-tag/2011May/0006.html (HTML working group rel relation microformats wiki)


Suggestion:

A regular "have obligations related to registration been met" check
into the W3C document publication/advancement procedure would be
useful.


http://www.w3.org/2001/tag/2002/0129-mime


http://tools.ietf.org/html/draft-ietf-websec-mime-sniff

TAG finding on Internet Media types: http://www.w3.org/2001/tag/2002/0129-mime

W3C guidelines on registering types:
http://www.w3.org/2002/06/registering-mediatype


http://tools.ietf.org/html/draft-freed-media-type-regs

(allowing grandfathered registrations; registration by parties other
than the 'owner' and registry update process)

... distinguish between "must understand" and "must ignore" for
  unrecognized values ...

In the design of protocols with extensibility points, the guidelines
for dealing with "unrecognized values" are essential for controlling
extensibility. It *is* useful to provide some way of communicating
with agents which do not understand extensibility names by giving
explicit rules for how unrecognized names are to be dealt with
(ignored, warned, looked up, etc.)

There is a tradeoffs between requiring registry entries contain
complete information and getting more things registered.