URI template: substring for dates

[James Manger]

[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

[Roy T. Fielding]

On Nov 2, 2009, at 4:40 AM, James Manger wrote:

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

Well, not really.  It is fairly common for URI layouts to incorporate
some portion of a date value, such as the year and/or month of  
publication.
Those are simple variable substitutions like:

    /post/{year}{month}/{title}

I have never seen a resource layout incorporate the current time.

In other words, there is no need for the template syntax to be aware
of date fields because (in this case) it is simpler for the variable
values to be limited as such.  String prefix/suffix makes sense because
they are ignorant of variable semantics no matter what the values
might be.  Using substrings to extract fields from a date value
means that we know it is a date value, and thus we can use a more
specific value definition like {seconds} without changing the syntax.

Thanks for the detailed proposal.  I think it would make sense if
we were trying to act like a programming language in the template,
but we are really trying hard to avoid that.

....Roy

[Gannon Dick]

Continuous variables (time, but also space) are probably unsuitable for URI Templates for the reasons mentioned by Mr. Fielding.

The last identifying term does not identify a point in time, but rather a sly duration.  To identify geographic regions by the barycentric coordinate (e.g. the latitude and longitude of City Hall) has the same problem.  I figured out a fix for the geography problem <http://www.rustprivacy.org/primeencoding.zip>, but the time problem will be forever intractable - the left-most term will have to be truncated in order to sort.

The "hash mark" separates the digital from the analog ...

/World/France/Paris (Region)/Paris#AndEverythingThere
/World/UnitedStates/Texas/Paris/MainStreet#AndEverythingThere

Just my 2 cents ...

--Gannon

--- On Mon, 11/2/09, Roy T. Fielding <fielding@...> wrote:

> From: Roy T. Fielding <fielding@...>
> Subject: Re: URI template: substring for dates
> To: "James Manger" <James@...>
> Cc: uri@...
> Date: Monday, November 2, 2009, 1:01 PM
> On Nov 2, 2009, at 4:40 AM, James
> Manger wrote:
>
> > [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.
>
> Well, not really.  It is fairly common for URI layouts
> to incorporate
> some portion of a date value, such as the year and/or month
> of publication.
> Those are simple variable substitutions like:
>
>    /post/{year}{month}/{title}
>
> I have never seen a resource layout incorporate the current
> time.
>
> In other words, there is no need for the template syntax to
> be aware
> of date fields because (in this case) it is simpler for the
> variable
> values to be limited as such.  String prefix/suffix
> makes sense because
> they are ignorant of variable semantics no matter what the
> values
> might be.  Using substrings to extract fields from a
> date value
> means that we know it is a date value, and thus we can use
> a more
> specific value definition like {seconds} without changing
> the syntax.
>
> Thanks for the detailed proposal.  I think it would
> make sense if
> we were trying to act like a programming language in the
> template,
> but we are really trying hard to avoid that.
>
> ....Roy
>
>
>

[James Manger]

I agree that dates are much more common in URIs than times. Defining 3  
variables for each date field is not as bad as half-a-dozen, but it is  
still annoying: some specs will define pubYear, pubMonth, pubDay;  
others will define pub=yyyy-mm-dd. HTML5, for instance, might make it  
convenient to get a date into a single variable (eg <input  
type="date">), but a prefix/suffix template syntax will not be able to  
pick out the month.

I don't think you can say a prefix/suffix is qualitatively different  
than a substring in being ignorant of variable semantics. The prefix/
suffix syntax can indicate a beginning or ending point from either end  
of a value. The substring syntax just lets you indicate both. In all  
cases a value can be too small for the offsets so you get less than  
expected, or an empty string.

{var:end} and {var^begin} vs {var[begin,end]}

It is a minor difference; offering a little more functionality &  
flexibility; with a slightly more familiar syntax.

P.S. The syntax could be {var:begin,end} to support substring  
functionality while looking slightly less like a programming language.

P.S. Is there any reason to assume hash-based storage will only ever  
use 2 layers? Why not 3?
/{hash[,4]}/{hash[4,8]/{hash[8,]}

James Manger