Subject: [mile] Apps Area review of draft-ietf-mile-enum-reference-format-05

From: Tim Bray <[email-masked]>
Date: Wed, 25 Jun 2014 10:25:56 -0700

I have been selected as the Applications Area Directorate reviewer for
this draft (for background on appsdir, please
seehttp://trac.tools.ietf.org/area/app/trac/wiki/ApplicationsAreaDirectorate
).

Please resolve these comments along with any other Last Call comments
you may receive. Please wait for direction from your document shepherd
or AD before posting a new version of the draft.

Document:draft-ietf-mile-enum-reference-format-05
Title: IODEF Enumeration Reference Format
Reviewer:Tim Bray
Review Date: June 25, 2014

There are problems in this document which should be addressed before
publication.

1. The description uses many technical terms without first either
defining them or giving a reference for their meaning:  “Reference
class”, “Enumeration values”, "enumeration identifiers and their
references”.  This reviewer found the spec really hard to understand
due to the heavy use of specialized language with no definition of
terms.  NOTE: It may be reasonable to decide that this specification
is only intended to be read by those who are already sufficiently
expert to understand the terms, in which case this wouldn’t be a
problem.

2. Why introduce two child elements, rather than just add an
attribute?  Here’s the example:

<ReferenceName>
   <Index>1</Index>
   <ID>CXI-1234-XYZ</ID>
</ReferenceName>

An attribute would feel more idiomatic. Why not

<ReferenceName Index="1">CXI-1234-XYZ</ReferenceName> ?

Suggested improvements to the spec:

Abstract: This at least should be comprehensible to nonspecialists.
Here is a suggested rewrite:

The The Incident Object Description Exchange Format (IODEF) is an XML
construct which contains identifiers, using an element called
ReferenceName, that come from enumerations of fixed string values.  At
the moment the content of ReferenceName is just a string field, which
is unsatisfactory because it is necessary to know both the value and
the enumeration from which it comes. This specification changes the
definition of ReferenceName by adding structure which identifies both
the value and the enumeration from which it comes.  This is done
indirectly through an IANA registry.

In the first paragraph of section 2, the word “resulting” is wrong.  I
think the sentence is trying to say “to require that the ReferenceName
element identify both the enumeration from which the name comes and
the name itself, and to identify enumerations via an IANA registry,
which includes useful metadata such as a link to the enumeration’s
specification.”

FIGURE 1 identifies the structure of Reference *before* this draft.
Why not provide before-and-after pictures?

Section 2, para beginning “Per IODEF”, language is clumsy “specific
references, such as ... are referenced.”  Perhaps something like
“becomes problematic when the ReferenceName comes from a particular
enumeration such as CVE [CVE], CCE [CCE], or CPE [CPE] and it is not
obvious to an implementer how to determine which. One solution,
presented here, is to add structure to the ReferenceName to identify
both the value and the enumeration it comes from“.

Section 2.1, should the title become something like “Revised
ReferenceName Format”?

Also, sort of roundabout. How about “... and requires a child elements
named "Index" and "ID"; the first contains an integer which identifies
an entry in an IANA registry (see Section 4), which specifies the
specification the actual enumeration value, provided as the content of
the “ID” child element.  Or, as suggested above, make Index an
attribute, then you don’t need ID.

The name “Index” is lousy.  Yes, it’s an integer index into an IANA
registry, but element names should describe what the content means,
not its data format. This identifies is a enumeration or a namespace
or a specification.  Maybe SpecIndex? or Enumeration?

Also, in the IANA table, shouldn’t the spec say something about what
kind of thing the Specification URI is supposed to identify?  An I-D?
An RFC? An XSD?

-- 
- Tim Bray (If you’d like to send me a private message, see
https://keybase.io/timbray)