Subject: [mile] Reference and related nits in draft-ietf-mile-enum-reference-format

From: "Black, David" <[email-masked]>
Date: Sun, 18 May 2014 22:39:15 -0400

Hi Adam,

> With respect to your first sentence above, I assert that the document does not
> "seem" to update ReferenceName, but actually does. :-)  Is it necessary to
> explicitly state the obvious in this case?  I'm happy to update the document,
> but I'm not sure I believe such a statement is necessary.  If it is necessary,
> then a single sentence can be added to the abstract making the statement.
> Thoughts here?

In this case, it is necessary to state the obvious for the sake of clarity -
I've been there and had to do that ;-).  In addition to a sentence in the
abstract, the header on the title page needs an "Updates: 5070 (if approved)"
line, and a section should be added entitled "Summary of Changes to RFC 5070"
that identifies the changes.

For a somewhat longer recent example, see RFC 7146:
	http://datatracker.ietf.org/doc/rfc7146/

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

Here are some additional editorial nits that need attention ...

a) I recently had another draft dinged by the IESG for using a citation as
a word in a sentence e.g., "[IODEF]" in the first sentence in Section 2:

   The need is to place enumeration identifiers and their references in
   [IODEF]'s Reference class.

Believe it or not, the appropriate change is "[IODEF]" -> "IODEF [IODEF]" -
I suggest just doing this and not asking why :-). The whole draft should be
checked for other uses of citations in this fashion.

b) In addition, references should not be cited in the abstract, so I believe
the appropriate changes to the two citations in the abstract are:

   The Incident Object Description Exchange Format [IODEF] provides a

		"[IODEF]" -> "(IODEF)"

   Reference class used to reference external entities (such as
   enumeration identifiers).  However, the method of external entity
   identification has been left unstructured.  This document describes a
   method to provide structure for referencing external entities for the
   [IODEF] Reference class.

		"[IODEF]" -> "IODEF"

Otherwise, the draft still looks good.

Thanks,
--David

> -----Original Message-----
> From: mile [mailto:[email-masked]] On Behalf Of Adam Montville
> Sent: Sunday, May 18, 2014 7:58 PM
> To: Alexey Melnikov
> Cc: <[email-masked]>; [email-masked]
> Subject: Re: [mile] Working Group Last Call for draft-ietf-mile-enum-
> reference-format
> 
> 
> On May 11, 2014, at 2:54 PM, Alexey Melnikov <[email-masked]>
> wrote:
> 
> >
> >> On 8 May 2014, at 12:30, "Takeshi Takahashi" <[email-masked]>
> wrote:
> >>
> >> Greetings, all,
> >>
> >> This is the Working Group Last Call for
> >> draft-ietf-mile-enum-reference-format, IODEF Enumeration Reference Format.
> >>
> >> The last call starts now, and ends Monday 26 May 2014.
> >>
> >> Please read the latest revision of the draft,
> >> http://tools.ietf.org/html/draft-ietf-mile-enum-reference-format-04, and
> >> send your comments to the mailing list; we'd also appreciate a comment if
> >> you're fine with the draft as is.
> >
> > Hi,
> > Below is my review of the draft:
> >
> > General comment: Is this intended as Proposed Standard? The draft header
> doesn't say the document type.
> 
> I'll update this, thank you.
> 
> >
> > The document seems to update ReferenceName syntax to allow for nested XML
> elements. However the document doesn't say that.
> > In relationship to this: would this document cause any interoperability
> issues with programs that can only parse the old schema?
> 
> I am unsure about interoperability issues, but they should be minimal and are
> likely implementation specific.
> 
> I tried an experiment where I generated some code (JAXB) for IODEF 1.0 and
> then fed it a modified recon example (Section 7.2 from RFC 5070).  The
> <ReferenceName> element contained an <EnumRef> element as opposed to the
> string "nmap".  Unmarshalling seemed to work without issue, but when examining
> the ReferenceName element , the only thing present was a newline character.
> In an example that doesn't use generated code but instead uses a SAX or DOM
> parser, we can grab the inner XML.  Using a validating DOM/SAX/other parser
> will, of course, break if the enumeration reference XML is embedded, so
> parsers will need to be updated.
> 
> I'm not a professional implementor, so it would be good to hear considerations
> from others.  Then, should these considerations be placed in the document (I
> assume that was the good point of raising the issue)?
> 
> With respect to your first sentence above, I assert that the document does not
> "seem" to update ReferenceName, but actually does. :-)  Is it necessary to
> explicitly state the obvious in this case?  I'm happy to update the document,
> but I'm not sure I believe such a statement is necessary.  If it is necessary,
> then a single sentence can be added to the abstract making the statement.
> Thoughts here?
> 
> 
> >
> >
> > 4  IANA Considerations
> >
> >      Note that certain name requests should not be permitted as either
> >      Full Name or Abbreviation entries for the requested IANA table.
> >
> > Do you mean restrictions imposed by the syntax described below or something
> else? If you intended to exclude some specific keywords, where is the list of
> them defined? Either way, I think you need to clarify. If you just meant the
> ABNF restrictions, I suggest adding something like "The restrictions are
> specified in the ABNF below".
> >
> >      Allocation Policy: Expert Review [RFC5226] and Specification
> >      Required [RFC5226]
> >
> > Nit: I think it would be better to say "Specification Required (which
> implies Expert Review)".
> >
> > _______________________________________________
> > mile mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/mile

---

From: Adam Montville <[email-masked]>
Date: Mon, 19 May 2014 06:58:55 -0700

David, thank you.  I've noted all of these and will make appropriate updates.

Are there other comments other than those posed by Alexey and David?

---

From: "Takeshi Takahashi" <[email-masked]>
Date: Thu, 22 May 2014 20:44:45 +0900

Hi Adam,

I remember that we had discussion on the Index field last year.
We have a field for the Index and not for version number.
That is because "the Index field in the XML unambiguously indicates which
IANA registry entry is to be used to correctly reference the enumeration
specification, which avoids interpretation of version strings that may have
specification-specific formats" (copied from the draft).
Yes, this was what I understood in the discussion last year.

Now I am reading the document again, and have stuck on one question.
Maybe I have some misunderstanding or have forgotten some discussion, but I
would appreciate if you could clarify the issue below.

If we have Index field, do we need the Abbreviation field?

Below is the example described in the draft.
<EnumRef>
  <Abbreviation>CXI</Abbreviation>
  <Index>1</Index>
  <ID>CXI-1234-XYZ</ID>
</EnumRef>

But can we simply write like this?
<EnumRef>
  <Index>1</Index>
  <ID>CXI-1234-XYZ</ID>
</EnumRef>

If we have the Index value, we can uniquely identify the specification and
version, correct?

Take

> From: Adam Montville [mailto:[email-masked]]
> Sent: Monday, May 19, 2014 10:59 PM
> To: Black, David
> Cc: Alexey Melnikov; <[email-masked]>; [email-masked]
> Subject: Re: Reference and related nits in
> draft-ietf-mile-enum-reference-format
> 
> >> With respect to your first sentence above, I assert that the document
> >> does not "seem" to update ReferenceName, but actually does. :-)  Is
> >> it necessary to explicitly state the obvious in this case?  I'm happy
> >> to update the document, but I'm not sure I believe such a statement
> >> is necessary.  If it is necessary, then a single sentence can be added
> to the abstract making the statement.
> >> Thoughts here?
> >
> > In this case, it is necessary to state the obvious for the sake of
> > clarity - I've been there and had to do that ;-).  In addition to a
> > sentence in the abstract, the header on the title page needs an
"Updates:
> 5070 (if approved)"
> > a) I recently had another draft dinged by the IESG for using a
> > citation as a word in a sentence e.g., "[IODEF]" in the first sentence
> in Section 2:
> >
> > Believe it or not, the appropriate change is "[IODEF]" -> "IODEF
> > [IODEF]" - I suggest just doing this and not asking why :-). The whole
> > draft should be checked for other uses of citations in this fashion.
> >
> > b) In addition, references should not be cited in the abstract, so I
> > believe the appropriate changes to the two citations in the abstract
are:
> http://tools.ietf.org/html/draft-ietf-mile-enum-reference-format-04
> >>>> , and send your comments to the mailing list; we'd also appreciate
> >>>> a comment if you're fine with the draft as is.
> >>>
> >>> Hi,
> >> I am unsure about interoperability issues, but they should be minimal
> >> and are likely implementation specific.
> >>
> >> I tried an experiment where I generated some code (JAXB) for IODEF
> >> 1.0 and then fed it a modified recon example (Section 7.2 from RFC
> >> 5070).  The <ReferenceName> element contained an <EnumRef> element as
> >> opposed to the string "nmap".  Unmarshalling seemed to work without
> >> issue, but when examining the ReferenceName element , the only thing
> present was a newline character.
> >> In an example that doesn't use generated code but instead uses a SAX
> >> or DOM parser, we can grab the inner XML.  Using a validating
> >> DOM/SAX/other parser will, of course, break if the enumeration
> >> reference XML is embedded, so parsers will need to be updated.
> >>
> >> I'm not a professional implementor, so it would be good to hear
> >> considerations from others.  Then, should these considerations be
> >> placed in the document (I assume that was the good point of raising the
> issue)?
> >>
> >> With respect to your first sentence above, I assert that the document
> >> does not "seem" to update ReferenceName, but actually does. :-)  Is
> >> it necessary to explicitly state the obvious in this case?  I'm happy
> >> to update the document, but I'm not sure I believe such a statement
> >> is necessary.  If it is necessary, then a single sentence can be added
> to the abstract making the statement.
> >> Thoughts here?
> >>
> >>
> >>>
> >>>
> >>> 4  IANA Considerations
> >>>
> >> else? If you intended to exclude some specific keywords, where is the
> >> list of them defined? Either way, I think you need to clarify. If you
> >> just meant the ABNF restrictions, I suggest adding something like
> >> "The restrictions are specified in the ABNF below".
> >>>

---

From: "Adam W. Montville" <[email-masked]>
Date: Thu, 22 May 2014 06:22:39 -0700

> On May 22, 2014, at 4:44 AM, "Takeshi Takahashi" <[email-masked]> wrote:
> 
> Hi Adam,
> 

I believe you are correct, and I can't think of a reason to keep the abbreviation field.

---

From: Eric Burger <[email-masked]>
Date: Wed, 28 May 2014 06:10:07 -0400

All it would do it introduce an opportunity to get it wrong. What do you do if the <Abbreviation/> does not match the <Index/>? If the answer is “ignore it,” it means <Abbreviation/> has no protocol value. If the answer is “fail the message with an error,” many implementors are likely to ignore it and some implementors will fail and interoperability will suffer.

Drop <Abbreviation/>.

---

From: "Adam W. Montville" <[email-masked]>
Date: Wed, 28 May 2014 09:01:12 -0500

> All it would do it introduce an opportunity to get it wrong. What do you do if the <Abbreviation/> does not match the <Index/>? If the answer is “ignore it,” it means <Abbreviation/> has no protoco…

The -05 version of the draft (updated just yesterday) removes Abbreviation and integrates more specifically with the IODEF 1.00 schema (i.e. as described in RFC 5070) to create a 1.01 schema.

---

From: "Adam W. Montville" <[email-masked]>
Date: Wed, 28 May 2014 09:06:11 -0500

---

From: "Takeshi Takahashi" <[email-masked]>
Date: Thu, 29 May 2014 10:24:18 +0900

Let me forward the email here.

> From: Adam W. Montville [mailto:[email-masked]]
> Sent: Wednesday, May 28, 2014 11:01 PM
> To: Eric Burger
> Cc: Takeshi Takahashi; <[email-masked]>
> Subject: Re: [mile] Reference and related nits in
> > All it would do it introduce an opportunity to get it wrong. What do you
> do if the <Abbreviation/> does not match the <Index/>? If the answer is
> "ignore it," it means <Abbreviation/> has no protocol value. If the answer
> is "fail the message with an error," many implementors are likely to
ignore
> it and some implementors will fail and interoperability will suffer.
> >
> > Drop <Abbreviation/>.
> 
> The -05 version of the draft (updated just yesterday) removes Abbreviation
> and integrates more specifically with the IODEF 1.00 schema (i.e. as
> described in RFC 5070) to create a 1.01 schema.
> 
> 
> >
> >>> That is because "the Index field in the XML unambiguously indicates
> >>> which IANA registry entry is to be used to correctly reference the
> >>> enumeration specification, which avoids interpretation of version
> >>> strings that may have specification-specific formats" (copied from the
> draft).
> >>> Maybe I have some misunderstanding or have forgotten some
> >>> discussion, but I would appreciate if you could clarify the issue
below.
> >>> If we have the Index value, we can uniquely identify the
> >>> specification and version, correct?
> >>
> >>>>>> With respect to your first sentence above, I assert that the
> >>>>>> document does not "seem" to update ReferenceName, but actually
> >>>>>> does. :-)  Is it necessary to explicitly state the obvious in
> >>>>>> this case?  I'm happy to update the document, but I'm not sure I
> >>>>>> believe such a statement is necessary.  If it is necessary, then
> >>>>>> a single sentence can be added
> >>>>> clarity - I've been there and had to do that ;-).  In addition to
> >>>>> a sentence in the abstract, the header on the title page needs an
> >>> "Updates:
> >>>> 5070 (if approved)"
> >>>>> line, and a section should be added entitled "Summary of Changes
> >>>>> to RFC
> >>>> 5070"
> >>>>> The need is to place enumeration identifiers and their references
> >>>>> in [IODEF]'s Reference class.
> >>>>>
> >>>>> [IODEF]" - I suggest just doing this and not asking why :-). The
> >>>>> whole draft should be checked for other uses of citations in this
> fashion.
> >>>>>
> >>>>> b) In addition, references should not be cited in the abstract, so
> >>>>> I believe the appropriate changes to the two citations in the
> >>>>> abstract
> >>> are:
> >>>>>
> >>>>> identification has been left unstructured.  This document
> >>>>> describes
> >>>> a
> >>>>> method to provide structure for referencing external entities for
> >>>>> the [IODEF] Reference class.
> >>>>>
> >>>>>      "[IODEF]" -> "IODEF"
> >>>>>
> >>>>>> Subject: Re: [mile] Working Group Last Call for
> >>>>>> draft-ietf-mile-enum- reference-format
> >>>>>>
> >>>>>>
> >>>>>>>> draft-ietf-mile-enum-reference-format, IODEF Enumeration
> >>>>>>>> Reference
> >>>> Format.
> >>>>>>>>
> >>>>>>>> , and send your comments to the mailing list; we'd also
> >>>>>>>> appreciate a comment if you're fine with the draft as is.
> >>>>>>>
> >>>>>>> Hi,
> >>>>>> I am unsure about interoperability issues, but they should be
> >>>>>> minimal and are likely implementation specific.
> >>>>>>
> >>>>>> 1.0 and then fed it a modified recon example (Section 7.2 from
> >>>>>> RFC 5070).  The <ReferenceName> element contained an <EnumRef>
> >>>>>> element as opposed to the string "nmap".  Unmarshalling seemed to
> >>>>>> work without issue, but when examining the ReferenceName element
> >>>>>> , the only thing
> >>>>>> In an example that doesn't use generated code but instead uses a
> >>>>>> SAX or DOM parser, we can grab the inner XML.  Using a validating
> >>>>>> With respect to your first sentence above, I assert that the
> >>>>>> document does not "seem" to update ReferenceName, but actually
> >>>>>> does. :-)  Is it necessary to explicitly state the obvious in
> >>>>>> this case?  I'm happy to update the document, but I'm not sure I
> >>>>>> believe such a statement is necessary.  If it is necessary, then
> >>>>>> a single sentence can be added
> >>>>>>>  Note that certain name requests should not be permitted as
> >>>>>>> either  Full Name or Abbreviation entries for the requested IANA
> table.
> >>>>>>>
> >>>>>> else? If you intended to exclude some specific keywords, where is
> >>>>>> the list of them defined? Either way, I think you need to
> >>>>>> clarify. If you just meant the ABNF restrictions, I suggest
> >>>>>> adding something like "The restrictions are specified in the ABNF
> below".
> >>>>>>>