Joe Gregorio | 4 Apr 22:18 2008

draft-gregorio-uritemplate-03.txt


Draft 03 of the uri template spec has been published:

   http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt

HTML and diffs are available here along with an updated
template explainer service:

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

I've folded in much of the feedback from the last draft.

Here are the revision history notes:

   Added more examples.  Introduced error conditions and defined
   their handling.  Changed listjoin to list.  Changed -append to
   -suffix, and allowed -prefix and -suffix to accept list variables.
   Clarified the handling of unicode.

   Thanks,
   -joe

--

-- 
Joe Gregorio http://bitworking.org

John Cowan | 5 Apr 07:30 2008

Re: draft-gregorio-uritemplate-03.txt


Editorial comments:

1.2: change the comma after "argument to an operator" to a semicolon

1.2: s/i.e/i.e./

1.3: add new second sentence like "In particular, it is not possible,
given a URI Template and a URI generated from it, to uniquely reconstruct
the values of the variables used."

4.1: s/comde/come/

4.3: s/language specific/language-specific/

4.4: s/set of variables/mapping from a set of variables to their values/

4.4: s/represenation/representation/

4.4: s/be percent encoded means/be percent-encoded means/

4.4: change comma after "by this specification" to a semicolon

4.4.1 et seqq: use "=" (equality) instead of ":=" (assignment)

4.4.4: s/only have one variable/have exactly one variable/

4.4.4: s/preceeded/preceded/ (twice)

4.4.7: s/listjoin/join/
(Continue reading)

John Cowan | 5 Apr 07:40 2008

Re: draft-gregorio-uritemplate-03.txt


Substantive points:

1) Why use NKFC, or any normalization at all?  That makes it impossible
to generate the URI equivalents of perfectly legal IRIs that happen to
contain characters that disappear under normalization.  If the values
of the variables are identical, codepoint by codepoint, the results
of the URI Template processor will be identical -- and that's all you
really need.

2) Why is an empty list variable treated the same as an undefined variable
by the -opt and -neg operators?

3) Why require the values of variables in -join to be non-empty?
That contradicts the first example in any case.  I think it makes more
sense to allow them to be empty and Just Work.

4) The -list operator corresponds more closely to join methods in Java,
Perl, and Python, and IMHO should be named -join, leaving something like
-map or -vars for the current -join operator.

--

-- 
We pledge allegiance to the penguin             John Cowan
and to the intellectual property regime         cowan <at> ccil.org
for which he stands, one world under            http://www.ccil.org/~cowan
Linux, with free music and open source
software for all.               --Julian Dibbell on Brazil, edited

Sebastian Pipping | 6 Apr 19:28 2008

uriparser 0.7.0 released


This release is a feature release, mainly adding dissection
and composition of query strings. Previously query strings
were block of text and nothing more. Now you can use them as
key/value pairs, as application/x-www-form-urlencoded data.
Please see the API documentation and change log for details.
This release is both source- and binary-compatible.

Download:
http://sourceforge.net/project/showfiles.php?group_id=182840

Changelog:
http://sourceforge.net/project/shownotes.php?release_id=589767&group_id=182840

API documentation:
http://uriparser.sourceforge.net/doc/html/

Sebastian

Wilfred Springer | 6 Apr 21:13 2008
Picon

Re: URI Templates and Acceptable Values

Hi Ben,

(Even though I have been subscribed to this list for ages, I haven't kept track of all of the discussions, so I can't help you directly.)

I also started to wonder about this today. The grammar suggests that you can do something like this with all operators:

{operator|arg|var=val,var=val,var=val}

... with val being the default value. Now the spec doesn't include any examples doing this. I started to wonder what it would be like for the list operator:

{-list|&|nodes=...}

The spec is inconclusive on how the default value should be represented. But since the list operator only accepts list type of variables, it must be a value.

I would say, we should either drop default values from the variable section of the expansion expression, or introduce a way to represent list values.

Wilfred Springer

2008/3/10, Ben Ramsey <benramsey.lists <at> gmail.com>:

I've combed through the list and can't find whether this has been previously discussed, so forgive me if I'm repeating something.

I know that you can use a URI template to define a default value for a parameter (i.e. {foo=bar}), but has anyone discussed the use of a list of acceptable values for a parameter?

Perhaps something like:

{foo=[bar,baz,qux]}

In this case, the only acceptable values for foo are bar, baz, and qux. Implementors would determine how to handle unacceptable values.

If this has been discussed and decided against, what was the reasoning for rejecting this idea?

--
Ben Ramsey
http://benramsey.com/



Joe Gregorio | 6 Apr 21:30 2008

Re: URI Templates and Acceptable Values


On Sun, Apr 6, 2008 at 3:13 PM, Wilfred Springer
<wilfredspringer <at> gmail.com> wrote:
> Hi Ben,
>
> (Even though I have been subscribed to this list for ages, I haven't kept
> track of all of the discussions, so I can't help you directly.)
>
> I also started to wonder about this today. The grammar suggests that you can
> do something like this with all operators:
>
> {operator|arg|var=val,var=val,var=val}
>
> ... with val being the default value. Now the spec doesn't include any
> examples doing this.

>From section 4.4.1:

"""
 Example:

   foo := "fred"

   "{foo}"        -> "fred"
   "{bar=wilma}"  -> "wilma"
   "{baz}"        -> ""
"""

I should probably add some more to Section 4.5.

>  I started to wonder what it would be like for the list
> operator:
>
> {-list|&|nodes=...}
>
> The spec is inconclusive on how the default value should be represented. But
> since the list operator only accepts list type of variables, it must be a
> value.

>From Section 4.1:

"""
   Some variables may be supplied with default values.  The default
   value must come from ( unreserved / pct-encoded ).  Note that there
   is no notation for supplying default values to list variables.
"""

   -joe

--

-- 
Joe Gregorio http://bitworking.org

Manger, James H | 9 Apr 03:57 2008

RE: draft-gregorio-uritemplate-03.txt

Comments on draft-gregorio-uritemplate-03.txt:

1. §4.5, 5th example
 http://example.org/?d={list|&d=|qux}

 http://example.org/?d=10&d=20&d=30

This example covers a common templating scenario: a query parameter that can repeat any number of times.
However, it does not work well. When the variable value is undefined (or an empty list) you get
 http://example.org/?d=

but probably want
 http://example.org/

'...?d=' is likely to be interpreted as [ "" ] instead of an undefined variable.
Another flaw is that the query name 'd' is repeated in the template -- once outside the expansion and once inside.
The first flaw could be solved with '{-opt|?d=|qux}', but then both the query name 'd' and variable name
'qux' have to occur twice -- for a really simple common scenario. Repeating a name seems minor in this
example (just a few extra characters), but once there are multiple parameters and longer names it is a
recipe for unnecessary errors.

2.
"." and ".." values can have special meaning in a URI, acting much like reserved characters. Template
expansion prevents variable values introducing the latter, but not the former.

3. Examples
The variable 'foo' has the value 'fred' in most examples, but in §4.5:
* 'foo' has a different value;
* a different variable ('bar') gets the value 'fred'; and
* 'fred' is also used as a variable name!
Argh. This just confuses the reader.
One set of variable names and values that all the examples use would be nicer. Choosing variable names that
hint at their values (eg 'primes', instead of 'qux' for a list) would help. For instance:

userid  = [ "fred" ]
primes  = [ "2", "3", "5" ]
amount  = [ "2,300.50" ]
zero    = [ "" ]
emp     = [ ]
res     = [ "Ben & Jerry's a/b/c" ]
i18ns   = [ "\u017F\u0307", "\u03d3" ]
1-a_b.c = [ "200" ]
un is undefined

4.
§4.4.1 ('var') substitution does not say what to do if the value is a list. I suggest concatenation the
values with no separator. Example: "{primes}" -> "235".

5.
Perhaps the most common scenario will be a URI template with lots of optional query parameters: some param
names matching the variable names, others not; some params that can be repeated, most occurring at most
once. It should be straight forward to write such a template, but I don't think it is with this syntax.
http://example.org/stuff?{join|&|userid,amount}{-prefix|&n=|primes}{-prefix|&org=|res}

The template author has to accept:
* A trailing '?' when no optional params are present
   "http://example.org/stuff?"
* An unusual '?&' pair when the single-valued same-name params are absent
   "http://example.org/stuff?&n=2&n=3&n=5"

6.
Another common scenario will be a single optional query parameter. For instance, getting data in XML
(default) or JSON (?fmt=json) format.
  http://example.org/data

  http://example.org/data?fmt=json

A template author could support this with one expansion:
  http://example.org/data{-prefix|?fmt=|fmt}

This can produce ".../data" and ".../data?fmt=json" as desired.
However, it can also produce
  http://example.org/data?fmt=json?fmt=123?fmt=abc

when a variable value of [ "json", "123", "abc" ] is supplied.
This is unlikely to be what the server was expecting. It introduces reserved characters '?' and '=' in a
place that was probably not anticipated (a query param value). It also requires the 'fmt' name to be
included twice.
A better template would be:
  http://example.org/data{-opt|?fmt=|fmt}{fmt}

This works, but now the author needed 2 expansions and to include the 'fmt' name 3 times.
6b.
The pattern of an optional single item that needs a prefix or suffix when present will be common. The prefix
and suffix operators will seem like the right solution to many authors. They are the simplest solution (1
expansion) that works with "good" data (variable values that are undefined or a single string). But this
simplest solution is insecure as by using a "bad" value (a list of 2 or more strings) the prefix or suffix
(often containing reserved chars) is repeated. This undermines the design criteria of the author
controlling where reserved chars go.
The author could be more careful, but the spec should be able to make the careful choice the simplest.

7.
The sample parsing code in §7 does not appear to preserve the order of the variables. However, the order
"MUST be preserved" for the 'join' operator (§4.4.6). I don't know Python well. Is there any easy way to
return the variables (& their defaults) and a list (or two lists: names & defaults), instead of as a dictionary/map/associative-array?

8.
The rule to reject the whole template when an unrecognized operator is present (§4.4) will make it hard to
introduce new operators. There is no version negotiation as a URI template is a simple data syntax, not a protocol.
I think it would work better if an unknown operator was treated like an undefined variable, and replaced
with the default value (or an empty string). This does not work with the current syntax, but it could work
with other schemes.

9.
Every operator that supports lists, explicitly treats a variable that is undefined or an empty list
identically. I agree with this. §4.1 says the opposite: "A list variable that contains no members ...
MUST NOT be considered undefined". I suggest changing this sentence.

10.
How about a 'query' operator, instead of 'join'.
  data?{-join|&|userid,amount}
becomes
  data{-query||userid,amount}
where the template processor can take care of choosing a '?' or '&' as a prefix (simply depending on whether
or not a '?' already appear in the URI being constructed). Perhaps '?' would be a better operator name than 'query'.
We could allow values to be lists.
  {-query||primes,userid} -> "?primes=2&primes=3&primes=5&userid=fred"
The arg could be used as the query param name (instead of reusing the variable name) when it isn't the empty string.
  {-query|n|primes} -> "?n=2&n=3&n=5"
A non-empty arg with more than one variable would be unusual but still obvious.
  {-query|x|userid,amount} -> "?x=fred&x=2%2C300.50"
  {-query|u|userid}{-query|a|amount} -> "?u=fred&a=2%2C300.50"


OVERALL
A lot of common scenarios are awkward to support cleanly with the current syntax.
A lot of simple scenarios require multiple expansions and repeated names, which make the syntax ungainly.
This should not be necessary.

A syntax with hardwired support for a prefix, suffix, separator, default and variable name can be much
cleaner - particularly for template authors. It would not have named operators so one avenue of
extensibility is cut off, but this is not crucial. There is plenty of room for extensibility in the
variable names.

TYPOS
§1.3  s/nor should not be/nor should they be/
§4.1  s/must comde from/must come from/
§4.4.7  s/listjoin/list/

----------
From: uri-request <at> w3.org [mailto:uri-request <at> w3.org] On Behalf Of Joe Gregorio
Sent: Saturday, 5 April 2008 7:19 AM


Draft 03 of the uri template spec has been published:

   http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt


Frank Ellermann | 10 Apr 07:47 2008
Picon
Picon

For review: the historical "videotex" URI scheme


URI scheme name:
   videotex
Status:
   historical
URI scheme syntax:
   "videotex://" login [ "/" videotexservice *[ parameter ] ]
   For details see the historical reference, a <login> was in
   essence what STD 66 specifies as <authority>.
URI scheme semantics:
   For details see the historical reference, the default port
   assigned by IANA is 516.  For a rough idea "videotex" was
   an URI scheme in the direction of "tn3270" and "telnet".
   The "vemmi" URL scheme specified in RFC 2122 for port 575
   was apparently designed to obsolete "videotex" URLs.
Encoding considerations:
   The historical reference does not go into details.  Picking
   an $EMULATION included values CEPT1 (BTX), CEPT2 (Teletel
   latin mode), CEPT2GREEK (Teletel greek mode), CEPT2ARABIC,
   CEPT3 (Prestel), CEPT4, NAPLPS, CAPTAIN, VT52, VT100, VT220,
   and a way for servers to determine the capabilities of the
   client.
Applications/protocols that use this URI scheme name.
   Various Videotex services existed, among them Prestel, Minitel,
   BTX.  In the time of the transition to the WWW client software
   needed to support legacy Videotex services of the corresponding
   providers.
Interoperability considerations:
   HTTP and the WWW were soon more popular than all predecessors
   not limited to Videotex.  
Security considerations:
   See STD 66 for a discussion of the "user:password <at> " construct
   in an <authority>.
Contact:
   <URL:mailto:uri <at> w3.org> (URI mailing list)
Author/Change controller:
   The historical reference mentions an ETSI TE1 WG, the authors
   later published RFC 2122 on standards track, change control by
   the IETF is good enough for this historical scheme. 
References:
   draft-mavrakis-videotex-url-spec (1996),
   <URL:http://esw.w3.org/topic/UriSchemes/videotex>,
   RFC 2122 (vemmi URL scheme), RFC 3986 (STD 66).

Nicolas Krebs | 17 Apr 00:16 2008

new Media Fragments Working Group at W3C


via 
http://www.w3.org/QA/2008/04/proposed_activity_for_video_on.html
and http://www.w3.org/2008/01/media-fragments-wg.html

http://www.w3.org/2008/01/media-fragments-wg.html 
"The mission of the Media Fragments Working Group, part of the Video 
on the Web Activity, is to address temporal and spatial media 
fragments on the Web using Uniform Resource Identifiers (URI)."

Look like RFC 5147 
urn:ietf:rfc:5147
http://www.ietf.org/rfc/rfc5147.txt
An other way of point and link to part of a web ressource via uri fragment
(i love this). 

See also 
http://www.w3.org/DesignIssues/Fragment.html
http://dret.typepad.com/dretblog/2007/11/fragment-identi.html
http://dret.net/netdret/docs/wilde-ht2005-textfrag.pdf
http://www.bortzmeyer.org/5147.html

Comment: 
I don't see the uri mailing list http://lists.w3.org/Archives/Public/uri/ 
or "URI Activity" http://www.w3.org/Addressing/Activity 
or the "URI Interest Group" http://www.w3.org/2001/12/URI/ 
in the "Dependencies" section. Is this included in or infered by 
"Internet Engineering Task Force (IETF) [...] 
This organisation is responsible for RFC 3986 (URI)" ? 

Philippe Le Hegaret | 17 Apr 22:21 2008
Picon

Re: new Media Fragments Working Group at W3C


On Thu, 2008-04-17 at 00:16 +0200, Nicolas Krebs wrote:
> I don't see the uri mailing list http://lists.w3.org/Archives/Public/uri/ 
> or "URI Activity" http://www.w3.org/Addressing/Activity 
> or the "URI Interest Group" http://www.w3.org/2001/12/URI/ 
> in the "Dependencies" section. Is this included in or infered by 
> "Internet Engineering Task Force (IETF) [...] 
> This organisation is responsible for RFC 3986 (URI)" ? 

We closed the URI activity and URI Interest Group last year...
[[
  This Activity has now closed. This page will not be updated any
further.
]]
http://www.w3.org/Addressing/Activity.html

But it still makes sense to keep this mailing list in the loop, so I'll
add something for that effect. The TAG is also supposed to cover URI as
well btw.

Philippe


Gmane