Link-Template

The issue I have with the fiql draft is not really the query
syntax
itself, as much as it is with the poor definition of the
qname-based
selectors and the definition of the fq:interface mechanism. 
What I
think would be a significantly better approach, as I've
mentioned, is a
more generic link-template mechanism that could be used for
a broader
set of use cases.  Prior to the publication of fiql, I had
already been
working on a syntax for the link-template, which would be
simple to
extend to support the fiql requirements.  For instance,

<template xmlns="http://pu
rl.org/atompub/templates/1.0"
  title="Search"
  rel="search"
type="application/atom+xml"
hreflang="en-US"
  template="http://example.org/{index=ent
ries}?{-join|&amp;|filter,num}">
  <variable name="index" type="http://.../enum">
    <value>entries</value>
    <value>comments</value>
  </variable>
  <variable name="num" type="http://.../simple"
pattern="d+" />
  <variable name="filter" type="http://.../expression
">
    <field name="title" />
    <field name="rating" type="http://.../numeric"
/>
    <field name="updated" type="http://.../date"
/>
  </variable>
</template>

With this, there is messing around with QNames.  There's
just a URI
Template with a number of template variables that each map
to some
distinct value definition.

The "index" variable is typed as an
"enum" with two possible values,
"entries" and "comments"

The "num" variable is a simple string value
matching the regex pattern
"d+" (one or more alphanumeric digits).

The "filter" variable is an expression that would
match the FIQL syntax.
 Within the filter variable definition are specific typed
field
definitions that define the fields that can be used within
the fiql
expression.

For example, given the values:

  index  = entries
  num    = 10
  filter = title==foo;rating=5

The URI Template expands to:

  http://example.org/entries?num=10&filter=ti
tle==foo;rating==5

Personally, I think this approach provides significantly
more
flexibility than the fq:interface definition without adding
too much
unnecessary complexity.  It's also something that can be
reused easily
for other use cases beyond basic searching and filtering

For instance,

<template xmlns="http://pu
rl.org/atompub/templates/1.0"
  title="Archive"
  rel="archive"
type="application/atom+xml"
hreflang="en-US"
  template="http://example.org/archi
ves//">
  <variable name="year"
            type="http://.../simple"
            pattern="d" />
  <variable name="month"
            type="http://.../simple"
            pattern="0[1-9]|1[0-2]" />
</template>

And another:

<template xmlns="http://pu
rl.org/atompub/templates/1.0"
  title="Sync"
  rel="sync" type="application/atom+xml"
hreflang="en-US"
  template="http://example.org/sync?
{-join|&|start,end">
  <variable name="start" type="http://.../date"
/>
  <variable name="end" type="http://.../date"
/>
</template>

Getting back to the FIQL use case, however, let's break down
the field
definition from earlier:

  <variable name="filter" type="http://.../expression
">
    <field name="title" />
    <field name="rating" type="http://.../numeric"
/>
    <field name="updated" type="http://.../date"
/>
  </variable>

Given this, there is obviously no clear connection between
each of the
fields and the elements in the Atom.  Personally, I think
this is a good
thing, as it ought to be up to the server code to determine
the
appropriate mapping between the fields and the elements. 
However, if we
do need a means of explicitly connecting the two, that can
be done via
the field element definition.  For instance, in order to
avoid having to
mess with QNames, we could define a URI identifier for each
of the Atom
elements, e.g.,

  <field name="title" ref="http://www.w3
.org/2005/Atom/title" />

This would tell us that the title field maps to the
atom:title element.

Perhaps I wanted to filter on title type (text, html, or
xhtml). For
that I could do something like:

  <field name="title" ref="http://www.w3
.org/2005/Atom/title" />
  <field name="type"
         type="http://.../enum"
         ref="http
://www.w3.org/2005/Atom/title/type">
    <value>text</value>
    <value>html</value>
    <value>xhtml</value>
  </field>

This would allow me to create expressions like:

  title==foo;type==html
  title==bar;type==text

I'm not convinced it's necessary, but like the fq:index
element, the
field element could have a path attribute as well:

  <field name="rating"
path="snx:rating" type="http://.../numeric"
/>

The link-template mechanism has the benefit of being more
generically
applicable to more scenarios that fq:interface; allows the
use of any
URI Template, not just ones that contain ; avoids
the
inherently messy qname garbage; and is not prohibitively
more
complicated than the fq:interface syntax.

- James

Mark Nottingham wrote:
> Wow, really? Are all of your use cases behind a
firewall / within the
> same administrative domain?
> 
> Cheers,
> 
> 
> On 20/12/2007, at 5:15 AM, James M Snell wrote:
> 
>> Regarding fq:interface, I'm not convinced the
fq:index bit is necessary;
>> and I'd much rather see a more generic way of
inserting URI Templates
>> into a feed
> 
> 
> -- 
> Mark Nottingham     http://www.mnot.net/
> 
> 

Sure, if we can get forward motion on a template-based
analogy of the  
link element, I'm all for it; I just didn't want to try to
boil the  
ocean in this one case. Seems like we have to settle on what
a link  
template is first, however...

Cheers,


On 22/12/2007, at 5:19 PM, James M Snell wrote:

> The issue I have with the fiql draft is not really the
query syntax
> itself, as much as it is with the poor definition of
the qname-based
> selectors and the definition of the fq:interface
mechanism.  What I
> think would be a significantly better approach, as I've
mentioned,  
> is a
> more generic link-template mechanism that could be used
for a broader
> set of use cases.  Prior to the publication of fiql, I
had already  
> been
> working on a syntax for the link-template, which would
be simple to
> extend to support the fiql requirements.  For
instance,
>
> <template xmlns="http://pu
rl.org/atompub/templates/1.0"
>  title="Search"
>  rel="search"
type="application/atom+xml"
hreflang="en-US"
>  template="http://example.org/{index=ent
ries}?{-join|&amp;| 
> filter,num}">
>  <variable name="index" type="http://.../enum">
>    <value>entries</value>
>    <value>comments</value>
>  </variable>
>  <variable name="num" type="http://.../simple"
pattern="d+" />
>  <variable name="filter" type="http://.../expression
">
>    <field name="title" />
>    <field name="rating" type="http://.../numeric"
/>
>    <field name="updated" type="http://.../date"
/>
>  </variable>
> </template>
>
> With this, there is messing around with QNames. 
There's just a URI
> Template with a number of template variables that each
map to some
> distinct value definition.
>
> The "index" variable is typed as an
"enum" with two possible values,
> "entries" and "comments"
>
> The "num" variable is a simple string value
matching the regex pattern
> "d+" (one or more alphanumeric digits).
>
> The "filter" variable is an expression that
would match the FIQL  
> syntax.
> Within the filter variable definition are specific
typed field
> definitions that define the fields that can be used
within the fiql
> expression.
>
> For example, given the values:
>
>  index  = entries
>  num    = 10
>  filter = title==foo;rating=5
>
> The URI Template expands to:
>
>  http://example.org/entries?num=10&filter=ti
tle==foo;rating==5
>
> Personally, I think this approach provides
significantly more
> flexibility than the fq:interface definition without
adding too much
> unnecessary complexity.  It's also something that can
be reused easily
> for other use cases beyond basic searching and
filtering
>
> For instance,
>
> <template xmlns="http://pu
rl.org/atompub/templates/1.0"
>  title="Archive"
>  rel="archive"
type="application/atom+xml"
hreflang="en-US"
>  template="http://example.org/archi
ves//">
>  <variable name="year"
>            type="http://.../simple"
>            pattern="d" />
>  <variable name="month"
>            type="http://.../simple"
>            pattern="0[1-9]|1[0-2]" />
> </template>
>
> And another:
>
> <template xmlns="http://pu
rl.org/atompub/templates/1.0"
>  title="Sync"
>  rel="sync"
type="application/atom+xml"
hreflang="en-US"
>  template="http://example.org/sync?
{-join|&|start,end">
>  <variable name="start" type="http://.../date"
/>
>  <variable name="end" type="http://.../date"
/>
> </template>
>
> Getting back to the FIQL use case, however, let's break
down the field
> definition from earlier:
>
>  <variable name="filter" type="http://.../expression
">
>    <field name="title" />
>    <field name="rating" type="http://.../numeric"
/>
>    <field name="updated" type="http://.../date"
/>
>  </variable>
>
> Given this, there is obviously no clear connection
between each of the
> fields and the elements in the Atom.  Personally, I
think this is a  
> good
> thing, as it ought to be up to the server code to
determine the
> appropriate mapping between the fields and the
elements.  However,  
> if we
> do need a means of explicitly connecting the two, that
can be done via
> the field element definition.  For instance, in order
to avoid  
> having to
> mess with QNames, we could define a URI identifier for
each of the  
> Atom
> elements, e.g.,
>
>  <field name="title" ref="http://www.w3
.org/2005/Atom/title" />
>
> This would tell us that the title field maps to the
atom:title  
> element.
>
> Perhaps I wanted to filter on title type (text, html,
or xhtml). For
> that I could do something like:
>
>  <field name="title" ref="http://www.w3
.org/2005/Atom/title" />
>  <field name="type"
>         type="http://.../enum"
>         ref="http
://www.w3.org/2005/Atom/title/type">
>    <value>text</value>
>    <value>html</value>
>    <value>xhtml</value>
>  </field>
>
> This would allow me to create expressions like:
>
>  title==foo;type==html
>  title==bar;type==text
>
> I'm not convinced it's necessary, but like the fq:index
element, the
> field element could have a path attribute as well:
>
>  <field name="rating"
path="snx:rating" type="http://.../numeric"
/>
>
> The link-template mechanism has the benefit of being
more generically
> applicable to more scenarios that fq:interface; allows
the use of any
> URI Template, not just ones that contain ;
avoids the
> inherently messy qname garbage; and is not
prohibitively more
> complicated than the fq:interface syntax.
>
> - James
>
> Mark Nottingham wrote:
>> Wow, really? Are all of your use cases behind a
firewall / within the
>> same administrative domain?
>>
>> Cheers,
>>
>>
>> On 20/12/2007, at 5:15 AM, James M Snell wrote:
>>
>>> Regarding fq:interface, I'm not convinced the
fq:index bit is  
>>> necessary;
>>> and I'd much rather see a more generic way of
inserting URI  
>>> Templates
>>> into a feed
>>
>>
>> -- 
>> Mark Nottingham     http://www.mnot.net/
>>
>>


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