3.1. Documentation Requirements for Registrations
3.1. Documentation Requirements for Registrations
Often, documents request an assignment in an existing registry (one created by a previously published document).
Such documents should clearly identify the registry into which each value is to be registered. Use the exact registry name as listed on the IANA web page, and cite the RFC where the registry is defined. When referring to an existing registry, providing a URL to precisely identify the registry is helpful (see Section 2.2).
There is no need to mention what the assignment policy is when making new assignments in existing registries, as that should be clear from the references. However, if multiple assignment policies might apply, as in registries with different ranges that have different policies, it is important to make it clear which range is being requested, so that IANA will know which policy applies and can assign a value in the correct range.
Be sure to provide all the information required for a registration, and follow any special processes that are set out for the registry. Registries sometimes require the completion of a registration template for registration or ask registrants to post their request to a particular mailing list for discussion prior to registration. Look up the registry's reference document: the required information and special processes should be documented there.
Normally, numeric values to be used are chosen by IANA when the document is approved; drafts should not specify final values. Instead, placeholders such as "TBD1" and "TBD2" should be used consistently throughout the document, giving each item to be registered a different placeholder. The IANA Considerations should ask the RFC Editor to replace the placeholder names with the IANA-assigned values. When drafts need to specify numeric values for testing or early implementations, they will either request early allocation (see Section 3.4) or use values that have already been set aside for testing or experimentation (if the registry in question allows that without explicit assignment). It is important that drafts not choose their own values, lest IANA assign one of those values to another document in the meantime. A draft can request a specific value in the IANA Considerations section, and IANA will accommodate such requests when possible, but the proposed number might have been assigned to some other use by the time the draft is approved.
Normally, text-string values to be used are specified in the document, as collisions are less likely with text strings. IANA will consult with the authors if there is, in fact, a collision, and a different value has to be used. When drafts need to specify string values for testing or early implementations, they sometimes use the expected final value. But it is often useful to use a draft value instead, possibly including the draft version number. This allows the early implementations to be distinguished from those implementing the final version. A document that intends to use "foobar" in the final version might use "foobar-testing-draft-05" for the -05 version of the draft, for example.
For some registries, there is a long-standing policy prohibiting assignment of names or codes on a vanity or organization-name basis. For example, codes might always be assigned sequentially unless there is a strong reason for making an exception. Nothing in this document is intended to change those policies or prevent their future application.
As an example, the following text could be used to request assignment of a DHCPv6 option number:
IANA is asked to assign an option code value of TBD1 to the DNS
Recursive Name Server option and an option code value of TBD2 to
the Domain Search List option from the DHCP option code space
defined in Section 24.3 of RFC 3315.
The IANA Considerations section should summarize all of the IANA actions, with pointers to the relevant sections elsewhere in the document as appropriate. Including section numbers is especially useful when the reference document is large; the section numbers will make it easier for those searching the reference document to find the relevant information.
When multiple values are requested, it is generally helpful to include a summary table of the additions/changes. It is also helpful for this table to be in the same format as it appears or will appear on the IANA web site. For example:
Value Description Reference
-------- ------------------- ---------
TBD1 Foobar this RFC, Section 3.2
TBD2 Gumbo this RFC, Section 3.3
TBD3 Banana this RFC, Section 3.4
Note: In cases where authors feel that including the full table of changes is too verbose or repetitive, authors should still include the table in the draft, but may include a note asking that the table be removed prior to publication of the final RFC.