Skip to main content

2.2. Documentation Requirements for Registries

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.

Last updated on