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

["Jiankang YAO" <[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 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"


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?


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.


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.


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.

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.


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


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.


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