W3C home > Mailing lists > Public > uri@w3.org > November 2009

URI template: substring for dates

From: James Manger <James@Manger.com.au>
Date: Mon, 2 Nov 2009 23:40:19 +1100
Message-Id: <D5DCF011-639D-4D27-84AF-5509C0981638@Manger.com.au>
To: uri@w3.org
[Comments on the URI Template working draft]

Constructing a URI with a substring of a user-provided variable value  
sounds useful. The current working draft has a dictionary site as an  
example (/dictionary/{term:1}/{term} produces /dictionary/c/cat), and  
mentions hash-based storage.

Another important example is dates. Many, many URI designs incorporate  
dates, in quite a variety of ways (just year, year/month/day, XML- 
style timestamp...) -- which sounds like a perfect situation to use a  
URI template.

Ideally, a spec could define one variable to hold a date (eg  
'published=2009-11-02T11:01:00Z'), then different sites can each have  
their own template to pick out the parts they need in the arrangement  
they want. The alternative is specs having to define, say, half-a- 
dozen variables to hold each component of each date, which is much  
less appealing (eg 'publishedYear=2009', 'publishedMonth=11',  
'publishedDay=02', 'publishedHour=11', 'publishedMinute=01'...).

Picking a 2-digit month, for instance, from a date string to use as a  
path segment (quite a common occurrence in URIs) requires a substring  
function with start and end offsets, not just a prefix or suffix as  
the current syntax supports ({var:end} or {var^begin} respectively).

I suggest a slightly more flexible syntax:
   {var[begin,end]}

A template for W3 standards might be:
   /TR/{date[,4]}/REC-{title}-{date[,4]}{date[6,8]}{date[9,11]}
producing /TR/1998/REC-CSS2-19980512 when title is "CSS2" and date is  
"1998-05-12T00:00:00Z".


Both begin and end can take negative values to indicate offsets from  
the end of the value, instead of from the beginning (like the current  
draft).

Both begin and end can be optional, defaulting to the beginning and  
ending of the variable value respectively.

My gut feeling is that [begin,end] would be fairly easier for template  
authors to understand and remember.

I would be tempted to RECOMMEND that variables that are dates use the  
XML date format (yyyy-mm-ddThh:mm:ssZ) were possible, but perhaps it  
would be sufficient to include an example using this format.



Suggested replacement text:

1. Introduction
....
   http://example.com/dictionary/{term[,1]}/{term}

2.4 Value Modifiers
A variable can have a modifier indicating that the substituted value  
is limited to a substring of the variable value. The primary use of  
these modifiers is to partition an identifier space hierarchically, as  
is often found in reference sites, date-based URIs and hash-based  
storage. They can also be used to indicate the maximum length of a  
given substitution.

   modifier      =  "[" [begin] "," [end] "]"
   begin         =  offset
   end           =  offset
   offset        =  [ "-" ] 1*DIGIT

If the variable is not typed, then each offset refers to a number of  
characters from either the beginning (0 or positive offset) or end  
(negative offset) of the variable's value (before any %-escaping). If  
the begin offset is omitted, the substring starts at the beginning of  
the value. If the end offset is omitted, the substring stops at the  
end of the value ("-0" SHALL NOT be used). The comma is never omitted.  
If the begin or end offset is beyond the variable's value (ie the  
absolute value of the offset is larger than the length of the  
variable's value) then the nearest end of the value is used. If the  
end offset is earlier in the string than the begin offset, an empty  
string is substituted.

If the variable is typed as a list, a modifier creates a sub-list.  
That is, the offsets refer to list elements, not characters.

If the variable is typed as an associative array, the offsets refer to  
tuples.

The following examples illustrate how modifiers work with the  
different variable types. More complex examples are provided in  
Section 5.

   Given the variable assignments:
     date  := "2009-10-31T22:55:13Z";
     name  := [ "Fred", "Wilma", "Pebbles" ];
     favs  := [ "color", "red", "volume", "high" ];

   Example Template     Expansion

     {date}             2009-10-31T22:55:13Z
     {date[,50]}        2009-10-31T22:55:13Z
     {date[,4]}         2009
     {date[11,]}        22:55:13Z
     {date[-1,]}        Z
     {date[6,8]}        10
     x{date[15,-15]}y   xy

     {?name}            ?name=Fred,Wilma,Pebbles
     {?name[,1]}        ?name=F
     {?@name}           ?name=Fred&name=Wilma&name=Pebbles
     {?@name[,1]}       ?name=Fred
     {?@name[1,]}       ?name=Wilma&name=Pebbles

     {?favs}            ?favs=color,red,volume,high
     {?%favs}           ?color=red&volume=high
     {?%favs[,1]}       ?color=red
     {?%favs[1,]}       ?volume=high
     {?%favs[-1,]}      ?volume=high
     {?%favs[,-1]}      ?color=red


James Manger
Received on Monday, 2 November 2009 16:33:54 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:25:13 UTC