RE: URI Template: query param name different than variable name

> > I suggest changing the '?' operator to have a form like "{?name=[var]}".
> > If 'var' is omitted (the template is "{?name=}") then (as with the
> > current draft) 'name' is used as both the variable name and the query
> > parameter name.
 
> But that introduces a whole host of problems.  Visually, it
> looks like the second variable is a default value (even if
> we were to change the default syntax).

"{?name=var}" makes the template look similar to the URIs that can be built from it, just with "var" in place of an actual value (and some {} brackets). Personally I find this visually quite intuitive -- more so than the existing draft.


> It also adds
> variables to the template that describe the implementation
> rather than the end-result.  And a complex schema like
> OpenSearch would end up with a huge, ugly template.

I don't quite understand this point. Which variable describes "the implementation rather than the end-result"?
A template is supposed to describe how to build URIs to match the server's "implementation" of their own URI space.

If OpenSearch defines a dozen terms with long labels then a template will have to list all those long labels if it want to control how the different terms are mapped to a particular server's URL space. I don't think there is any sensible way around this. I also don't think long templates are much of a problem in these cases.


> > Please also require a template processor to be smart about a '?'
> > operator: substituting '?...' if it is the first query param (no
> > previous '?' in the URI being built), or substituting '&...' otherwise.
 
> The template processor doesn't know where it is in the URI.

As long as it is processing the whole template (not an individual {...} placeholder) it does know where it is. The rule for converting a '?' operator to '?' or '&' can be very easy: substitute '?' if, and only if, there is no previous '?' in the string being built.

> Is such a feature still needed with the profile idea above?

Yes. A optional "profile" attribute might be ok, but I find the "map" attribute idea appalling.

> Link-Template: <http://example.com/find{?q,lang};

>        profile="http://opensearch.org/1.1";
>        map="q:searchTerms,lang:language"

I would much prefer

Link-Template: <http://example.com/find{?q=searchTerms}{?lang=language}>;
  profile="http://opensearch.org/1.1"

Adding "map" substantially complicates handling templates.
Now you need to store/transmit/configure 2 items.
You can no longer simply introduce an analogous template field mimicking an existing URI field in a protocol, file format or API.

"map" is unnecessary. If you need the mapping to process the template (which you do), then just include it in the template itself.


> > If this {?name=[var]} proposal is accepted it might be worth making
> > some other changes to keep the syntax consistent. Below is one idea:
> >   {[op [name=]] [vartype] varname [modifier] [| default]}
> > * add a ',' operator, instead of supporting a variable-list in each
> > {...} expression

> But then we can't represent common idioms like imagemap,
> coordinates, etc.  And it is ugly.

Perhaps {/x}{/y}{/z} is slightly uglier than {/x,y,z}.
However, it is more obvious to me how {/x}{/y}{/z} is processed than {/x,y,z} -- the former just looks more like the URIs that can be built from it.
Comma-separate variable lists in each {...} expression also means we need to escape commas in variable names and default values.

> > * 'default' is a default for the whole expression, not just the
> > variable value excluding modifiers

> But then we can't easily define path segment defaults
> within a hierarchy.

Could you give an example template with path segment defaults within a hierarchy?
Instead of
  "{/country=US,state=CA,city}"
you can do
  "/{country|US}/{state|CA}{/city}



--
James Manger

Received on Friday, 26 February 2010 05:56:53 UTC