Uri Templates: Questions on draft-gregorio-uritemplate-06

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Uri Templates: Questions on draft-gregorio-uritemplate-06

Robbie Gates
Hi All,
 i am having trouble reconciling some of the examples in the 06 draft
with both the descriptions of the expansions and the sample
implementation.

The first set hinge on the handling of expansions where named (in the
sense of the table in appendix A) is true. The variable list has the
list value ["red", "green", "blue"]. The example expansions are:

        {;list}        ;list=red,green,blue
        {;list*}        ;red;green;blue
        {?list}        ?list=red,green,blue
        {?list*}        ?list=red&list=green&list=blue
        {&list}        &list=red,green,blue
        {&list*}        &list=red&list=green&list=blue

I don't understand why the expansions of ? and & include list= for
each entry when exploded. The description of the handling for the case
of an exploded list makes no mention of the use of the name, and there
is no separate section (as there is for the unexploded case). Also,
the table makes ; the same as ? and & for named, and yet their
handling appears different. The descriptions in 3.2.7 and 3.2.8 /
3.2.9 are likewise similar. In short, i can't see why the examples
differ, given the rest of the document, i was expecting

        {?list*}        ?red&green&blue
        {&list*}        &red&green&blue

I know these don't look like valid form query or form continuation
strings - am i missing something in the description of ? and & (and
the implementation hints) regarding special handling for the name when
exploded ?

The second case is the examples for the variable foo with string value
"That's right!"

        {foo}        That%27s%20right%21
        {+foo}        That%27s%20right!
        {#foo}        #That%27s%20right!

As far as i can see, the single quote character between the t and the
s is in sub-delims (in section 1.5) between & and (. I don't
understand why it is treated differently to ! which is also in
sub-delims. I would have expected these last two expansions to be:

        {+foo}        That's%20right!
        {#foo}        #That's%20right!

since both + and # have allow U+R, and ', ! (but not space) are
sub-delims and hence reserved.

Thanks in advance for any enlightenment,

 - Robbie


Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

Roy T. Fielding
On Sep 5, 2011, at 12:54 AM, Robbie Gates wrote:

> i am having trouble reconciling some of the examples in the 06 draft
> with both the descriptions of the expansions and the sample
> implementation.
>
> The first set hinge on the handling of expansions where named (in the
> sense of the table in appendix A) is true. The variable list has the
> list value ["red", "green", "blue"]. The example expansions are:
>
>        {;list}        ;list=red,green,blue
>        {;list*}        ;red;green;blue
>        {?list}        ?list=red,green,blue
>        {?list*}        ?list=red&list=green&list=blue
>        {&list}        &list=red,green,blue
>        {&list*}        &list=red&list=green&list=blue
>
> I don't understand why the expansions of ? and & include list= for
> each entry when exploded. The description of the handling for the case
> of an exploded list makes no mention of the use of the name, and there
> is no separate section (as there is for the unexploded case). Also,
> the table makes ; the same as ? and & for named, and yet their
> handling appears different. The descriptions in 3.2.7 and 3.2.8 /
> 3.2.9 are likewise similar. In short, i can't see why the examples
> differ, given the rest of the document, i was expecting
>
>        {?list*}        ?red&green&blue
>        {&list*}        &red&green&blue

Hi Robbie,

Yes, you are right -- that is a bug in the new algorithms that
I added for draft 06.  I'll work on a fix.

> The second case is the examples for the variable foo with string value
> "That's right!"
>
>        {foo}        That%27s%20right%21
>        {+foo}        That%27s%20right!
>        {#foo}        #That%27s%20right!
>
> As far as i can see, the single quote character between the t and the
> s is in sub-delims (in section 1.5) between & and (. I don't
> understand why it is treated differently to ! which is also in
> sub-delims. I would have expected these last two expansions to be:
>
>        {+foo}        That's%20right!
>        {#foo}        #That's%20right!
>
> since both + and # have allow U+R, and ', ! (but not space) are
> sub-delims and hence reserved.

Yep, another bug -- I really should check my own standards first.

Thanks for the careful review,

....Roy


Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

Roy T. Fielding
On Sep 6, 2011, at 3:49 PM, Roy T. Fielding wrote:

> On Sep 5, 2011, at 12:54 AM, Robbie Gates wrote:
>> I don't understand why the expansions of ? and & include list= for
>> each entry when exploded. The description of the handling for the case
>> of an exploded list makes no mention of the use of the name, and there
>> is no separate section (as there is for the unexploded case). Also,
>> the table makes ; the same as ? and & for named, and yet their
>> handling appears different. The descriptions in 3.2.7 and 3.2.8 /
>> 3.2.9 are likewise similar. In short, i can't see why the examples
>> differ, given the rest of the document, i was expecting
>>
>>       {?list*}        ?red&green&blue
>>       {&list*}        &red&green&blue
>
> Hi Robbie,
>
> Yes, you are right -- that is a bug in the new algorithms that
> I added for draft 06.  I'll work on a fix.

Actually, after having tried a fix to the algorithm, I think it
would be more useful to have the result you expect above (and it
would simplify the algorithm).  That also would provide a means
to define value-only parameters in the query component, which has
been requested in a private discussion.

....Roy

Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

Marc Portier-2


On 09-09-11 00:27, Roy T. Fielding wrote:

> On Sep 6, 2011, at 3:49 PM, Roy T. Fielding wrote:
>> On Sep 5, 2011, at 12:54 AM, Robbie Gates wrote:
>>> I don't understand why the expansions of ? and&  include list= for
>>> each entry when exploded. The description of the handling for the case
>>> of an exploded list makes no mention of the use of the name, and there
>>> is no separate section (as there is for the unexploded case). Also,
>>> the table makes ; the same as ? and&  for named, and yet their
>>> handling appears different. The descriptions in 3.2.7 and 3.2.8 /
>>> 3.2.9 are likewise similar. In short, i can't see why the examples
>>> differ, given the rest of the document, i was expecting
>>>
>>>        {?list*}        ?red&green&blue
>>>        {&list*}&red&green&blue
>>
>> Hi Robbie,
>>
>> Yes, you are right -- that is a bug in the new algorithms that
>> I added for draft 06.  I'll work on a fix.
>
> Actually, after having tried a fix to the algorithm, I think it
> would be more useful to have the result you expect above (and it
> would simplify the algorithm).  That also would provide a means
> to define value-only parameters in the query component, which has
> been requested in a private discussion.
>

Can't say I have a problem with it, but surely the current approach has
a very logic reason of existence, no?

Following the principle of least surprise (from a uri-template user
point of view, not from the implementation side) I would guess the
current expansion

{?list}    ?list=red,green,blue'
{?list*}   ?list=green&list=red&list=blue

is on the side of 80% of the expectations, no?

So at the least we make sure this keeps being possible, and (assuming we
find a way to provide both renditions) even would be the result of the
more naive & spontaneous use of the templates?


Of course, I do remember how I ended up finding the ;red;green;blue a
quirk expansion compared to ;list=red;list=green;list=blue  (the
opposite case?)

So why not think about having both just more explicit by declaring two
kinds of 'explodes' one 'named' (*), the other 'unnamed' (% maybe?)

then
{?list}    ?list=red,green,blue
{?list*}   ?list=green&list=red&list=blue
{?list%}   ?green&red&blue

{;list}    ;list=red,green,blue
{;list*}   ;list=green;list=red;list=blue
{;list%}   ;green;red;blue


yielding even less surprises?

-marc=


> ....Roy
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

t.petch-4
----- Original Message -----
From: "Marc Portier" <[hidden email]>
To: "Roy T. Fielding" <[hidden email]>
Cc: "URI" <[hidden email]>
Sent: Friday, September 09, 2011 8:34 AM

> On 09-09-11 00:27, Roy T. Fielding wrote:
> > On Sep 6, 2011, at 3:49 PM, Roy T. Fielding wrote:
> >> On Sep 5, 2011, at 12:54 AM, Robbie Gates wrote:
> >>> I don't understand why the expansions of ? and&  include list= for
> >>> each entry when exploded. The description of the handling for the case
> >>> of an exploded list makes no mention of the use of the name, and there
> >>> is no separate section (as there is for the unexploded case). Also,
> >>> the table makes ; the same as ? and&  for named, and yet their
> >>> handling appears different. The descriptions in 3.2.7 and 3.2.8 /
> >>> 3.2.9 are likewise similar. In short, i can't see why the examples
> >>> differ, given the rest of the document, i was expecting
> >>>
> >>>        {?list*}        ?red&green&blue
> >>>        {&list*}&red&green&blue
> >>
> >> Hi Robbie,
> >>
> >> Yes, you are right -- that is a bug in the new algorithms that
> >> I added for draft 06.  I'll work on a fix.
> >
> > Actually, after having tried a fix to the algorithm, I think it
> > would be more useful to have the result you expect above (and it
> > would simplify the algorithm).  That also would provide a means
> > to define value-only parameters in the query component, which has
> > been requested in a private discussion.
> >
> Can't say I have a problem with it, but surely the current approach has
> a very logic reason of existence, no?
>
> Following the principle of least surprise (from a uri-template user
> point of view, not from the implementation side) I would guess the
> current expansion
>
> {?list}    ?list=red,green,blue'
> {?list*}   ?list=green&list=red&list=blue
>
> is on the side of 80% of the expectations, no?
>
> So at the least we make sure this keeps being possible, and (assuming we
> find a way to provide both renditions) even would be the result of the
> more naive & spontaneous use of the templates?
>
> Of course, I do remember how I ended up finding the ;red;green;blue a
> quirk expansion compared to ;list=red;list=green;list=blue  (the
> opposite case?)
>
> So why not think about having both just more explicit by declaring two
> kinds of 'explodes' one 'named' (*), the other 'unnamed' (% maybe?)
>
> then
> {?list}    ?list=red,green,blue
> {?list*}   ?list=green&list=red&list=blue
> {?list%}   ?green&red&blue
>
> {;list}    ;list=red,green,blue
> {;list*}   ;list=green;list=red;list=blue
> {;list%}   ;green;red;blue

Mmmm .... the problem I have is that s.3.2.1 is clear that whether or not the
expansion is name=value,name=value,name=value or value,value,value
depends on whether or not the value is an associative array, and in the examples
in the rest of s.3 I cannot tell which values are an associative array and which
are not.

If the value is not an associative array, then the only action of the explode
modifier I can see is to change the separator character so I find the original
question indeterminate:-(

I dislike the idea above which, for me, overloads the explode modifier and is
NOT intuitive.  Changing the separator is one thing, switching from value list
to name=value pairs is orthogonal to that, so if the latter is to be done by an
explode modifier, as opposed to the value being an associative array, then there
should be a second explode modifier that does that and that alone.

Mind, I do find the text on explode modifiers opaque, and could be missing
something when it says
" An explode modifier ("*") indicates that the variable represents a
   composite value that may be substituted in full or partial forms,
   depending on the variable's type and value set.  Since URI Templates
   do not contain an indication of type or schema, this is assumed to be
   determined by context.  An example context is a mark-up element or
   header field that contains one attribute that is a template and one
   or more other attributes that define the schema applicable to
   variables found in the template.  Likewise, a typed programming
   language might differentiate variables as strings, lists, associative
   arrays, or structures."

I am afraid I have no idea what that is trying to say:-(

Tom Petch

> yielding even less surprises?
>
> -marc=
>
>
> > ....Roy
> >
> >
>


Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

Roy T. Fielding
In reply to this post by Marc Portier-2
On Sep 8, 2011, at 11:34 PM, Marc Portier wrote:
> Can't say I have a problem with it, but surely the current approach has a very logic reason of existence, no?

The original was a bit of a coin toss.  Although it looks more consistent with
forms syntax to do

> {?list}    ?list=red,green,blue'
> {?list*}   ?list=green&list=red&list=blue

the reality is that most forms-processing libraries assume that
the names are unique.  They are usually processed as an associative
array or hash, so what happens is that the last parameter named
"list" wins.  That's why my first try at this pattern appended
a number to the subsequent names.

At this point, I am just going to say that if an application
actually wants the above, then it should supply an associative
array itself and not rely on funky list magic.  Also, someone
else requested the ability to define query parameters without
any =value, as in

   foo?a=c&d

which is possible (in the editor's draft) if we have

   a := "c"
   b := [ "d" ]

   {?a,b}

> So why not think about having both just more explicit by declaring two kinds of 'explodes' one 'named' (*), the other 'unnamed' (% maybe?)

Modifiers like explode effectively double the complexity of expansion,
so I am reticent to add any more unless there is a proven need.

....Roy


Reply | Threaded
Open this post in threaded view
|

Re: Uri Templates: Questions on draft-gregorio-uritemplate-06

Marc Portier-2


On 09-09-11 22:29, Roy T. Fielding wrote:

> On Sep 8, 2011, at 11:34 PM, Marc Portier wrote:
>> Can't say I have a problem with it, but surely the current approach has a very logic reason of existence, no?
>
> The original was a bit of a coin toss.  Although it looks more consistent with
> forms syntax to do
>
>> {?list}    ?list=red,green,blue'
>> {?list*}   ?list=green&list=red&list=blue
>
> the reality is that most forms-processing libraries assume that
> the names are unique.  They are usually processed as an associative
> array or hash, so what happens is that the last parameter named
> "list" wins.  That's why my first try at this pattern appended
> a number to the subsequent names.
>

Which I think is a neat idea in fact.  I don't want to rewind all done
work, but is there any history on why it was dropped?

> At this point, I am just going to say that if an application
> actually wants the above, then it should supply an associative
> array itself and not rely on funky list magic.  Also, someone

hm,

I understand (and agree on) what you say about the list magic, but I'm
underwhelmed at yet another push off to context-values-pre-processing
(as we had with the defaults)

In general terms it feels like the slippery slope from effectiveness
versus efficiency (As a wise man once told me: "In your strive for
efficiency you should watch out not to become ineffective")
Or put bluntly: if all is done in context-pre-processing, then all what
remains to be done is string-concatenation... (I know I'm stretching it,
just wanting to make it extreme to get the argument across.)

Might be just me, but I like to think about the 'context' as rather
close to a business object in an application.  The more we need to tweak
it before being 'useable' in uri-templates, the lesser value remains to
using the uri-templates, no?

> else requested the ability to define query parameters without
> any =value, as in
>
>     foo?a=c&d
>
> which is possible (in the editor's draft) if we have
>
>     a := "c"
>     b := [ "d" ]
>

Which triggers Tom's remark about the 'type' of value driving the naming
or not, rather then the template declaring it.

>     {?a,b}
>

and adding e:= [('f','g')]
then (surprisingly?) explodes {?a,b,e} to ?a=c&d&f=g

>> So why not think about having both just more explicit by declaring two kinds of 'explodes' one 'named' (*), the other 'unnamed' (% maybe?)
>
> Modifiers like explode effectively double the complexity of expansion,
> so I am reticent to add any more unless there is a proven need.
>

Ok, I buy that.

But.
I don't think I was adding an aspect to what uri-templates is trying to
do: Deciding between 'named' versus 'unnamed' is already in there, some
of it rather implicit, but still.


Dunno if below helps, if not just ignore, I know I have a natural reflex
towards consensus, but I do know howto value clear (even limiting)
decisions.


Taking a step back, maybe we should first agree on the aspects
uri-templates should cover?  For each part of the uri to be expanded,
what are the decisions to be taken?
   * what prefix-char to use
     * and should it be present or not if no remainder follows
   * following-join-char to use
     * and should it be used between empty values
   * add or not the context-name as used in the template
     * or silence/drop it, and
     * should that be driven by the types of the context values itself?
   * add or not a member name
     (like the dropped sequence-number suffix,
      or the associative array explosion where keys are promoted to )
     * in which cases? for which
   * explode arrays and hashmaps to follow up values
   * truncate the value to its first N chars
   * binding char between name and value (=)
     * and if it should be or not present in absence of the value
   * way of encoding (allow reserved or not)
     * for both names and values ?
   * (no longer) provide a default for undefined values

(miss any?)


If I look at my implementation and the suggestion stemming from the
table in appendix A. Then the current operators are pretty much somewhat
a short-hand notation, each of them implying some of the above decisions.

Yet with every iteration of those implied decisions there seems to be a
side stepping up and not finding their use-case or preferred set of
decisions?

Can/should we silence those discussions by offering an
explicit/canonical syntax (through a new 'elaborate' operator) that
allows for a very clear, explicit, unambiguous expression that is
capable of catching all aspects?


regards,
-marc=

> ....Roy
>
>