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

From: "Jiankang YAO" <[email-masked]>
Date: Wed, 7 Dec 2011 11:18:58 +0800

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.

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 7 Dec 2011 20:07:48 +1100

Thanks for the feedback. Responses inline.

> "ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z"

Is this a discussion that's already taken place?

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

> suggestion: delete it or move it to information reference.

Just changed in SVN.

> Comments: If the readers can understand it clearly, the definition should appear first.

Could you make a concrete proposal here?

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

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

> need a reference to UTF-8

In SVN.

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

---

From: Frank Ellermann <[email-masked]>
Date: Wed, 7 Dec 2011 16:32:53 +0100

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

Well, we're not supposed to "redefine" terms unless we really want it,
but I fear that your suggestion misses another important point:

> for example, we just say "ALPHA, DIGIT are imported from RFC5234"

If you write that only in prose Bill's syntax checker would flag the
terms as "undefined".  IMO the best way for imports is something in
the direction of

   ALPHA = <ASCII letters as specified in appendix X of RFC 5234>

Or similar, it's an editorial nit, and not really a major issue here,
after all this draft doesn't try to redefine any STD 68 terms ;-)

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

LOL, yes, that is an xml2rfc artefact, at some point it tries to dump
all pending URI references.  AFAIK the authors intend to add three or
more missing informative references, that should also take care of the
discussion list URI.  Using <eref ... /> might also help to get rid of
this non-normative oddity.

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

IMHO IANA registries should only be created when they are required,
and if they are (supposed to be) helpful.  That's not the case here,
all used operator characters are fully specified, and all remaining
potential operator characters are enumerated:  It is the job of any
later draft to create a registry if the "KISS" approach (= complete
enumeration in one memo) does not more work.

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

For some reasons major parts of the terminology ended up in 1.5 and
1.6 _after_ some preliminary uses in 1.2 ... 1.4.  Normally the
order of 1.x sections in a draft is no issue, but here 1.2 is rather
long; hopefully the order can be rearranged, or improved by forward
references.

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

The given reference UAX #15 is good enough for my purposes, this is
no draft where a reference to RFC 5198 would be clearer.  YMMV, and
<http://www.rfc-editor.org/rfc-style-guide/abbrev.expansion.txt>
lists "UTF-8" as a well-known term, but does not yet star "NFC".

-Frank

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Wed, 7 Dec 2011 09:11:39 -0800

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of Mark Nottingham
> Sent: Wednesday, December 07, 2011 1:08 AM
> To: Jiankang YAO
> Cc: [email-masked]; IETF Apps Discuss
> Subject: Re: [apps-discuss] APPSDIR review of draft-gregorio-uritemplate-07
> 

I agree that re-stating definitions that are better replaced by references to them is the wiser move.

> > comments or suggestions:I suggest something in the document to be

I don't think this is necessary.  The point of registries is to make something extensible without having to modify its defining document, such as adding header fields to email or MIME types, etc.  In this case, declaring a character as an operator that's not already an operator can alter the semantics of existing templates based on the initial RFC.  So if the set of operators is to change, I suggest that a new RFC would be required, obsoleting previous ones.

-MSK

---

From: Graham Klyne <[email-masked]>
Date: Wed, 07 Dec 2011 18:21:00 +0000

On 07/12/2011 09:07, Mark Nottingham wrote:
>> >        &    Continuation of query-style&name=value pairs within

I agree that this does not seem an appropriate case for an IANA registry.

(a) The design is very closely coupled with URI syntax, which IMO makes it more 
usable.  A registry might encourage divergence.

(b) Addition of new "operators" could potentially have deep impact on template 
handling code, and such might be encouraged by allowing IANA registration of 
extensions.  I think this could harm interoperability if extensions are registered.

(c) The overhead of creating and managing a registry doesn't seem to be 
justified by any clear benefit.

#g
--

---

From: "Jiankang YAO" <[email-masked]>
Date: Thu, 8 Dec 2011 14:41:56 +0800

----- Original Message ----- 
From: "Mark Nottingham" <[email-masked]>
To: "Jiankang YAO" <[email-masked]>
Cc: "IETF Apps Discuss" <[email-masked]>; <[email-masked]>
Sent: Wednesday, December 07, 2011 5:07 PM
Subject: Re: APPSDIR review of draft-gregorio-uritemplate-07

> "ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z"

==>Is this a discussion that's already taken place?

yes. the rule has been followed by EAI WG.

> Comments: If the readers can understand it clearly, the definition should appear first.

==>Could you make a concrete proposal here?

what is "URI Template" should be defined in section 1.
there is no precise or clear definition of "URI Template" in section 1.

Jiankang Yao

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 8 Dec 2011 17:45:39 +1100

> yes. the rule has been followed by EAI WG.

Do you have a reference? I.e., is this an IESG ruling, or something that was decided in that WG? As has mentioned, taking the approach you outline will result in ABNF errors.

> there is no precise or clear definition of "URI Template" in section 1.

I was hoping for something more substantial. Let me take another look at it...

Regards,

---

From: Julian Reschke <[email-masked]>
Date: Thu, 08 Dec 2011 09:35:42 +0100

On 2011-12-08 07:45, Mark Nottingham wrote:
> ...

It depends; BAP, Bill's ABNF Parser, when run from the command line, can 
include core rules from a file.

Best regards, Julian

---

From: "t.petch" <[email-masked]>
Date: Thu, 8 Dec 2011 12:23:20 +0100

----- Original Message -----
From: "Mark Nottingham" <[email-masked]>
To: "Jiankang YAO" <[email-masked]>
Cc: <[email-masked]>; "IETF Apps Discuss"
<[email-masked]>
Sent: Thursday, December 08, 2011 7:45 AM
Subject: Re: [apps-discuss] APPSDIR review of draft-gregorio-uritemplate-07
>
> > 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.
> I was hoping for something more substantial. Let me take another look at it...

I agree that section 1 is a little weak but think the Abstract gets it (almost)
right.

"   A URI Template is a compact sequence of characters for describing a
   range of Uniform Resource Identifiers through variable expansion."

I would prefer
"  A URI Template is a compact sequence of characters which describes a
   range of Uniform Resource Identifiers through variable expansion."

and I would put that as section 1 first sentence, perhaps adding

"... A URI Template is not per se a URI but rather a potential URI in which
certain parts have been replaced by operators and variable names; the operators
have
been chosen to facilitate the construction of URIs, allowing the ready
generation
of such as name=value, or just value, in paths, queries and fragments, both of
single values or of lists of values."

> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>
>

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 8 Dec 2011 23:36:20 +1100

I'll take that on board, thanks.

---

From: "Roy T. Fielding" <[email-masked]>
Date: Thu, 8 Dec 2011 14:23:50 -0800

> Do you have a reference? I.e., is this an IESG ruling, or something that was decided in that WG? As has mentioned, taking the approach you outline will result in ABNF errors.

FWIW, I am opposed to making this change.  IMO, it is trivial for
any one of the reviewers prior to publication to verify that the
rules were copy and pasted correctly.  That's why they are all in
one section.  After that, the specification will be read by thousands
of people and used as a reference in hundreds of implementations, and
occasionally even automatically checked with abnf parsers.  The cost
of splitting the normative information across multiple specs is not
worth the theoretical notion that someone might copy them incorrectly.

These are not cases of independently developed protocol elements
that might be updated over time.  They are simply character sets.
We don't want them to be updated over time.  And they are essential
to understanding exactly what characters are allowed in each of
the rules in the main spec.

> I was hoping for something more substantial. Let me take another look at it...

It is defined in the abstract. *shrug*

....Roy

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 09 Dec 2011 12:38:49 -0700

<hat type='individual'/>

On 12/7/11 11:45 PM, Mark Nottingham wrote:
>>> Suggestion: for example, we just say "ALPHA, DIGIT are imported
>>> from RFC5234" instead of repeating "ALPHA          =  %x41-5A /
>>> %x61-7A   ; A-Z / a-z"
>> 
> Do you have a reference? I.e., is this an IESG ruling, or something
> that was decided in that WG? As has mentioned, taking the approach
> you outline will result in ABNF errors.

As far as I know, there is no "rule" here.

>> 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.
>> what is "URI Template" should be defined in section 1. there is no
>> precise or clear definition of "URI Template" in section 1.
> 

Why not just copy the first sentence of the Abstract?

   A URI Template is a compact sequence of characters for describing a
   range of Uniform Resource Identifiers through variable expansion.

I suggest adding it to the start of this paragraph:

   URI Templates provide a mechanism for abstracting a space of resource
   identifiers such that the variable parts can be easily identified and
   described.  URI templates can have many uses, including discovery of
   available services, configuring resource mappings, defining computed
   links, specifying interfaces, and other forms of programmatic
   interaction with resources.  For example, the above resources could
   be described by the following URI templates:

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 11 Dec 2011 09:15:40 +1100

>   be described by the following URI templates:

Seems workable to me.

Thanks,

---

From: Peter Saint-Andre <[email-masked]>
Date: Sat, 10 Dec 2011 15:28:34 -0700

>>   be described by the following URI templates:

To be clear, I suggested:

(where the first sentence is copied from the Abstract...)

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 11 Dec 2011 09:39:41 +1100

Yes. I ended up splitting it into two paragraphs, with the new sentence as the first (due to the combined length).

Cheers,

---

From: Peter Saint-Andre <[email-masked]>
Date: Sat, 10 Dec 2011 15:55:53 -0700

> Yes. I ended up splitting it into two paragraphs, with the new sentence as the first (due to the combined length).

Whatever works for you. :)

---

From: Alexey Melnikov <[email-masked]>
Date: Sat, 10 Dec 2011 23:14:57 +0000

> Is this a discussion that's already taken place?
By copying definitions from other specs (instead of referencing them), 
you are risking introducing new errors and also risking that your 
document will not be updated when the referenced documents are updated.

My personal preference is not to copy definitions, but there is no hard 
rule on this.

---

From: "t.petch" <[email-masked]>
Date: Sun, 11 Dec 2011 10:31:36 +0100

----- Original Message -----
From: "Alexey Melnikov" <[email-masked]>
To: "Mark Nottingham" <[email-masked]>
Cc: "IETF Apps Discuss" <[email-masked]>;
<[email-masked]>
Sent: Sunday, December 11, 2011 12:14 AM

> >> 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.
> My personal preference is not to copy definitions, but there is no hard

I am with Roy on this one - keep it in.

Tom Petch