Re: URI Template experience

On Feb 26, 2010, at 8:52 AM, Marc Hadley wrote:
> Some feedback on the latest:
> 
> Section 1.1
> 
> "A URI Template provides both a structural description of a URI space
> and, when variable values are provided, a simple instruction on how
> to construct URIs corresponding to each of those values."
> 
> Very minor but I found this a little confusing wrt to cardinality of URIs and variable values, suggest replacing with:
> 
> "A URI Template provides both a structural description of a URI space
> and, when variable values are provided, a simple instruction on how
> to construct a URI corresponding to those values."

Yep, done.

> Section 1.2
> 
> Table rows 3.3 and 3.4 - What happens for {list}, {keys} ? Should {list} could be expanded as val1,val2,val3 ?

Yes, done.  Same for keys.  I'd like to keep the behavior as consistent
as possible regardless of type, since the template itself doesn't show
the type.

> Table row 3.5 - What happens for {;list} ? By analogy to the ? operator I'd expect it to result in ;list=val1,val2,val3 ?

Right, we only want to do weird things when * or + are given.

> Do we also need to support {;list*} and {;list+} ? Same question applies to expectations for {;keys}.

I am leaning towards

|     |     |    {;list}           ;val1,val2,val3                |
|     |     |    {;list*}          ;val1;val2;val3                |
|     |     |    {;list+}          ;list=val1;list=val2;list=val3 |
|     |     |    {;keys}           ;key1,val1,key2,val2           |
|     |     |    {;keys*}          ;key1=val1;key2=val2           |
|     |     |    {;keys+}          ;keys.key1=val1;keys.key2=val2 |


> Table row 3.6 - Is the ?list.1=val1&list.2=val2 style of expansion common enough to warrant the special + modifier ?

Probably not, but I couldn't think of a better expansion.  Any ideas?
I guess that I should make it consistent with {;list+} and just assume
that people won't use it if unique keys are required.  That would be

|     |     |    {?list}           ?list=val1,val2,val3           |
|     |     |    {?list*}          ?val1&val2&val3                |
|     |     |    {?list+}          ?list=val1&list=val2&list=val3 |
|     |     |    {?keys}           ?keys=key1,val1,key2,val2      |
|     |     |    {?keys*}          ?key1=val1&key2=val2           |
|     |     |    {?keys+}          ?keys.key1=val1&keys.key2=val2 |


> For 3.6-3.8 I think the * form is the most common so I'd suggest swapping the meaning. E.g.
> 
> {/list} => /val1/val2/val3
> {/list*} => /val1,val2,val3

That would be inconsistent with all of the other cases, which I think would
be worse than adjusting for the common case.  The idea is that, without the
explode modifier, one can look at the template and match variables to values
if the template is bordered by reserved characters.  The modifier indicates
that probably won't be true and that magic is expected here, and I would
prefer that the magic be consistent for the various operators.  I.e.,
'*' means use the variable structure for placement of delimiters, and
'+' means also use name labels to allow for multivariable expansions.

The summary table is getting too long.  I should move the exhaustive examples
to the either the expansion section or the Examples section.

....Roy

Received on Saturday, 27 February 2010 00:34:02 UTC