Re: [Fwd: Re: [search-ws] Description Language]

[Ashley Sanders <a.sanders@manchester.ac.uk>]

[Cc'd to search-ws group email list.]

Rob, Ralph,

> 1.  I'd prefer a clean division between request description and response
> description.  <request> and <response>

Yes. I'd come to the same conclusion and have changed the Perl
module to expect a <request> and <response> element. (It was the
way it was because of my reluctance to keep introducing new
elements...)

> 2.  <spec> is not very distinctive.  <interface> or similar?

Yes, <spec> isn't good. I've changed it to <sws> which may not
be any better, but at least it does stand for Search-WS which
is the name of the committee.

> 3.  Prefer 'param' to 'field' for request parameters.

Yes. All the .sws files in the stuff I've uploaded to the
groups web site now use <param> instead of <field>.

> 4.  Inconsistency between <var name="numberOfItems"> and <items> ?

I'm not sure I see the inconsistency.

>     Prefer <field type="numberOfItems">

Now the <field> has been changed to <param> I could use
<field> instead of <var>... However, I think I still prefer
<var> -- pretty much as I do see them as variables in a
programming language.

> 5.  URI templates are okay in an attribute, but /interface/request/uri
> seems to make more sense to me than /spec/search/@href.  Minor point, as
> there's very valid precedent for @href!  

 > 6.  I have a preference for elements over attributes, as they're easier
 > to extend in the future with additional structure if necessary.


I've left it as @href for now, but I have no real objections to
a <uri> element as you describe (other than my natural inclination
not to keep creating new elements -- which I'll admit is probably
not a goo objection...)

> 7.  We should watch (and contribute to) the URI template discussion on
> the w3 uri list to ensure that it meets our needs.  At the moment it
> doesn't.
> 
> 
> So to recast the current description:
> 
> <interface>
>   <request>   
>     <uri>http://copac.ac.uk/3000/copac?operation=searchRetrieve
>         &amp;version=1.1&amp;query={query}&amp;maximumRecords={maxItems}
>         &amp;recordSchema=info:srw/schema/1/mods-v3.0</uri>
>     <param name="query">
>       <semantics>info:sru/cql/1.0</semantics>
>     </param>
>     <param name="maxItems">
>       <default>25</default>
>     </param>
>   </request>
>   <response>
>     <type>text/sru+xml</type>
>     <field name="numberOfItems">
>       <xpath select="/zs:searchRetrieveResponse/zs:numberOfRecords"/>
>     </field>
>     <field name="items">
>       <xpath select="/zs:searchRetrieveResponse/zs:records"/>
>     </field>
>   </response>
> </interface>

The above is basically okay, except my struct in the latest version
is (just showing the top level elements):

<sws>
  <op>
   <request>
    ...
   </request>
   <response>
     ...
   </response>
  </op>
</sws>

The <op> is there because you often need multiple http requests to
achieve ones goal. I guess you could do away with <op> but I think
it is nice to tie the request and response together inside a single
element.

I've used <op> in the latest version, but I'm not really sure
what a good name would be. The Perl module doesn't mind what they are
called!

> 
> 
> Traditional Form Interface:
> 
> * Not sure of the utility of name attribute on form.

The name attribute can go (it's still there because I forgot to
remove it before I uploaded the latest file.)

> * <field> to <param> as above
> * Wrap <form> in <request> as above
> * I understand the utility of <retrieve> vs <search> but I'm not sure
> that I'm happy with the implementation.  The response DOES retrieve
> items, just not the full description of the resource. Don't have a
> constructive suggestion yet though!

Here are some some thoughts of my own on future additions to the
"language."

I still think we need to add conditions -- so that you can specify
that an operation only occurs if a specific condition is met.
The use case for this would be sorting a Copac result set.
Copac only allows sort operation on result sets of less than
a certain number of records.

We also need to add iteration somehow. The use case for this would
be to retrieve, say, the first 100 results from Google. Ie you need
to request the "next page" 9 times. (I guess you could get around the 
need for iteration by un-rolling the loop. One could, for instance, just 
list 10 get next page operations in the specification file with a
post-condition on each operation to stop processing if there are less
than 100 results.)

I also think pre- and post-conditions on operations would be good. Or in
other words, stop all processing now if this condition is not met
(probably because of an error or an unexpected result.)

The <var> variables at the moment are just scalars (to use Perl
jargon.) I think it might be useful to have arrays to which new
values can be appended. The <items> is a special case of a <var>
which is an array. (Which troubles me as I don't like special
cases.) I called it <items> as I was trying to stick to the
vocabulary we decided on during one of the phone meetings. I
think the way to go is to define some sort of array operations
into which the records/items can be pushed as they are garnered
from the retrieved url responses.

I think this is enough for now...

Regards,

Ashley.
-- 
Ashley Sanders               a.sanders@manchester.ac.uk
Copac http://copac.ac.uk A Mimas service funded by JISC