Re: [apps-discuss] APPSDIR review of draft-gregorio-uritemplate-07

[Mark Nottingham <[e-mail]>]

Thanks for the feedback. Responses inline.

On 07/12/2011, at 2:18 PM, Jiankang YAO 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 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-gregorio-uritemplate-07
> Title: URI Template
> 
> Reviewer: Jiankang Yao
> Review Date: December 7, 2011
> 
> Summary:
> 
> This draft is almost ready for publication as a Proposed Standard. But before publication, the following 
> issues should be considered or addressed.
> 
> Major issues:
> 
> 
> 1) In section 1.5.  Notational Conventions
> 
> There is a repetition of definition of ALPHA, DIGIT, HEXDIG,......
> 
> There is a discussion in IETF: we should not give the repetition of definition of ABNF syntax if we can refer it to other documents. The reason is that repetition may bring the errors or misunderstanding.
> 
> Suggestion: for example, we just say "ALPHA, DIGIT are imported from RFC5234" instead of repeating
> "ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z"

Is this a discussion that's already taken place?

> 2)   Normative reference [UNIV4] points to unicode version 4.0, but the current version of unicode is version 6. 
> 
> Suggestion or comments: Does this document apply to unicode version 4 only? or we can update the reference to unicode version 6?

Already v6 in SVN.

> 3)Normative reference [1] points to <http://lists.w3.org/Archives/Public/uri/> which is maillist archive and can not be Normative. 
> suggestion: delete it or move it to information reference.

Just changed in SVN.

> 4)There is a lot of "A URI Template" in section 1, but there is no precise definition of "URI Template" in section 1. The definition seems to appear on section 2.
> Comments: If the readers can understand it clearly, the definition should appear first.

Could you make a concrete proposal here?

> 5)The abstract said "This specification defines the URI Template syntax and the process
>   for expanding a URI Template into a URI reference".
> but in section 2, it said that "we define the URI-Template syntax in terms of the ABNF for Level 4".
> Suggestion: if we just define the syntax for level 4, it should mention it in the Abstract and introduction.

That's just noting that implementations of the lower levels aren't required to parse the full syntax, not that the syntax isn't defined for other levels.

> Discussion issues:
> 1)No IANA actions are required by this document. 
> 
> comments or suggestions:I suggest something in the document to be added to IANA, for example,the operators in section 2 and 3 of this document.
> If we register these operators in IANA, it will help the future use of these operators/characters.
> 
> for example:
> 
>      +   Reserved character strings;
> 
>      #   Fragment identifiers prefixed by "#";
> 
>      .   Name labels or extensions prefixed by ".";
> 
>      /   Path segments prefixed by "/";
> 
>      ;   Path parameter name or name=value pairs prefixed by ";";
> 
>      ?   Query component beginning with "?" and consisting of
>          name=value pairs separated by "&"; and,
> 
>      &   Continuation of query-style &name=value pairs within
>          a literal query component.
> 
>   The operator characters equals ("="), comma (","), exclamation ("!"),
>   at-sign ("@"), and pipe ("|") are reserved for future extensions.

I think that's worth discussion, but my initial reaction is that a registry here will make interoperability much more difficult, and possibly harm adoption. 

> Minor Issues:
> 
> 1) "after UTF-8 encoding" in the first paragraph In section 1.2 Levels and Expression Types
> need a reference to UTF-8

In SVN.

> 2) In section 1.3.  Design Considerations
>  where " Mechanisms similar to URI Templates have been defined within several
>   specifications, including WSDL, WADL and OpenSearch."
> 
>  What is WSDL WADL and OpenSearch? 
>  Suggestion: need a reference or explaination for these acronyms or special words.

In SVN.

> 3) In the 4th paragraph of section 1.6,Normalization Form C needs a reference.

There's a reference to UTR15 directly above, in the same (admittedly lengthy) paragraph.

Regards,

--
Mark Nottingham   http://www.mnot.net/