Skip to main content

2. Creating and Revising Registries

Defining a registry involves describing the namespaces to be created, listing an initial set of assignments (if applicable), and documenting guidelines on how future assignments are to be made.

When defining a registry, consider structuring the namespace in such a way that only top-level assignments need to be made with central coordination, and those assignments can delegate lower-level assignments so coordination for them can be distributed. This lessens the burden on IANA for dealing with assignments, and is particularly useful in situations where distributed coordinators have better knowledge of their portion of the namespace and are better suited to handling those assignments.

2.1. Organization of Registries​

All registries are anchored from the IANA "Protocol Registries" page:

https://www.iana.org/protocols

That page lists registries in protocol category groups, placing related registries together and making it easier for users of the registries to find the necessary information. Clicking on the title of one of the registries on the IANA Protocol Registries page will take the reader to the details page for that registry.

Unfortunately, we have been inconsistent in how we refer to these entities. The group names, as they are referred to here, have been variously called "protocol category groups", "groups", "top-level registries", or just "registries". The registries under them have been called "registries" or "sub-registries".

Regardless of the terminology used, document authors should pay attention to the registry groupings, should request that related registries be grouped together to make related registries easier to find, and, when creating a new registry, should check whether that registry might best be included in an existing group. That grouping information should be clearly communicated to IANA in the registry creation request.

2.2. Documentation Requirements for Registries​

Documents that create a new namespace (or modify the definition of an existing space) and that expect IANA to play a role in maintaining that space (serving as a repository for registered values) must provide clear instructions on details of the namespace, either in the IANA Considerations section or referenced from it.

In particular, such instructions must include:

The name of the registry​

This name will appear on the IANA web page and will be referred to in future documents that need to allocate a value from the new space. The full name (and abbreviation, if appropriate) should be provided. It is highly desirable that the chosen name not be easily confused with the name of another registry.

When creating a registry, the group that it is a part of must be identified using its full name, exactly as it appears in the Protocol Registries list.

Providing a URL to precisely identify the registry helps IANA understand the request. Such URLs can be removed from the RFC prior to final publication or left in the document for reference. If you include iana.org URLs, IANA will provide corrections, if necessary, during their review.

Required information for registrations​

This tells registrants what information they have to include in their registration requests. Some registries require only the requested value and a reference to a document where use of the value is defined. Other registries require a more detailed registration template that describes relevant security considerations, internationalization considerations, and other such information.

Applicable registration policy​

The policy that will apply to all future requests for registration. See Section 4.

Size, format, and syntax of registry entries​

What fields to record in the registry, any technical requirements on registry entries (valid ranges for integers, length limitations on strings, and such), and the exact format in which registry values should be displayed. For numeric assignments, one should specify whether values are to be recorded in decimal, in hexadecimal, or in some other format.

Strings are expected to be ASCII, and it should be clearly specified whether case matters, and whether, for example, strings should be shown in the registry in uppercase or lowercase.

Strings that represent protocol parameters will rarely, if ever, need to contain non-ASCII characters. If non-ASCII characters are really necessary, instructions should make it very clear that they are allowed and that the non-ASCII characters should be represented as Unicode characters using the "(U+XXXX)" convention. Anyone creating such a registry should think carefully about this and consider internationalization advice such as that in [RFC7564], Section 10.

Initial assignments and reservations​

Any initial assignments or registrations to be included. In addition, any ranges that are to be reserved for "Private Use", "Reserved", "Unassigned", etc. (see Section 6) should be indicated.

For example, a document might specify a new registry by including:

---------------------------------------------------------------

X. IANA Considerations

This document defines a new DHCP option, entitled "FooBar" (see
Section y), and assigns a value of TBD1 from the DHCP Option space
<https://www.iana.org/assignments/bootp-dhcp-parameters>
[RFC2132] [RFC2939]:
                                Data
       Tag     Name            Length      Meaning
       ----    ----            ------      -------
       TBD1    FooBar          N           FooBar server

The FooBar option also defines an 8-bit FooType field, for which
IANA is to create and maintain a new registry entitled
"FooType values" used by the FooBar option.  Initial values for the
DHCP FooBar FooType registry are given below; future assignments
are to be made through Expert Review [BCP26].  Assignments consist
of a DHCP FooBar FooType name and its associated value.

       Value    DHCP FooBar FooType Name   Definition
       ----     ------------------------   ----------
       0        Reserved
       1        Frobnitz                   RFCXXXX, Section y.1
       2        NitzFrob                   RFCXXXX, Section y.2
       3-254    Unassigned
       255      Reserved
---------------------------------------------------------------

For examples of documents that establish registries, consult [RFC3575], [RFC3968], and [RFC4520].

Any time IANA includes names and contact information in the public registry, some individuals might prefer that their contact information not be made public. In such cases, arrangements can be made with IANA to keep the contact information private.

2.3. Specifying Change Control for a Registry​

Registry definitions and registrations within registries often need to be changed after they are created. The process of making such changes is complicated when it is unclear who is authorized to make the changes. For registries created by RFCs in the IETF stream, change control for the registry lies by default with the IETF, via the IESG. The same is true for value registrations made in IETF-stream RFCs.

Because registries can be created and registrations can be made outside the IETF stream, it can sometimes be desirable to have change control outside the IETF and IESG, and clear specification of change control policies is always helpful.

It is advised, therefore, that all registries that are created clearly specify a change control policy and a change controller. It is also advised that registries that allow registrations from outside the IETF stream include, for each value, the designation of a change controller for that value. If the definition or reference for a registered value ever needs to change, or if a registered value needs to be deprecated, it is critical that IANA know who is authorized to make the change. For example, the Media Types registry [RFC6838] includes a "Change Controller" in its registration template. See also Section 9.5.

2.4. Revising Existing Registries​

Updating the registration process or making changes to the format of an already existing (previously created) registry (whether created explicitly or implicitly) follows a process similar to that used when creating a new registry. That is, a document is produced that makes reference to the existing namespace and then provides detailed guidance for handling assignments in the registry or detailed instructions about the changes required.

If a change requires a new column in the registry, the instructions need to be clear about how to populate that column for the existing entries. Other changes may require similar clarity.

Such documents are normally processed with the same document status as the document that created the registry. Under some circumstances, such as with a straightforward change that is clearly needed (such as adding a "status" column), or when an earlier error needs to be corrected, the IESG may approve an update to a registry without requiring a new document.

Example documents that updated the guidelines for assignments in pre-existing registries include: [RFC6895], [RFC3228], and [RFC3575].