Guidelines for Writing an IANA Considerations Section in RFCs
RFC 8126

Note: This ballot was opened for revision 09 and is now closed.

(Pete Resnick) Discuss

Discuss (2014-11-24 for -11)
2.1/2.2 - You rightly point out in 2.1 that the terminology has been inconsistent in the past. But then you go ahead in 2.2 and use the two most confusing terms that you could use ("registry" for the grouping and "sub-registry" for the thing that contains the namespace). Please come up with terminology for this version of the document and stick to it. I would very much prefer "Category" (or "Grouping") for the grouping and "Registry" for the thing that contains the namespace. The documentation requirement should be for the Registry name, and, if desired, the Category (or Grouping) into which the Registry goes. The grouping can be identified by name or (if it already exists) by URL. If you insist on using the terms "registry" and "sub-registry" (and I implore you not to), please at least define those terms in terms of category, grouping, and namespace. In any event, please do not update this document without fixing the problem.

2.2 - The size/format section makes it confusing as to whether you're defining technical *protocol* requirements (which don't belong in the registry definition) or requirements for the registry itself (i.e., how things are displayed or stored by IANA). I particularly don't like giving UTF8 as an example. If the thing in the registry is a text string, then "Zürich" is a fine entry, whether it is stored in the registry at IANA with the second character as U+00FC or U+0075 U+0308 (however encoded); the registry should point back elsewhere in the document to define the encoding requirements or the normalizations that might be used. However, if the thing in the registry is a specific UTF8-encoded octet-string, then what should appear in the registry should either contain "0xC3 0xBC" or it should contain "0x75 0xCC 0x88" and not appear as "ü". The paragraph should make that clear.

In the example, I'm not clear on what "under the FooBar option" means. That sounds like there is a Category called "FooBar Options" somewhere, but I don't think that's what you mean.
Comment (2014-11-24 for -11)
No email
send info
Overall: I think this document could use a good edit pass to remove redundant information and put things in the correct order. Lots of information is scattered because it is repeated in several places.

I also agree that the 2119 language in here is not useful.

Specifics:

1 - I agree that you should strike the last sentence of the first paragraph.

1.1 - I suggest a small insertion:

OLD
   But if it's necessary to include a longer technical explanation of
   the purpose and use of the item,
NEW
   But if it's necessary to include a normative definition or longer
   technical explanation of the purpose and use of the item,
END

2.3/2.3.* - I agree with Adrian and Alissa's concerns. This could really be edited down quite a bit and combined with section 4, removing lots of duplication throughout. Giving the menu of policies *first* and then describing how to use them seems like a good plan. The second-to-last and third-to-last paragraphs of 2.3 seem unnecessary.

4.8 - Does an Info/Exp RFC without the consensus box checked count for IETF Review?

4.9 - How about BCPs?

4.10 - The reference to RFC 2434 is odd.

5.4 - I'm suspicious about this section. I suspect it was written when it was thought that experts would be reviewing IETF Review documents. (Cf. discussion of the IESG and the "token held by the responsible Area Director".) In 2.3.2, it explains that this scenario really shouldn't be coming up, because experts need not (ought not?) be on the hook to review IETF Review documents. I'm not convinced these two section jive with each other.

(Adrian Farrel) Yes

Comment (2014-11-22 for -11)
No email
send info
I am conflicted as to what ballot position to enter! In the end I 
selected "Yes" because I think that publication as an RFC outweighs my
concerns about the document.

However, I present a list of editorial considerations.

I spent some time in Honolulu asking established IETF participants why
they find writing IANA considerations sections so hard. The answer I got
was that 5226 was too much to plough through and so they just guessed.
That is a problem we need to address somehow.

RFC 5226 is 27 pages long. This I-D is 37 pages long. I don't think this
is helping. Perhaps the solution is to bring out the key sections of the
document to be easily discovered (currently sections 4 and 6) and 
presented as the core text.

I know this isn't a helpful comment at this stage, and I know you aren't
likely to restart your work with the intent of deleting swathes of text
so just take this as me whining. (But I really found most of sections 2 
and 5 added unnecessary description and was a bit jumbled. I also 
thought section 2 errs on the side of making access to code points easy
where interop and protocol-bastardisation are a risk - but I have been 
burned.)

---

Section 1.2

I looked at http://iana.org/help/protocol-registration
It's an empty placeholder. I recommend against referencing it unless
the IANA is making a pedge to fill the page before publication of the
RFC.

---

I really think that the use of 2119 langauge is unnecessary.
Furthermore, it is used incosistently with some elements of the
procedures described in lower case normal English.

---

Section 2

Is it necessary to indicate the plural(s) in this way?
English allows a single instance as a special case of a plural.

---

Section 2

   listing an initial set of assignments (if appropriate)

I think that is s/appropriate/applicable/

---

Section 2 has

   Before defining a registry, however, consider delegating the
   namespace in some manner.

Pedantically I think this is s/Before/When/ as the Hierarchical
assignment policy is just another policy in the list.

Carrying on in the section you have

   In particular, not all namespaces require a registry; in some cases,
   assignments can be made independently and with no further (central)
   coordination.  In the Domain Name System, for example, IANA only
   deals with assignments at the higher levels, while subdomains are
   administered by the organization to which the space has been
   delegated.  When a namespace is delegated in this manner, the scope
   of IANA is limited to the parts of the namespace where IANA has
   authority.

This is slightly confusing firstly because namespaces that don't require
a registry don't fall into scope of this document, and also because the 
example given, there is a registry with Hierarchical assignment policy.

---

Section 2.1 is perfectly correct but the choice of "Hierarchical" is
unfortunate coming immediately after a section on that discussed 
delegation which (although not mentioned) is through the Hiearchical
assignment policy.

Maybe just "Sturcture of Registries" or "Organisation of Registries"

---

In Section 2.1

   In the example section above, there are two registries
   related to the ADSP protocol, and they are both placed in the "ADSP
   Parameters" group.

   Within the "ADSP Parameters" group are two registries: "ADSP Outbound
   Signing Practices" and "ADSP Specification Tags".

There seems to be some repetition.

---

Section 2.1

   And when new
   registries are created, the documents that define them often don't
   specify the grouping at all, but only name the new registry.  This
   results in questions from IANA and delays in processing, or, worse,
   in related registries that should have been grouped together, but
   that are instead scattered about and hard to find and correlate.

Wouldn't it be better to fold this into the subsequent paragraph to 
give advice and guidance on how to do things right rather than 
commentary on how things are done wrong?

---

Section 2.2

I found 

   Required information for registrations 

      This information may include the need to document relevant
      Security Considerations, if any.

more confusing than helpful. I looked for more details on this
information but didn't immediately find anything. Can you include a 
forward pointer to the relevant section?

---

Section 2.2

   Applicable review process 

      The review process that will apply to all future requests for
      registration.  See Section 2.3.

Is this intended to be the assignment or registration policy?
(Although in section 2.3 you call it a "Regsitry Policy".)

---

Shouldn't 2.3 start with two lines saying what an Registry Policy is?

---

Section 2.3

   Even when the space is essentially unlimited, however, it is usually
   desirable to have at least a minimal review prior to assignment in
   order to:

s/however, it is/it is still/

But I would quibble with "usually" since that flies in the face of FCFS.
And, indeed, subsequent text says
   When the namespace is essentially unlimited and there are no
   potential interoperability or security issues, assigned numbers can
   usually be given out to anyone without any subjective review.
which is the same "essentially unlimited".

---

Missing from, but implicit in the first two paragraphs of Section 2.3.1
is that ayone can make up any registration policy they like and that no-
one has grounds to object. If that is intended it should be said 
(elsewhere you also only recommend - not mandate - the use of one of the
defined policies).

---

Section 2.3.2

In the case of multiple registration policies that we see in the 
registries today, there is typically poor or no guidance about the use
of the competing policies. Your text wisely says "Guidance should be 
provided about when each policy is appropriate", but the example is a 
bit woolly in that it only says *a* circumstance under which one of the
two policies should be used. It would help, I think, if the example 
could be tighter and so give a better template for people defining 
registries. For example,

      IANA is asked to create the registry "Fruit Access Flags" as a
      sub-registry of "Fruit Parameters".  New registrations will be
      permitted through either the IETF Review policy or the
      Specification Required policy [BCP26].  The latter should be used
      only for registrations requested by SDOs outside the IETF: all 
      other registrations should use former.

---

Section 2.3.3 is new information and is potentially important. I think
the reader needs some help to distinguish this section from 2.3.4 (I 
do! and my issues/questions here also apply to 2.3.4) and an example 
would help (perhaps an example for an IETF review registry).

It may also be helpful to clarify here what type of RFCs we require for
what type of updates. For example, if I create a registry in a Standards
Track RFC that has a Standards Action registration policy, so I need a
Standards Track RFC to change that policy to IETF Review?

---

The last para of 2.3.3 needs to point to 4.4 (as well as 9.5).

---

3.1

   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.

The exception being when there are multiple policies defined for a 
registry and a choice is being made.

Equally, when a registry is subdivided into ranges with different 
policies, the request must specify the range in order for IANA to 
determine which policy applies.

---

3.1

   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.

This is good, but tends to imply that a draft can state speicific values
from experimental ranges. 3692 makes it clear that this is not the case.

---

3.1

   Note: In cases where authors feel that including the full table 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.

On first and second reading I took this to mean "include the full 
existing table from the registry and show your additions." On third 
reading (perhaps after adequate port?) I see that you may mean a full
table of the new entries. Maybe this could be wordsmithed?

---

The example at the end of 3.1 includes text that often trips up authors
who detest the future historic tense. 

      IANA has assigned 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.

It is true that the final RFC text will contain these words ("IANA has
assigned") and at the time of RFC editing this will be inserted. But
authors prefer to write...

      IANA is requested to assign an option code value of TBD1 ...

You use this form in other examples, so I think this is just a 
cut'n'paste from an RFC.

---

You might add in 3.4 (since it may be valuable to highlight what was,
but is no longer the case"...

It is not necessary to explicitly mark a registry as allowing early 
allocation. [RFC7120] explains all of the considitions under which early
allocation is allowed.

---

Section 4

   The following are some defined policies, most of which are in use
   today.

Of course, that set me to trying to work out which ones are not in use
today. After a while I determined that it's a trick: "all" is a sub-case
of "most".

Maybe this sentence can read...

  The following policies are defined for common usage.

---

Section 4

"strongly RECOMMENDED"

Does that go along with "you know you really, really SHOULD" and 
"absolutely MUST"?

---

Section 4

The example...

   Pseudowire Edge to Edge Emulation (PWE3) [RFC4446]

is vague and fails the test of this document. That is, there is no
registry with that name. You could have...

  MPLS Pseudowire Types Registry [RFC4446]  

---

Section 4.1

   There is
   no need for IANA to review such assignments (since IANA does not
   record them)

Perfectly correct, but I would prefer the statement to be reversed as

   IANA does not record assignments from registries or ranges with this
   policy (and therefore there is no need for IANA to review them)

---

4.2

   Experimental Use is similar to Private Use only

d/only/

---

4.2

I would like this section to state:

- IANA does not record assignments from registries or ranges with this
  policy
- It is inappropriate for documents to state explicit values from 
  registries or ranges with this policy

---

Section 4.3

   Examples:

      DNS names
      Object Identifiers
      IP addresses

Is it possible to give references for these? Maybe URLs or RFCs?

---

Section 4.4

   It is also important to understand that First Come First Served
   really has no filtering.  Essentially, any request is accepted.  A
   working group or any other entity that is developing protocol based
   on a First Come First Served code point has to be extremely careful
   that the protocol retains wire compatibility with current use of the
   code point.  Once that is no longer true, the new work needs to
   change to a different code point (and register that use at the
   appropriate time).

I'd suggest a paragraph break after "accepted." There is no 
consequential flow into the next sentence.

---

Section 4.5

   (Also called "Designated Expert" in earlier editions of this
   document.) For the Expert Review policy, review and approval by a
   designated expert (see Section 5) is required.  The required
   documentation and review criteria for use by the designated expert
   should be provided when defining the registry.  For example, see
   Sections 6 and 7.2 in [RFC3748].

   It is particularly important, when using a designated expert, to give
   clear guidance to the expert, laying out criteria for performing an
   evaluation and reasons for rejecting a request.  When specifying a
   policy that involves a designated expert, the IANA Considerations
   SHOULD contain such guidance.

There is a bit of duplication in this text. I suggest folding the last
two sentences of the first paragraph into the second paragraph.

---

4.10

   IESG Approval is not intended to be used often or as a "common case";
   indeed, it has seldom been used in practice during the period RFC
   2434 was in effect.

s/has/was/

---

Section 5 presents a lot of new material about DEs. Two questions arise:

1. How does a member of the community discover the names and email 
   addresses of the DEs?

2. How does the "chair" of a "pool" of DEs get appointed?

---

Section 5.2.1 should prpbably also talk about removing DEs at the whim
of the IESG (and resignations).

---

Section 5.4 doesn't address a question that comes up a lot. Precisely 
when should the DE review be done?

We often see it raised as a question at IETF last call, IESG evaluation,
IESG approval, and RFC editor processing. I think this document could 
give better guidance, specifically to IANA who are invoked to make
provisional assignments during IETF last call often before a DE has made
a pronouncement.

---

It would be nice if this document also clarified the role of a DE in
assessing an IETF consensus document. Can a DE block an assignment made
by IETF consensus?

---

Section 7

   o  If a document registers an item that is defined and explained
      elsewhere, the registered reference should be to that document,
      and not to the document that is merely performing the
      registration.

I know what you mean, but "reference should be to that document" is
confusing. Maybe...

   o  If a document registers an item but the definition and explanation
      of the item is provided in a second document, the reference in the
      registry should be to the document that provides the definition 
      and not to the document that is merely performing the
      registration.

(Although, I would find it helpful to include both references.)

---

Section 8 runs the risk of confusing obsoletion with updating. I think 
you are trying to describe both what to do when a new RFC obsoletes an
old RFC that defined and described the registered codepoint, and what 
to do when the change is just an update.

The first paragraph and a half are, I think, intended to describe the 
replacement. The later text then introduces the case of an update.

However...

   On occasion, an RFC is issued that obsoletes a previous edition of
   the same document.  We sometimes call these "bis" documents, such as
   when RFC 9876 is updated by draft-ietf-foo-rfc9876bis.

Maybe s/updated/obsoleted/

---

Should section 12 discuss the signing and verification of IANA registry
web pages?

(Brian Haberman) Yes

(Ted Lemon) Yes

Comment (2014-11-25 for -11)
No email
send info
This is a very helpful document.  Thanks for doing it.   I did not find it overly wordy--it was a clear and easy read, despite its length.

In 2.3.1:

   Examples of situations that might merit RFC Required, IETF Review, or
   Standards Action include the following:

   o  When a resource is limited, such as bits in a byte (or in two
      bytes, or four), or numbers in a limited range.  In these cases,
      allowing registrations that haven't been carefully reviewed and
      agreed by community consensus could too quickly deplete the
      allowable values.

   o  When thorough community review is necessary to avoid extending or
      modifying the protocol in ways that could be damaging.  One
      example is in defining new command codes, as opposed to options
      that use existing command codes: the former might require a strict
      policy, where a more relaxed policy could be adequate for the
      latter.  Another example is in defining protocol elements that
      change the semantics of existing operations.

This doesn't actually make sense: "RFC Required" does not really imply that there has been thorough community review or consensus.   I think you want RFC Required when you want there to be a document available that explains what a given code point is used for, and/or what its related format is.   So I would encourage you to explain "RFC required" separately, and perhaps use my explanation for why you would want that as a registration policy, if you agree that I've described it correctly.

In 4.10, it's perhaps worth noting that "IESG approval" is essentially always a possibility for an IANA allocation that is under IETF control.   That being the case, it might be worth saying why this is different.   (I think the difference is that this is an anticipated (as opposed to unanticipated) need, and therefore doesn't imply the need to change the registration policy.)

In 5.2, it would be nice if it were required that the expert explain the decision and that the IANA make a record of that explanation that would be available if someone had a question about it.   I think this is sort of happening already in the IANA tracker, as long as the designated expert explains the decision, but maybe that should be made explicit?

(Terry Manderson) Yes

(Alexey Melnikov) Yes

Comment (2016-06-07 for -16)
No email
send info
Thank you for addressing my comments.

(Jari Arkko) No Objection

Comment (2014-11-25 for -11)
No email
send info
Thank you for doing this work!

(Alia Atlas) No Objection

Comment (2016-06-01 for -15)
No email
send info
I do agree with Benoit's Discuss that it would be excellent to have a template example of all the information to be
included - quite clearly.

I did find the document well-written and easy to understand.

Nit:

Section 4, p. 14 "or nor copy" should be "nor copy"

(Richard Barnes) No Objection

Comment (2014-11-24 for -11)
No email
send info
Section 2:
"consider delegating the namespace"
What do you mean by "delegating" here?  Having some organization other than IANA run it?  "Before using IANA, please consider not using IANA"?  Especially in light of the DNS example, it seems like this is not really what you mean.  "consider structuring the namespace in such a way that allocations can be made without central coordination."

Section 2.2.
"See Section y.1"
Isn't this a counterexample?  That's not what you would actually put in the registry; you would put "RFC [XXXX], Section y.1"

Deborah Brungard No Objection

(Ben Campbell) No Objection

Comment (2016-06-01 for -15)
No email
send info
I find this long, but quite readable. Only a few minor comments:

- 4, numbered list: Does it really make sense to list "IESG Approval" as more strict than "Standards Action?" (considering the latter also implies IESG approval...)

- 4.6: I assume a "specification required" registry could have guidance to the expert above and beyond the "public spec with enough detail part"? If so, a mention of that might be helpful.

- 5.2: "If a designated expert is conflicted..." is a bit ambiguous. An expert could be internally conflicted, have a conflict with others, or have a conflict of interest. I think,  from the remaining context, the last is what you have in mind?

-- I've seen cases of an AD approving a registration when the expert is indisposed or has a conflict of interest. Is that worth a mention? I guess it's sort of the same as appointing oneself as a temporary expert.

(Benoît Claise) (was Discuss) No Objection

Comment (2016-09-22 for -18)
No email
send info
thanks for addressing my DISCUSS point.

Alissa Cooper (was Discuss, No Objection) No Objection

Comment (2016-08-23 for -17)
No email
send info
Thanks for addressing my DISCUSS and comments. I have just two further comments about Section 1.3:

#3 under "In general" -- An author's first stop should be a WG chair or document shepherd, not an AD. 

#7 under "existing registry" -- I think this needs some qualification, such as "If the item contains contact information for a person, make sure it's clear ...." Otherwise I think this could confuse people into thinking that they need to say something about registration policy when all they're doing is registering a value in an existing registry.

(Spencer Dawkins) No Objection

Comment (2014-11-24 for -11)
No email
send info
I appreciate the robust reviews and discussion thus far.

(Stephen Farrell) (was Discuss) No Objection

Comment (2016-08-05 for -17)
No email
send info
Thanks for handling my remaining discuss point.

I didn't check these comments for -17, happy to chat about
any that remain relevant. (Or to not chat about 'em if that's
not needed:-)

- Almost twice as long as 5226 is not desirable. And in any
case the diff isn't usable. And I still think this is being
overly prescriptive in many many places. I also agree with
Benoit that a good set of examples would be more useful,
but maybe that needs to be a separate document now.

- 1.1 (and generally): I'm no so keen on the prescriptive
instructions here - guidance is fine but the should could be
take too seriously in para1.  If the overall draft/RFC is
clear enough for implementers in the end then the job is
done, regardless of where in the RFC the text resides. (And
you later also ask that e.g. rules for upper/lower case are
in IANA sections which conflicts with this.)

- 2, 2nd para: This seems out of place. I doubt most readers
will understand it here. Suggest moving this to later or
deleting it.

- 2.1: I'm not convinced document authors should pay
attention to these groups myself, I've only ever found that
makes finding and naming stuff harder. And I don't think
that we should be making life harder for authors in this
respect, if what's meant is that they ought understand this
before writing a document. 

- 3.1: The policy to disallow vanity isn't really IANA's
policy - it should be stated as the IETF's policy.

(Joel Jaeggli) No Objection

Comment (2014-11-18 for -11)
No email
send info
WFM

genart review discussion looks closed off to my satisfaction.

(Suresh Krishnan) No Objection

Comment (2016-06-01 for -15)
No email
send info
I share the concerns regarding the length of this document.

(Mirja Kühlewind) No Objection

Comment (2016-05-30 for -14)
No email
send info
A few comments for clarification:

1) I find the following sentence on private or experimental use slightly confusing:
"IANA does not record assignments from registries or ranges with this policy"
I would say that these values ARE assigned, as private or experimental by IANA.

2) Is "Hierarchical Allocation" (section 4.3) really an own policy given that IANA only registers "top-level" namespace and usually does not take track of the subnamespace handling anymore?

3) Double-checking: Does "RFC Required" mean that no expert review is needed? IS would be sufficient? Do we actually have this use case (given there are also no examples given here)?

(Kathleen Moriarty) No Objection

Comment (2014-11-24 for -11)
No email
send info
I agree with Adrian and others, that this document is important, but could be shorter.  I'd change to a Yes ballot with my questions getting a response and the draft getting a bit shorter (condense sections 2.3 & 4 - Alissa, and highlighting 4&6 - Adrian).

Questions:

Section 2.3.x Specification Required - an example of a low bar would be helpful…
        Section 2.3.1 says "Significant stable public documentation sufficient for
        interoperability."

    Is an email to an IETF list adequate? If so, can we list that as an example?
    I have had this questioned a few times recently (even from a former AD)
    and a few other ADs said an email on an IETF list would suffice because
    there is a stable way to point to it in the archives.  If this is the case,
    it would be great to document that so it is clear on the bar.  We don't want
    to have drafts coming through that are not necessary.  This should probably
    go in section 4.6 and I could see where this might be adequate for some
    additions to registries. It would be easy to argue that a URL to an IETF
    list email would be more stable than a document posted on a web site.

Section 4.4
There should probably be some privacy considerations listed since contact information is provided and maintained (contact person field and change controller).  Perhaps something like the following (I'm one to alternate options):

"When submitting contact information, the use of aliases or purpose specific business email addresses may be considered to protect the privacy of individuals personal contact information."


Security Considerations
Adrian & Alissa raised questions on security review and registration policies.  In my draft reviews, I've kept those points separate.  If there were security considerations specific to a requested registry addition over and above the considerations of the draft establishing the registry, then I'd want those documented within the specification required document text (whatever that stable document is). 


Reduction of text suggestions intended to be helpful:

Section 1.1
See Alissa commented on reducing this one as well, I agree.

Section 2.1
The second to last paragraph might be safely cut as well.  It looks like Alissa recommended the one before this and I think Benoit agrees on delating the one too from his comments.  It may be safe to cut both.

Alvaro Retana No Objection

(Martin Stiemerling) No Objection

Comment (2014-11-25 for -11)
No email
send info
In full support of the reviews which are in by now!

Barry Leiba Recuse