RE: URI Templates: done or dead?

Mark:

Great email, thanks for stirring things up.

On this issue I had a great conversation with Roy Fielding at the most
recent ApacheCon in Atlanta. He was gracious enough to spend almost an hour
with me. He had the following to say, which I will do my best to paraphrase
based on my memory though chances are I will get part of it wrong. I've cc'd
Roy in hopes he will correct anything that I accidentally misrepresent:

	Basically Roy said that his view of URI Templates 
	was that it needed to be written to support 
	machines, not humans. He said that a human readable 
	*representation* was possible to be generated from 
	a machine-readable URI Template, but from his 
	perspective if it wasn't written to support machines 
	he would not use it nor support it.

Roy gave me his comments in response to my fervent advocacy for URI
Templates to be optimized for humans. Mark it sounds like you have a similar
position to mine which is there is a strong needs for a very human friendly
URI Template specification. I envision many uses for URI Templates in
Content Management Systems and Application Frameworks but I think Roy
envisions using them in Apache, routers, proxies, etc. Unfortunately, I
don't think any URI template specification will come to a resolution as long
as there are those competing and evidently non-compatible objectives.

So I thinkthere really needs to be two different specifications; one for
humans and another for machines. Ideally those two specifications would be
linked in that all the aspects of the human-friendly version would at least
be translatable to the machine-optimized version but there would be two (2)
different specs optimized for two (2) significantly different needs. 

So I'll throw out this straw-man. I'd advocate starting from scratch on a
human-friendly URI Template specification while keeping an eye on our
ability to translate it to the existing machine-optimized URI Template spec
as it exists, and maintaining some compatibility with the most basic use
cases.  One thing I think this buys us is the ability to disregard some of
the more complex encoding concerns that are simply unimportant in CMS or App
Framework use-cases.

And not to give you more work that you may not have asked for, but I think
you Mark would be the perfect person to lead this human-friendly version of
URI Templates, and I'd be honored to help you on that task if you choose to
head in that direction. I'd consider leading it but I simply don't have any
experience writing specs. 

If I had my preference I'd actually call the human-friendly version of URI
Templates "URL Templates" because most people are more familiar with "URL"
than "URI" and this is the human-friendly version, but I know that the w3c
really dislikes "URL" so my guess is that part wouldn't fly.

Well anyway, I've tossed out the piņata so bat away.

-Mike Schinkel 
http://mikeschinkel.com


-----Original Message-----
From: uri-request@w3.org [mailto:uri-request@w3.org] On Behalf Of Mark
Nottingham
Sent: Monday, September 15, 2008 7:58 AM
To: URI
Cc: Joe Gregorio; David Orchard; Marc Hadley
Subject: 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 18:26:48 UTC