[apps-discuss] APPSDIR review of draft-ietf-mile-template-02

["Martin J. Dürst" <[e-mail]>]

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

  Please resolve these comments along with any other 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-template-02
  Title: Guidelines for Defining Extensions to IODEF
  Reviewer: Martin Dürst
  Review Date: 2012/02/29


  Summary: This document may be ready for publication as a BCP after 
fixing some issues.


Mayor Issues:

This draft is extremely short (the main text is less than three pages). 
I'm not at all sure if it is worth spending a BCP number on it. Given 
the fact that it's a deliverable of the mile WG, for the rest of this 
review, I'm assuming that this has been discussed before, and the answer 
was positive. However, I'm nevertheless seriously wondering whether it 
would not be better to have a bit more experience with actual extension 
documents before putting best current practice in RFC form. (I can only 
see two extension documents at http://datatracker.ietf.org/wg/mile/; 
experience from both the IETF and the W3C shows that it may take 
considerable time to get extensions right.)


Section 6, IANA Considerations, says:
    [IANA NOTE: The authors request that IANA include a note at the top
    of http://www.iana.org/assignments/xml-registry/schema.html, stating
    "Changes to the XML Schema registry for schema names beginning with
    'urn:ietf:params:xml:schema:iodef' are subject to an additional IODEF
    Expert Review [RFC5226]," and naming the designated expert.]
The example in the appendix 
(urn:ietf:params:xml:schema:iodef-myextension-1.0) shows that "names 
beginning with
'urn:ietf:params:xml:schema:iodef" refers to a simple textual prefix 
match. I'd expect that this is rather difficult to implement for IANA, 
and it definitely doesn't scale well at all (e.g. if other frameworks 
also add such restrictions). It would probably be better to have a 
separate registry e.g. under urn:ietf:params:xml:schema:iodef: or 
urn:ietf:params:xml:iodef-extension-schema: or some such.




  Minor Issues:

The text uses RFC 2119, but also uses the same keywords non-capitalized, 
which will lead to confusion. Examples:

    Note that in this final case, the extension will not be directly
    interoperable with IODEF implementations, and must "unwrap" the IODEF
    document from its container... (Section 4)

    ENUM for enumerated types; allowable values of the enumeration
    must be defined in the attribute definition

    In addition to schema reviews required by
    IANA, these registry requests should be accompanied by a review by
    IODEF experts to ensure the specified AdditionalData and/or ...
    (Intro, where one usually tries to avoid normative stuff)

    Lots and lots of 'should' in Appendix A, which all seem to be
    intended normatively and therefor would better go into the main text.


The shortness of the document tends to give the impression that writing 
an extension is easy. However, lots of details about extensions are 
already given in RFC5070, and it should be stressed very clearly that a 
good knowledge of RFC 5070 is a precondition to writing an extension. In 
addition, the document should not only reference RFC 5070, but also give 
more explicit pointers with section numbers in more cases.


Section 4 says:
The attributes which can be extended in this way are defined in Section
5.1 of [RFC5070], and limited to the following: [followed by long list]
This let me think that the list is just a copy of a similar list in 
RFC5070. But this is not the case. To get the list, the schema in 
RFC5070 has to be searched for ext- attributes. So these attributes are 
not actually defined in Section 5.1. Please clarify. Also, please tweak 
the format so such a simple list doesn't take up almost a whole page. 
Also please shortly explain the Element@attribute syntax, which is part 
of XML 'slang' but not a formal part of the XML core spec.


The last paragraph of Section 4 says:
    XML extensions within an AdditionalData or RecordItem element use a
    dtype of "xml", and SHOULD define a schema for the root element
    within the AdditionalData or RecordItem attribute.
The term "root element" is very clearly defined (and important) in XML, 
and the use here is different from this established use. Please change.


Security Section:
It is a general problem of this document that most of the meat is in the 
Appendix, but the problem is most apparent here. The Security Section 
should clearly *at least* mention that there is additional security 
stuff in the Appendix.


p. 9, A.4.1.  IODEF Data Types: This looks like a simple repetition from 
RFC 5070. A pointer should be better. Also, there are some inaccuracies:


"ML_STRING (for strings in encodings other than that of the enclosing 
document)": Here, RFC 5070 says:
    STRING data that represents multi-character attributes in a language
    different than the default encoding of the document is of the
    ML_STRING data type.

    The ML_STRING data type is implemented as an "iodef:MLStringType" in
    the schema.
RFC 5070 hopelessly mixes up languages and encodings. This draft 
shouldn't make things worse by claiming that XML can contain blobs of 
data encoded with a different encoding that the overall entity. 
(external entities can have a different encoding, but that's a separate 
matter).


"DATETIME for ISO 8601:2000 [RFC3339] encoded timestamps"
RFC 5070 correctly says that RFC 3339 is a subset of ISO 8601. This 
draft shouldn't give the impression that they are the same.


"TIMEZONE for timezones as encoded in section 2.9 of [RFC5070]."
"as encoded in" is confusing. ", encoded as defined in" is clearer.
Same for PORTLIST.


"URL for URLs as in [RFC3986].": This repeats an error from RFC5070. 
URLs are mentioned shortly in section 1.1.3 of RFC 3986, but not what's 
meant here. It at least say: "URL for URIs as in [RFC3986].". It is a 
problem that IRIs aren't allowed, but that's a problem that has to be 
fixed in RFC 5070, not here.



  Nits:

p. 4: involving integration with IODEF within ->
       involving integration of IODEF within

p. 5: SHOULD define the use the "meaning": use or meaning?

p. 8, A.3.  Applicability says:              "The primary goal of this
    section is to allow readers to see if an extension is indeed intended
    to solve a particular problem."
Are there extensions that are not intended to solve a particular 
problem? Please reword.

ibid: "This should also ??? the scope"

p. 8, A.4.  Extension Definition: "enumerating the new values with an
    explanation of the meaning of the new value": Singular/plural
    alignment problem

ibid: "or in another referenced MILE extension document": Why the 
restriction on MILE? Shouldn't any IODEF extension be okay?

p. 10, Section A.4:
              ... IODEF:Address element, which supports IPv4 and
    [RFC4291] IPv6 addresses, as well as MAC, ATM, and BGP autonomous
    system numbers.
Why do IPv6 addresses need a reference, but the others don't? At least, 
it should be "IPv6 addresses [RFC4291]". But why not just drop it?

p. 10, Section A.5: "Guidance should focus
    on ensuring the users of this extension do so in a secure fashion,"
    "do so": do what? Be more specific.

ibid: "represented by an extension": The paragraph has "this extension" 
in the first line, so it should be "represented by this extension" here.

p. 11: Appendix A.8: "given in the appendix" -> "given in Appendix A"


Regards,   Martin.