URI Template
draft-gregorio-uritemplate-08

[Ballot discuss]
The Gen-ART Review by Vijay Gurbani on 1-Jan-2012 raised two minor
  issues.  I have not seen a response to this review, but I believe
  it deserves a response.  The two issues are repeated below.

  - S3.2.1, first paragraph: "A variable defined as an associative
  array of (name, value) pairs is considered undefined if the
  array contains zero members or if all member names in the array
  have undefined values."

  Here, do you mean "if all member names in the array have no
  values."?  That is, "undefined values" implies that values are
  present in the template, but are not understood.  On the other
  hand, "no values" implies the absence of any values at all.  In my
  reading of the text, it appears that "no values" conveys more
  context than "undefined values".

  - S4, general comment: I am not sure where the template expansion is
  done --- at the client (browser) or at the origin server (the draft
  does not enunciate this, and if it does, I may have missed it).  If
  the expansion is done at the origin server, I suspect that one can
  keep it a bit more busy by asking it to perform unnecessary
  template expansion for a resource that may be accessed normally
  even without template expansion.  Is it worth documenting this at
  all in the Security Considerations section?  (Clearly, if the expansion
  is done at the client, then it is the client incurring the expense
  of expansion.  Insofar as the client is malicious, it is best to
  let it expend as much effort as necessary.)

[Ballot comment]
2.2: I'm not clear from what is said in section 3 or Appendix A what happens when an op-reserve appears in a template that is being processed where the processor doesn't recognize these operators, in particular '$', '(', and ')'. Are they all treated as error conditions? If so, where in the algorithm.

2.3: Do you really want varnames to be able to end with "." or "_" or begin with "_" or pct-encoded? If you want only internal ".", then you want:

varname = varchar *(["."] varchar)

If you only want internal "_" and pct-encoded as well, then:

varname = ALPHA / DIGIT *(["_" / "." / pct-encoded] / ALPHA / DIGIT)

I don't care, but the current construct (can't begin with ".", but otherwise anything goes) seemed like an odd choice.

2.4.1: An upper limit on max-length might be a useful addition.

3.2.1: The current text says:

  ...If the value
  contains multibyte UTF-8, care must be taken to avoid splitting the
  value in mid-character: count each Unicode codepoint as one
  character.

The admonition in 1.6 seems equally useful for the values variables: Though they might exist as encoded, all contents of variables are assumed by the spec to be Unicodes, and must be appeneded by UTF-8ing them and pct-encoding as necessary. I think it's worth adding text on this.

[Ballot discuss]
The Gen-ART Review by Vijay Gurbani on 1-Jan-2012 raised two minor
  issues.  I have not seen a response to this review, but I believe
  it deserves a response.  The two issues are repeated below.

  - S3.2.1, first paragraph: "A variable defined as an associative
  array of (name, value) pairs is considered undefined if the
  array contains zero members or if all member names in the array
  have undefined values."

  Here, do you mean "if all member names in the array have no
  values."?  That is, "undefined values" implies that values are
  present in the template, but are not understood.  On the other
  hand, "no values" implies the absence of any values at all.  In my
  reading of the text, it appears that "no values" conveys more
  context than "undefined values".

  - S4, general comment: I am not sure where the template expansion is
  done --- at the client (browser) or at the origin server (the draft
  does not enunciate this, and if it does, I may have missed it).  If
  the expansion is done at the origin server, I suspect that one can
  keep it a bit more busy by asking it to perform unnecessary
  template expansion for a resource that may be accessed normally
  even without template expansion.  Is it worth documenting this at
  all in the Security Considerations section?  (Clearly, if the expansion
  is done at the client, then it is the client incurring the expense
  of expansion.  Insofar as the client is malicious, it is best to
  let it expend as much effort as necessary.)

[Ballot comment]
I have no objection to the publication of this document as a Standards
Track RFC. I have a few very minor comments you might look at.

---

You may note that you use RFC 2119 language in Section 1.1 but do not
include the explanation until Section 1.5.

---

Should you provide references for WSDL, WADL, and OpenSearch in section
1.3?

---

In section 1.5 there is a minor notational discrepency.

You have:

    ALPHA          =  %x41-5A / %x61-7A  ; A-Z / a-z
    DIGIT          =  %x30-39            ; 0-9
    HEXDIG        =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

That means that HEXDIG has a mixed mode of hex notation and quoted
letters. It might have made more sense to write...

    HEXDIG        =  DIGIT / %x41-46    ; 0-F

But I struggle to see this as in any way an important comment! Maybe
more interesting is to check that you really intended to exclude lower
case alpha from the representation of hex numbers used in pct encoding.

---

While Appendix A begins with a helpful note that the body of the
document is normative text, it doesn't actually comment on whether the
appendix is normative or not. It would be nice to make this explicit.

[Ballot comment]
- End of p12 says "If a value provided by a user" which implies that
all the usual injection attacks need to be countered in at least some
deployments. Why doesn't that need to be mentioned in the security
considerations? I don't think 3986 envisages that kind of issue. (Esp.
if templates were combined with OAuth v1 or something else that
authenticates the URL after expansion, meaning that the user at the
browser could not have produced the URL herself.)

- Can expressions be nested?, e.g. "{foo{bar}baz}" 1st sentence of 3.2
implies not, but in any case it might be worth adding a sentence
saying that nesting like that is not supported.

- Expressions can be obfuscated. That could provide a new attack
vector: expression author convinces webmaster that template is safe
when its not. Not sure if that's worth a mention or not.

- Seven operators; lists of variable with optional modifiers (esp
"explode") - that all seems to me like too much to be universally
useful and safe. Just an opinion, not a discuss.

Updated PROTO writeup from the Document Shepherd.

###

  (1.a) Who is the Document Shepherd for this document? Has the
        Document Shepherd personally reviewed this version of the
        document and, in particular, does he or she believe this
        version is ready for forwarding to the IESG for publication?

I (Murray Kucherawy) am the document shepherd.  Not only have I reviewed this
version of the document, but I implemented the mechanism it describes from
scratch based on its content.  I was not part of the document's development.
I believe it is ready for IESG evaluation.

NOTE: This is not the product of a working group.

  (1.b) Has the document had adequate review both from key WG members
        and from key non-WG members? Does the Document Shepherd have
        any concerns about the depth or breadth of the reviews that
        have been performed? 

The document was developed mainly within the W3C.  It has had a long lifetime
of being developed, then abandoned, then developed, then abandoned, then
developed again.  I am satisfied with the review it has received throughout
its lifetime.

  (1.c) Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization or XML?

I have little concern about the need for additional specific review.
I suggest, though, that if the sponsoring AD or the IESG would like further
review for the record, that someone like Larry Masinter (who is on the
apps-review team) might be a good candidate.

  (1.d) Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of? For example, perhaps he
        or she is uncomfortable with certain parts of the document, or
        has concerns whether there really is a need for it. In any
        event, if the WG has discussed those issues and has indicated
        that it still wishes to advance the document, detail those
        concerns here. Has an IPR disclosure related to this document
        been filed? If so, please include a reference to the
        disclosure and summarize the WG discussion and conclusion on
        this issue.

I have no such concerns.  Any difficulties I had implementing were only
because of my own misreading of a few minor points of the document, or
my unfamiliarity with what's allowed in a URI, and not because of any
document deficiencies.  There is a possible need for this work in the REPUTE
working group already, and also possibly in WEIRDS if/when it charters.
I have no reports of likely IPR claims.

  (1.e) How solid is the WG consensus behind this document? Does it
        represent the strong concurrence of a few individuals, with
        others being silent, or does the WG as a whole understand and
        agree with it? 

This is not the product of a working group.

  (1.f) Has anyone threatened an appeal or otherwise indicated extreme
        discontent? If so, please summarise the areas of conflict in
        separate email messages to the Responsible Area Director. (It
        should be in a separate email because this questionnaire is
        entered into the ID Tracker.)

There have been no such indications.

  (1.g) Has the Document Shepherd personally verified that the
        document satisfies all ID nits? (See the Internet-Drafts Checklist
        and http://tools.ietf.org/tools/idnits/). Boilerplate checks are
        not enough; this check needs to be thorough. Has the document
        met all formal review criteria it needs to, such as the MIB
        Doctor, media type and URI type reviews?

I have done an ID Nits verification myself.  The only complaints were
"weird spacing".  It also mentions that the lifetime of the document predates
RFC5378, but the authors are fine with the new IPR rules.

A URI Type review is the most relevant review possible, but is not needed
in this case.

  (1.h) Has the document split its references into normative and
        informative? Are there normative references to documents that
        are not ready for advancement or are otherwise in an unclear
        state? If such normative references exist, what is the
        strategy for their completion? Are there normative references
        that are downward references, as described in [RFC3967]? If
        so, list these downward references to support the Area
        Director in the Last Call procedure for them [RFC3967].

There is no split to references; they are all normative.  However, it looks
like that is appropriate for this document.  There are no downward
references other than to outside documents like the ASCII definition, which
(I believe) have no formal IETF status.

  (1.i) Has the Document Shepherd verified that the document IANA
        consideration section exists and is consistent with the body
        of the document? If the document specifies protocol
        extensions, are reservations requested in appropriate IANA
        registries? Are the IANA registries clearly identified? If
        the document creates a new registry, does it define the
        proposed initial contents of the registry and an allocation
        procedure for future registrations? Does it suggest a
        reasonable name for the new registry? See [RFC5226]. If the
        document describes an Expert Review process has Shepherd
        conferred with the Responsible Area Director so that the IESG
        can appoint the needed Expert during the IESG Evaluation?

There are no IANA actions for this document.

  (1.j) Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

The ABNF in this document has been verified.

  (1.k) The IESG approval announcement includes a Document
        Announcement Write-Up. Please provide such a Document
        Announcement Write-Up? Recent examples can be found in the
        "Action" announcements for approved documents. The approval
        announcement contains the following sections:

    Technical Summary
        Relevant content can frequently be found in the abstract
        and/or introduction of the document. If not, this may be
        an indication that there are deficiencies in the abstract
        or introduction.

A URI Template is a compact sequence of characters for describing a
range of Uniform Resource Identifiers through variable expansion.
This specification defines the URI Template syntax and the process
for expanding a URI Template into a URI reference, along with
guidelines for the use of URI Templates on the Internet.

    Working Group Summary
        Was there anything in WG process that is worth noting? For
        example, was there controversy about particular points or
        were there decisions where the consensus was particularly
        rough?

This is not the direct product of a working group, though it was discussed
originally on the uri@w3c.org mailing list which was the one used by the URI
working group (now closed).

    Document Quality
        Are there existing implementations of the protocol? Have a
        significant number of vendors indicated their plan to
        implement the specification? Are there any reviewers that
        merit special mention as having done a thorough review,
        e.g., one that resulted in important changes or a
        conclusion that the document had no substantive issues? If
        there was a MIB Doctor, Media Type or other expert review,
        what was its course (briefly)? In the case of a Media Type
        review, on what date was the request posted?

There are several implementations of this mechanism in several languages,
one of which is mine (C).  It appears in an open source product called
OpenDKIM.  Other implementations can be found at
http://code.google.com/p/uri-templates/wiki/Implementations.

###

State changed to In Last Call from Last Call Requested.

The following Last Call Announcement was sent out:

From: The IESG
To: IETF-Announce
Reply-To: ietf@ietf.org
Subject: Last Call:  (URI Template) to Proposed Standard


The IESG has received a request from an individual submitter to consider
the following document:
- 'URI Template'
  as a Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2011-12-26. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  A URI Template is a compact sequence of characters for describing a
  range of Uniform Resource Identifiers through variable expansion.
  This specification defines the URI Template syntax and the process
  for expanding a URI Template into a URI reference, along with
  guidelines for the use of URI Templates on the Internet.

Editorial Note (to be removed by RFC Editor)

  To provide feedback on this Internet-Draft, join the W3C URI mailing
  list (http://lists.w3.org/Archives/Public/uri/) [1].




The file can be obtained via
http://datatracker.ietf.org/doc/draft-gregorio-uritemplate/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-gregorio-uritemplate/


No IPR declarations have been submitted directly on this I-D.

State Change Notice email list has been changed to joe@bitworking.org, fielding@gbiv.com, Marc.Hadley@oracle.com, mnot@pobox.com, orchard@pacificspirit.com, msk@cloudmark.com, draft-gregorio-uritemplate@tools.ietf.org from joe@bitworking.org, fielding@gbiv.com, Marc.Hadley@oracle.com, mnot@pobox.com, orchard@pacificspirit.com, draft-gregorio-uritemplate@tools.ietf.org

Proto writeup from Murray Kucherawy ...

  (1.a) Who is the Document Shepherd for this document? Has the
        Document Shepherd personally reviewed this version of the
        document and, in particular, does he or she believe this
        version is ready for forwarding to the IESG for publication?

I (Murray Kucherawy) am the document shepherd.  Not only have I reviewed this
version of the document, but I implemented the mechanism it describes from
scratch based on its content.  I was not part of the document's development.
I believe it is ready for IESG evaluation.

NOTE: This is not the product of a working group.

  (1.b) Has the document had adequate review both from key WG members
        and from key non-WG members? Does the Document Shepherd have
        any concerns about the depth or breadth of the reviews that
        have been performed? 

The document was developed mainly within the W3C.  It has had a long lifetime
of being developed, then abandoned, then developed, then abandoned, then
developed again.  I am satisfied with the review it has received throughout
its lifetime.

  (1.c) Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization or XML?

I have little concern about the need for additional specific review.
I suggest, though, that if the sponsoring AD or the IESG would like further
review for the record, that someone like Larry Masinter (who is on the
apps-review team) might be a good candidate.

  (1.d) Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of? For example, perhaps he
        or she is uncomfortable with certain parts of the document, or
        has concerns whether there really is a need for it. In any
        event, if the WG has discussed those issues and has indicated
        that it still wishes to advance the document, detail those
        concerns here. Has an IPR disclosure related to this document
        been filed? If so, please include a reference to the
        disclosure and summarize the WG discussion and conclusion on
        this issue.

I have no such concerns.  Any difficulties I had implementing were only
because of my own misreading of a few minor points of the document, or
my unfamiliarity with what's allowed in a URI, and not because of any
document deficiencies.  There is a possible need for this work in the REPUTE
working group already, and also possibly in WEIRDS if/when it charters.
I have no reports of likely IPR claims.

  (1.e) How solid is the WG consensus behind this document? Does it
        represent the strong concurrence of a few individuals, with
        others being silent, or does the WG as a whole understand and
        agree with it? 

This is not the product of a working group.

  (1.f) Has anyone threatened an appeal or otherwise indicated extreme
        discontent? If so, please summarise the areas of conflict in
        separate email messages to the Responsible Area Director. (It
        should be in a separate email because this questionnaire is
        entered into the ID Tracker.)

There have been no such indications.

  (1.g) Has the Document Shepherd personally verified that the
        document satisfies all ID nits? (See the Internet-Drafts Checklist
        and http://tools.ietf.org/tools/idnits/). Boilerplate checks are
        not enough; this check needs to be thorough. Has the document
        met all formal review criteria it needs to, such as the MIB
        Doctor, media type and URI type reviews?

I have done an ID Nits verification myself.  The only complaints were
"weird spacing".  It also mentions that the lifetime of the document predates
RFC5378, but the authors are fine with the new IPR rules.

A URI Type review is the most relevant review possible, but is not needed
in this case.

  (1.h) Has the document split its references into normative and
        informative? Are there normative references to documents that
        are not ready for advancement or are otherwise in an unclear
        state? If such normative references exist, what is the
        strategy for their completion? Are there normative references
        that are downward references, as described in [RFC3967]? If
        so, list these downward references to support the Area
        Director in the Last Call procedure for them [RFC3967].

There is no split to references; they are all normative.  However, it looks
like that is appropriate for this document.  There are no downward
references other than to outside documents like the ASCII definition, which
(I believe) have no formal IETF status.

  (1.i) Has the Document Shepherd verified that the document IANA
        consideration section exists and is consistent with the body
        of the document? If the document specifies protocol
        extensions, are reservations requested in appropriate IANA
        registries? Are the IANA registries clearly identified? If
        the document creates a new registry, does it define the
        proposed initial contents of the registry and an allocation
        procedure for future registrations? Does it suggest a
        reasonable name for the new registry? See [RFC5226]. If the
        document describes an Expert Review process has Shepherd
        conferred with the Responsible Area Director so that the IESG
        can appoint the needed Expert during the IESG Evaluation?

There are no IANA actions for this document.

  (1.j) Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

The ABNF in this document has been verified.

  (1.k) The IESG approval announcement includes a Document
        Announcement Write-Up. Please provide such a Document
        Announcement Write-Up? Recent examples can be found in the
        "Action" announcements for approved documents. The approval
        announcement contains the following sections:

    Technical Summary
        Relevant content can frequently be found in the abstract
        and/or introduction of the document. If not, this may be
        an indication that there are deficiencies in the abstract
        or introduction.

A URI Template is a compact sequence of characters for describing a
range of Uniform Resource Identifiers through variable expansion.
This specification defines the URI Template syntax and the process
for expanding a URI Template into a URI reference, along with
guidelines for the use of URI Templates on the Internet.

    Working Group Summary
        Was there anything in WG process that is worth noting? For
        example, was there controversy about particular points or
        were there decisions where the consensus was particularly
        rough?

This is not the product of a working group.  It is the output of an
individual submission from people that participate in both the IETF and W3C.

    Document Quality
        Are there existing implementations of the protocol? Have a
        significant number of vendors indicated their plan to
        implement the specification? Are there any reviewers that
        merit special mention as having done a thorough review,
        e.g., one that resulted in important changes or a
        conclusion that the document had no substantive issues? If
        there was a MIB Doctor, Media Type or other expert review,
        what was its course (briefly)? In the case of a Media Type
        review, on what date was the request posted?

There are several implementations of this mechanism in several languages,
one of which is mine (C).  It appears in an open source product called
OpenDKIM.  Other implementations can be found at
http://code.google.com/p/uri-templates/wiki/Implementations.