URI Templates: done or dead?

There hasn't been a lot of discussion or activity on URI Templates  
recently, which either means it's very stable, or very nearly dead.

If it's very stable, we should ship it and be done with it. If it's  
nearly dead (and I do get a whiff of that; while I continuously hear  
people clamouring for it to be finished, not many seem to be willing  
to use it in its current state; YMMV), we should at least try to  
revive it.

My continuing concerns with the -03 draft are that it's too complex,  
not human-friendly, and it makes the common, simple use cases hard.  
The first example in the spec ( http://www.example.com/users/ 
{userid} ) holds up well, but it goes quickly downhill from there; ( http://www.example.com/? 
{-join|&|query,number} ) looks like line noise, IMHO.

I believe there are a few things we can do to make URI Template more  
broadly useful and useable, without sacrificing too much functionality  
(at least in the 80% case).

1. Reduce or drop operators.

As mentioned above, they don't read well; they're obviously intended  
for machines, not people. The expansion for a template should be  
blindingly obvious, but the operator syntax seems to want to get in  
the way rather than help. Furthermore, the vast majority of use cases  
for templates are for simple template substitution, not operations  
like 'neg' and 'opt'.

2. Drop list values.

Again, the majority of use cases out there have no need for list  
values in template variables, and including them in the spec  
significantly complicates things.

3. Make percent-encoding context-sensitive.

There are just too many cases where the 'escape everything but  
unreserved' rule gets in the way; for example, if my template is "http://example.com/user/ 
{email}", I'm going to have percent-encoded @ signs in my URIs whether  
I like it or not -- even though they're not required to be percent- 
encoded there. This is a relatively simple thing to do, as long as we  
also...

4. Allow exceptions to percent-encoding.

We need a syntax that allows characters to be excepted from encoding,  
even in context. As a straw-man, I suggest preceding the expression  
with the characters that are excepted, like:

    http://example.com/{/path}
    http://example.com/thing{?&=query_args}

and so forth.

5. If we keep operators at all, mint special ones for the common cases.

E.g., something to handle encoded form query values "out of the box":
   http://example.com/thing{-?a=foo&b=bar&c=baz}
and likewise with matrix parameters.


Let's see if that shakes things up...


--
Mark Nottingham     http://www.mnot.net/

Received on Monday, 15 September 2008 12:17:00 UTC