Differences between the two Registry proposals

A Registry is a data set that documents logically independent 'atoms'; conceptually a table with independent rows, and rules for the values in the columns (e.g. that values in a column be drawn from a defined set).

A registry documents a data set consisting of one or more associated registry tables, each table representing an updatable collection of logically independent, consistently-structured registry entries.

1. Registries are always owned by, or incorporated directly into, a Referencing Document (though the registry may be referenced by other documents as well, fo course). (Roughly, the spec. that has some aspect (e.g. a field, an attribute value) for which registration of new values needs to be possible.)
2. Registries are defined by a Registry Definition. Contains the definition of and requirements for the registry values.
3. Published Registry values. The formal published location, which URLs referring to registry values (e.g. notably from the Referencing Document) point to.

• one or more registry tables, holding the data set represented by the registry
• the rules of the registry, defining how the registry tables are structured and maintained
one or more referencing specifications, which make use of the registry

4. Registry values management. This is where the registry values are maintained, and so on.

They are updated following the (approved) process for that registry as defined in the Registry definition.

Hence changes to the Registry other than managing entries are all controlled by the update process for the Registry definition.

As long as they are in accordance with the rules of the registry, changes to the contents of a registry table (.e. Class 5 changes) can be made by re-publishing the technical report that contains the affected table, without needing to satisfy any other requirements for the publication (not even Working Group consensus, unless this is required by the rules of the registry). Such registry changes do not trigger new Advisory Committee Reviews, nor new Exclusion Opportunities, and do not require Director’s approval, even for technical reports at maturities where this would normally be expected. Such publications can be made even in the absence of a Working Group chartered to maintain the registry when the custodian is another entity.

We are currently discussing which of these elements can be combined. Examples include: 1+2) Referencing Document + Registry Definition, and have a pointer to the Published Registry. (This is like the IETF, where RFCs typically document a technology, and say which fields are open to registration, and under what conditions, but the registry values themselves are at IANA). (Some do not like this practice, others do).

2+3) Registry Definition + Published Registry. This would be the case where it makes sense to define a registry as a stand-alone Recommendation in its own right.

1+2+3) Referencing Document + Registry Definition + Published Registry. This would be suitable for ’small’ tables for which the current values and the definitions can easily be inlined into the spec. (“thing-type: a value drawn from the thing-type registry; current values and the procedures for registering a new thing-type can be found in Annex G”). You could insert the Published Registry as an iframe, for example.

• This is not Process text, just a discussion of possibilities for Issue 354
• The possibility outlined for 2+3 suggests that the full REC track would be used, even though some aspects of it aren't relevant; FFPR started with this position, but currently defines a separate track in order to a) avoid invoking the Patent Policy and all of its machinery, including Calls for Exclusions, on a document that it can't apply to and b) simplify the track by removing the CR phase, which checks an implementation requirement that doesn't exist on registries
• 1+2+3 is allowed by the earlier allowance for including a registry section in a REC ("Registries can be … incorporated as part of a W3C Recommendation as a registry section").

See Maturity Levels of Registry Reports which is a simplified form of the REC track, for the 2+3 case.

1+2+3 is handled by Updating Registry Tables together with Registry Reports

The Referencing Document

1. MUST contain all normative statements and information that affect implementations and the conformance of implementations. It must not be possible that a change to the Registry values affect the conformance of implementations to the Referencing document; if there are values that must be implemented, or any other such restrictions, they must be documented in the document without reference to the registry.

2. may either contain the registry or have a reference to the registry, where to view it

1. contain a section defining the registry that must
   1. state that it is a Registry per the W3C Process,
   2. identify the Custodian. The Custodian can be the W3C group that owns the Referencing Document, the team if no such W3C group exists, or some other entity.
   3. define the fields of its table of items,
   4. define the policy and procedure for changes (additions, and deletions or modifications if they are permitted); how to request a registration, what information is required, and what criteria must be met
2. contain all requirements and normative language related to the registry; the rules for values (logically, the column values) in each entry (e.g. uniqueness, matching to a value from some other specification or registry, etc.)
3. contain documentation on the policy and mechanisms for changes to existing entries:
   1. can entries be retired (deleted) or deprecated?
   2. can entries be changed after being published?
   3. if entries can be deleted, can any code-points be re-used, or are they 'reserved' indefinitely?
4. provide the location of the published Registry values, and the Registry management.
5. provide any restrictions on links to other publications, e.g. that the specification be
   1. publicly available (as opposed to company-private, for example)
   2. freely available (no cost)
   3. published by a recognized standards body
   4. a W3C publication
6. document any requirements of evidence of implementability, implementation, interoperability, etc.

• Define the scope and purpose of the registry table.
• Define the fields of the registry table and their constraints (e.g. values must be drawn from a defined set, or be unique, or only reference publicly available resources, etc.)
• Define the method and critera by which changes are proposed, approved, and incorporated. (For example, a registry could define that changes to registry entries can be proposed using a particular web form or email address, that registry entries can be added but not changed, or that they do or do not need to be approved by any member of a particular Working Group.)
• Identify the custodian of the registry table: the entity to which requests for registry changes must be sent, and which is responsible for evaluating whether such requests satisfy the criteria defined in the rules of the registry.

  The custodian may be the Working Group, the Team, or a delegated entity. The custodian for all registry tables in a single registry should generally be the same entity.

• Generally speaking, documents referencing a technical report should not be determining the status of the technical report or the process that governs its evolution. This is backwards, and also raises weird questions like, what if you have multiple ones, what if some are not W3C documents, what if the first one is a Note but then later a REC wants to reference it too…
• Allowing Registry definitions in Notes seems pointless: the values can only be updated according to the rules, but the rules can change at anytime. It pretty much boils down to the registry being a Note. We need a registry process for when Notes aren't good enough, otherwise just use a Note and put "Registry" in the title.

The Registry values

1. must only be updated when conforming to the rules in the associated Registry Definition.

2. must not contain any normative statements (must, should, etc.).

3. if it is not embedded in the referencing document or registry definition, must contain a link back to the registry definition (which contains the rules etc.) and should contain a link back to the referencing document (for which it is a registry), if that document is separate;
4. may contain informative material, including descriptions of the various values ('columns') and their meaning
5. must contain or reference the information on how to request updates (a new entry or any other permitted changes).

3. current FFPR doesn't allow splitting values from definitions. If it did allow, it would need an equivalent
4. Needing repeat information that exists in the registry definition in the values because they have been split into separate publications is a clear indication that they should not have been split (and is a good way for things to get out of sync), so this should not be necessary / allowed.
5. Ditto.

6. may contain a machine-readable copy (e.g. CSV file) which MUST match the human-readable copy of the same version of the Published registry

(Note that this probably should apply to the development of any W3C publication. The general rules are currently unstated.)

The Registry management must be a location that is suitable for development of a W3C publication. The rules are currently unstated but probably should be stated for the general case, and not specifically for registries. Registry management must

• have the ability to file bug reports (aka issues)
• support history tracking (so we can see what was changed when, by whom, etc.)
• have backups maintained by the W3C (so if there is a disc crash or the service goes down, we don't lose)
• must be setup in such a way that review (cross-functional, wide, AC, review for example) can be managed using automatic notifications, e.g. sending notifications and periodic summaries to interested populations;
• be such that the development tool/site are to be accessible (a) to those needing accessible access and (b) to our community internationally.

(A scrapable Wiki may be suitable here, while a Wiki is probably not suitable for document management generally.)