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

[Brian Trammell <[e-mail]>]

Hello, Martin,

Many thanks for your (thorough!) review! Replies to these points, inline.

On Feb 29, 2012, at 11:28 AM, Martin J. Dürst wrote:

> 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.)

The status of the draft was indeed discussed in the WG, and we were indeed expecting a discussion on its intended status after sending it up. The content of the template itself is essentially informational: we have a lot of contributions from people just coming into the IETF community, so we wanted a template to help jumpstart these authors's efforts. 

On the other hand, the IANA note requires a standards action. BCP was the result, but we agree it's a little weird.

> 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.

I suppose we could use a separate registry if it simplifies things (we honestly hadn't considered the scalability issues that would result from this being a precedent, good point), but there are already extensions in the present registry following the "textual match" semantics:

iodef-phish-1.0	 urn:ietf:params:xml:schema:iodef-phish-1.0 [RFC5901]
iodef-rid-1.0	 urn:ietf:params:xml:schema:iodef-rid-1.0   [RFC6045]
iodef-rid-2.0	 urn:ietf:params:xml:schema:iodef-rid-2.0   [RFC-ietf-mile-rfc6045-bis-11.txt]

So, we'd have to split the registry. 

It also appears that "subregistries" (e.g. urn:ietf:params:xml:schema:pidf:*) are kept in the same registry, so I'm not sure whether 'urn:ietf:params:xml:schema:iodef-' is harder to manage than 'urn:ietf:params:xml:schema:iodef:'.

Perhaps the right thing here is to refer this to IANA?

> 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.

Good points all; we'll have a look at these and make a full 2119-language pass. Note of course that some of the non-2119 words are not intended normatively.

As for upgrading the shoulds in Appendix A and moving them up, I'm not sure that that would make the document easier to use. These are advisory (appendix A is essentially the Informational part of the document), and bringing them outside the template makes them harder to refer to. Authors are intended to follow the template by copying the document template out of appendix A (this becomes much easier when they have the XML source), then following the instructions to fill it in.

(Indeed, I see on review here that we're missing A.7.1 normative references and A.7.2 informative references)

> 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.

Good point; we'll do this.

> 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.

We can add section references for each of these.

> 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.

Check.

> 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.

Indeed. Is there a preferred terminology for the root of a subtree within a document?

> 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.

I'm confused here. Where's the 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.

I think we'd like to keep this section in the template, so we'll make these fixes.

> Nits:

(will fix these too)

> 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?

Yep; fixed this elsewhere but missed this one...

> 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?

"IPv6 addresses formatted as in [RFC4291]" was the intent here.

> 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"

Best regards, and thanks again!

- Brian