RE: draft-gregorio-uritemplate-02.txt

Suggested changes to draft-gregorio-uritemplate-02.txt

§3, 1st sentence: Allow a template to have no expansions (ie just be a URI).
< “contains one or more embedded template expansions”
> “contains any number of embedded template expansions”

§3.1: Values of variables should not be restricted. They should just be escaped when building the URI. The simplest model is to say each variable value is a list of (Unicode) strings. An empty list is treated as if the variable was undefined.
I don't think it is worth supporting percent-encoded binary blobs. It makes code awkward as callers need to encode values before passing them to the template processor. The sentence about percent-encoding everything outside ( unreserved / pct-encoded ) is ambiguous. You cannot tell if a percent sign is part of a pct-encoding or is actually meant to be a %.
“every octet of the UTF-8 string that falls outside of ( unreserved / pct-encoded ) MUST be percent-encoded”

§3.2: I would put the 'expansion' rule at the top, not the bottom. I think it is more natural to read from the high-level to the details (but this is a very minor stylistic preference).

§3.3.6: Move the last paragraph (“the result of substitution MUST match…”) to §3.3 (before §3.3.1) as it applies to all the rules, not just 'listjoin'.

§3.4: foo is used as a variable value so don’t reuse it as an undefined variable name. It has unnecessary potential to confuse the reader.

§3.4: A zero-length string should be a legitimate value. It should not be treated as undefined. It is not necessary to make a zero-length string a special case. Perhaps a user interface might translate an empty text input box into an undefined variable, instead of a zero-length string, but the URI template processor API should not force that arrangement.
Consider a variable value that is a list of strings, one of which has zero-length… the whole variable cannot be treated as undefined.
< ./{-prefix|#|str0}  ->  ./
> ./{-prefix|#|str0}  ->  ./#

§3.4: Using a variable that is a list of strings in a template that expects a single string is undefined. The first 'join' example inserts (escaped) commas - but there is no explanation of where they came from. I suggest the default rule should be to concatenate the strings in the list with NO separator. If multiple values are allowed the template author should explicitly indicate that by providing the separator.
< /?{-join|&|a,data}  ->  /?a=foo&data=10%2C20%2C30
> /?{-join|&|a,data}  ->  /?a=foo&data=102030

§3.4: …&{-join|&|foo} -> …& produces a poor URI. It has an unwanted & at the end. This points to a limitation of the syntax.


I still prefer my { prefix ^ var * separator ^ suffix | default } syntax, with shortcuts. The examples from the document are rewritten in this syntax below (after the original). Only #8 cannot be expressed, but I don't think that is a problem as it is a very contrived example. I think mine are more readable, particularly for query parameters.

More importantly, we need easy support for query parameters where the query name does not match the variable name. We need easy support for the leading '?' or '&'.
In my syntax:
0  /find{?q=searchTerm}{&p=page}{&lang=}
I think it is pretty obvious (even if you don't know my syntax) to recognise the URIs this template can produce.
I am not sure that this simple case is even possible with the current draft. An approximation is:
0a /find?q={searchTerm}{-prefix|&p=|page}{-join|&|lang}
'join' is succinct for long lists of query parameter, but only when query name matches variable name, and it does not help with the leading '?' or '&'.


1  http://example.org/?q={a}

   same

2  http://example.org/{foo}

   same

3  relative/{reserved}/
   same

4  http://example.org/{foo=fred}

   http://example.org/{foo|fred}


5  http://example.org/{foo=%25}/

   http://example.org/{foo|%25}/


6  /{-prefix|#|foo}
   /{#foo}

7  ./{-prefix|#|str0}
   ./{#str0}

8  /{-append|/|a}{-opt|data|points}{-neg|@|a}{-prefix|#|b}
   /{a/}data{#b}
   does not support opt & neg when not adjacent to use of the variable's value

9  http://example.org/q={u}

   same

10 http://example.org/?{-join|&|a,data}

   http://example.org/{?a=}{&data=}


11 http://example.org/?d={-listjoin|,|points}&{-join|&|a,b}

   http://example.org/?d={points*,}{&a=}{&b=}


12 http://example.org/?d={-listjoin|,|list0}&{-join|&|foo}

   http://example.org/?d={list0*,}{&foo=}

   does not produce unwanted ampersand on end when foo undefined

13 http://example.org/?d={-listjoin|&d=|points}

   http://example.org/{?d=*}

   http://example.org/{?d=^d*&d=}    if you don’t like the shortcuts

14 http://example.org/{a}{b}/{a_b}

   same

15 http://example.org/{a}{-prefix|/-/|a}/

   http://example.org/{a}{/-/a}



James Manger

----------
From: uri-request@w3.org [mailto:uri-request@w3.org] On Behalf Of Joe Gregorio
Sent: Monday, 26 November 2007 11:50 PM
To: URI
Subject: draft-gregorio-uritemplate-02.txt

http://bitworking.org/projects/URI-Templates/

Received on Tuesday, 27 November 2007 02:26:31 UTC