Guidance for RFC Authors

RFCs often contain content that is directly applicable to IANA, and these sections should conform to a number of requirements. Authors of prospective RFCs (known as Internet-Drafts, or “I-D”s), should read RFC 8126, which provides the authoritative set of guidelines for writing an IANA Considerations section. This document augments RFC 8126 by providing additional guidance and more specific details.

IANA is always happy to provide guidance directly to document authors. If you have questions that haven't been addressed here, or if you want us to check out your document's IANA Considerations section at any stage of development, email us at iana@iana.org.

Terminology usage

In addition to the guidance in RFC 8126, here are some additional terminology considerations:

Registry vs. subregistry

You should almost always use the term "registry" to refer to a table or collection of assignments made for a common identifier type. The term "subregistry" should be reserved for registries that are nested within specific registrations. For example, at https://www.iana.org/assignments/isis-tlv-codepoints, "IS-IS Sub-TLVs for Reverse Metric TLV" is a subregistry for value 16 ("Reverse Metric") in the "IS-IS Top-Level TLV Codepoints" registry.

Registry group

A set of registries presented as a single document through a common URL (i.e. https://iana.org/assignments/*) is called a "registry group." A group consists of one or more registries. Registries are typically grouped when they are thematically related, such as when implementers are likely to use the different identifier types for a common protocol.

In the past, these groups have been called "top-level registries" or "registries" (which we have now settled on as the descriptor for a discrete set of registrations, as above). RFC 8126 uses the term "registry grouping," but the RFC Editor recommended the more flexible "group."

What to include when you're creating a registry

When an RFC creates a new IANA registry, every piece of text that makes up the newly-created registry should also appear in the IANA Considerations section. This will always include the following:

  • Name of the registry
    • Please provide the full text of the name of the registry. Spell out acronyms, then include them in parentheses where desired (e.g. “Structural Dynamic Flow (SDF) Codes”)
    • If the registry group includes similar registries, consider whether a registry naming scheme appears to be (or should be) in use.
    • Leave redundant descriptors like "Registry" out of the registry name.
  • Name of the registry group (e.g. the string "Access Node Control Protocol (ANCP)" at https://www.iana.org/assignments/ancp)
    • Leave redundant descriptors like "Parameters" and “Assignments” out of the registry group name.
    • If the group currently consists of one registry, should you reuse the registry name for the group name, or adjust it? Could more registries be added to this group in the future?
  • Registration procedure
    • Select an appropriate definition from RFC 8126, Section 4.
    • Note that different procedures can be assigned to different ranges (e.g. "IETF Review for 0-7, First Come First Served for 8-65535").
  • Field names
    • If you're creating a First Come First Served or Expert Review registry, we recommend including a "Change Controller" field. For more information, see RFC 8126, Section 2.3.

Other considerations

  • Should any values be marked "Reserved"? If so, do they need to be explicitly marked as "Reserved for Private Use" or "Reserved for Experimental Use"?
  • If you need to allocate numeric values:
    • Unless specified differently, registries typically start at the value “0” and numerically increment as unsigned integers.
    • Is there an upper numeric boundary informed by how the identifier is stored (e.g. 15, 255, 65535 for 4-bit, 8-bit and 16-bit identifiers respectively)? This can be indicated by providing a table (ideally using RFCXML) that includes the registry's "Unassigned" values.
    • Should the first value (e.g. 0) or last value be marked "Unassigned" (available for assignment), marked "Reserved" (unavailable, unless a future document says otherwise), or left out of the registry?
  • If the registry should be placed at an existing URL, it's helpful to cite that URL, but please use the "short" version that doesn't include a file extension (or a URI fragment). More on this below, in the "Future" section. In the meantime:

What to include when you're making a registration

Whether your section consists of a ten-page table or a single sentence that tells us to allocate one codepoint, the following information should appear in the document text:

  • The exact registry name as it appears online
  • Enough information to populate every required field
  • If you include the URL, please see the notes concerning file extensions and URI fragments above.

Note that if you're requesting a registration in an Expert Review or Specification Required registry, we'll ask the expert(s), with the WG in copy, to review it at the end of IETF Last Call.

What not to include

  • If you're registering, for example, a sub-TLV in a registry of sub-TLVs, it may be preferable to leave the string "sub-TLV" out of the new registration's name/description field. See the existing registry for examples.

  • If you're asking for a specific value that hasn't been allocated yet, describe it as a "suggested" value (in parentheses or otherwise). Unless the value has been approved for early allocation (details below), there is no mechanism in place to keep that value from being registered by another document before yours is approved for publication, and therefore the assigned value may differ from the value in the I-D.

Securing a specific identifier value

If you need an allocation from a registry that requires an RFC, see RFC 7120 (especially Section 3) for instructions. (This is the procedure that the term "Early Allocation" usually refers to.)

If your document needs an allocation from a First Come First Served or Expert Review registry, send your request to iana@iana.org. Whether such an early allocation will be made depends on the policy of the registry, such as the RFC that established the registry and the opinion of the IESG-designated expert for the registry, where applicable.

When a document obsoletes an existing RFC

If you're obsoleting the original document rather than updating it (as in a “bis” document), and you want to keep the full text of the original IANA Considerations section, we'd like to see an introduction or introductory sub-section(s) that tell(s) us what needs to be changed or added.

Our questions:

  • Should we replace all references to the original document?
  • Are there old references that should be left in place? (this is less common)
  • Should any of the original registrations be marked "deprecated" or "obsoleted"?
  • Is this document creating new registries and/or registrations? We prefer that these be separated from the original actions.

To make sure that everything's been accounted for, it can also be helpful to include a list of registry groups that include references to the original document. Consult with IANA staff if you need guidance in this area.

Recommendations for common issues

  • If you're creating or updating multiple registries, divide the IANA Considerations into sub-sections (possibly with a summary at the top of the section, if appropriate).
  • The IESG shouldn't be listed as a change controller unless the RFC that created the registry (e.g. port numbers, XML namespaces and schemas) requires it. The IETF should be named instead.
  • If you're creating a mailing list or other additional mechanism that will be involved in the operation of the registry:
    • Should the review period have a specific duration?
    • Should the mailing list be public or viewable only by the experts?
    • The mailing list sub-section should describe the submission procedure. To make sure that requests don't accidentally get dropped, we recommend telling the applicant to send their request to iana@iana.org and telling us to send that request to the list (with the applicant in copy).
    • You can provide a mailing list name in the document.
  • If registry users would benefit from a note at the top of the registry, as in the “OSPFv3 Extended-LSA Sub-TLVs” registry at https://www.iana.org/assignments/ospfv3-parameters, that note should be included in the IANA Considerations section.
  • We prefer that all information for IANA be included in the IANA Considerations section. If that's not possible, please include references to the relevant section/table and, in that section, clearly label the information to be registered (much as if you were writing instructions for a computer that doesn't know what your registry is).
  • Although this wasn't the case in RFC 2434, the "Specification Required" procedure always includes expert review.

Suggested text (if you need it)

If you're not sure how to write your IANA Considerations section, you could adapt the starter text below. It's not great, but it'll be clear to us. You're welcome to rephrase, insert URLs, and/or add any other text you think is relevant. If you're creating an Expert Review or Specification Required registry, for example, you might include instructions for future experts.

Creating a registry (existing registry group):

IANA will add the following new registry to the "Foo" registry group at https://www.iana.org/assignments/example:

Registry Name: (NAME)

Registration Procedure: (PROCEDURE)

(TABLE OF REGISTRATIONS)

Creating a registry (new registry group):

One registry:

IANA will create the following registry in a new registry group called "Foo":

Registry Name: (NAME)

Registration Procedure: (PROCEDURE)

(TABLE OF REGISTRATIONS)

Multiple registries (in this example, the IANA Considerations section is Section 9):

IANA will create a new registry group called "Foo." This group includes the "Foo" and "Bar" registries described below.

9.1 Foo

IANA will create the following registry:

Registry Name: Foo

Registration Procedure: (PROCEDURE)

(TABLE OF REGISTRATIONS)

Creating registrations:

One registration, only one or two fields to fill in:

IANA will assign value TBD (suggested value: 47) to "Foo" in the "Bar" registry.

Multiple registrations/fields:

IANA will add the following (entry/entries) to the "Bar" registry:

(TABLE OF REGISTRATIONS)

Replacing a reference:

Replacing all references to a document:

In the "Foo" (registry/registry group), IANA will replace all references to RFC XXXX with references to this document.

Replacing some references to a document:

In the "Foo" (registry/registry group), IANA will replace references to RFC XXXX with references to this document for the following registrations:

(TABLE OF REGISTRATIONS)

Naming the registrations that won't have their references replaced:

In the "Foo" (registry/registry group), IANA will replace references to RFC XXXX with references to this document for all but the following registrations:

(TABLE OF REGISTRATIONS)

Adding a reference to an existing registry:

IANA will list this document as an additional reference for the "Foo" registry.

Adding a reference to an existing registration:

One registration:

IANA will list this document as an additional reference for "X" in the "Y" registry.

Multiple registrations:

IANA will list this document as an additional reference for the following entries in the "Y" registry:

(TABLE OF REGISTRATIONS)

No actions:

No IANA actions required.

Examples of registry formats:

IANA review states

Every time we review a document after IETF Last Call, we assign it an "IANA review state" like "IANA OK - Actions Needed." You can find information about these states at https://datatracker.ietf.org/help/state/draft/iana-review. Note that while we will check the document again when it enters IESG Evaluation and after the IESG approves it for publication, we aren't otherwise notified when documents are updated. If you make changes that may require another IANA review after the document appears on an IESG telechat agenda, please contact us at iana@iana.org.

Future considerations

IANA is currently developing an improved registry management system. This currently has two implications for I-D text:

  • It is likely that the concept of a “registry group” will evolve to enable new methods of aggregating and presenting registration data. The current publication mechanism is intrinsically tied to underlying storage format of registry data, but we expect that to no longer be the case. This means that there will be new presentation methods in the future, and the interrelationships between registries are likely to be more flexible.
  • Registries — and individual registrations — may be presented individually in some contexts, rather than always within their registry groups. This means that URL fragments that are used to jump to the relevant context on a single page, such as those in a URL like https://www.iana.org/assignments/bgp-parameters#bgp-graceful-restart-flags, may not take you directly to, e.g., the BGP Graceful Restart Flags registry. However, it will at the very least take you to the BGP Parameters registry group.

If you have questions about how your registry may be impacted by the future evolution of the IANA services, please contact us about it. IANA can be reached about this or any other concern at iana@iana.org.

Last revised 2023-03-22.