Advanced Search in OPDS 1.1

[Patrick Thompson]

In OPDS 1.1 we are considering adding advanced search. This would allow you to constrain your search to certain fields, for example title or author. 

In OPDS 1.0 we support search with OpenSearch description. Our usage is pretty simple. We define a general OpenSearch description template, for example, from Feedbooks' OpenSearch description:

<Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>

where {searchTerms} is substituted with the URL-encoded search terms.

We would like to be able to optionally allow constrained searches, so that the user entered search terms apply to a particular domain; such as title or author or, in the case of audiobooks, narrator/contributor.

This could be manifested in a client where a radio button would allow the search to be across all fields, or just the title field, or just the author field.

To keep it simple and provide a common user experience across catalogs, my preference would be that we agree on a recommended set of conventions, rather than create a generally extensible mechanism.

The OpenSearch specification seems to be extensible enough to provide what we need.  

One way, perhaps, would be to have different search templates for each search type (though I don't know if it is valid to have multiple templates of the same Url type). The template parameter would be adopted as a standard convention by OPDS catalogs. 

For example:

General search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>

Title search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?title={atom:title}"/>

Author search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?author={atom:author}"/>

Contributor (e.g., narrator) search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?contributor={atom:contributor}"/>

In context:

<?xml version="1.0" encoding="UTF-8"?>

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">

    <ShortName>Feedbooks</ShortName>

    <Description>Search for e-books on Feedbooks</Description>

    <InputEncoding>UTF-8</InputEncoding>

    <OutputEncoding>UTF-8</OutputEncoding>

    <Image type="image/x-icon" width="16" height="16">http://www.feedbooks.com/favicon.ico</Image>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?title={atom:title}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?author={atom:author}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?contributor={atom:contributor}"/>

    <Query role="example" searchTerms="robot" />

</OpenSearchDescription>

Can anyone confirm if this would be a valid OpenDescription document?

Also, is this something that catalog vendors would be willing to support?

-Patrick

[Hadrien Gardeur]

One way, perhaps, would be to have different search templates for each search type (though I don't know if it is valid to have multiple templates of the same Url type). The template parameter would be adopted as a standard convention by OPDS catalogs. 

For example:

General search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>

Title search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?title={atom:title}"/>

Author search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?author={atom:author}"/>

Contributor (e.g., narrator) search: <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?contributor={atom:contributor}"/>

In context:

<?xml version="1.0" encoding="UTF-8"?>

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">

    <ShortName>Feedbooks</ShortName>

    <Description>Search for e-books on Feedbooks</Description>

    <InputEncoding>UTF-8</InputEncoding>

    <OutputEncoding>UTF-8</OutputEncoding>

    <Image type="image/x-icon" width="16" height="16">http://www.feedbooks.com/favicon.ico</Image>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?title={atom:title}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?author={atom:author}"/>

    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?contributor={atom:contributor}"/>

    <Query role="example" searchTerms="robot" />

</OpenSearchDescription>

Can anyone confirm if this would be a valid OpenDescription document?

It is if you add the namespace for Atom:

<?xml version="1.0" encoding="UTF-8"?>

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:atom="http://www.w3.org/2005/Atom">

    <ShortName>Feedbooks</ShortName>
    <Description>Search for e-books on Feedbooks</Description>
    <InputEncoding>UTF-8</InputEncoding>
    <OutputEncoding>UTF-8</OutputEncoding>
    <Image type="image/x-icon" width="16" height="16">http://www.feedbooks.com/favicon.ico</Image>
    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}"/>
    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?title={atom:title}"/>
    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?author={atom:author}"/>
    <Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?contributor={atom:contributor}"/>
    <Query role="example" searchTerms="robot" />
</OpenSearchDescription>

 

Also, is this something that catalog vendors would be willing to support?

I would implement this at Feedbooks. 

[Keith Fahlgren]

Hi,

Would a @rel attribute help clarify these Url elements at all?

Keith

[Hadrien Gardeur]

I don't think that a rel value is actually used at all in Open Search for such elements.

Based on the third example here: http://www.opensearch.org/Specifications/OpenSearch/1.1#Examples_2

It seems that a single URL could contain all the optional parameters too.

[Patrick Thompson]

Actually, it looks like you can have rel values. Here is what the spec says:

 Url rel values

Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute value should be treated by the client as if the rel attribute was not present at all.

If a client does not recognize the semantic meaning of any rel value token, then the containing Url should be ignored by the client.

Rel value tokens may be either fully qualified tokens (e.g., "http://example.com/rel#foo") or unqualified tokens (e.g., "results").

All fully qualified tokens must be a valid URL. The semantic meaning of any fully qualified token is outside the scope of this specification, but convention dictates that the URL should resolve to a resource that describes the relationship.

All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those tokens listed below have meaning defined in this specification.

Rel values:

"results" (default)

Represents a request for search results in the specified format.

"suggestions"

Represents a request for search suggestions in the specified format. See the OpenSearch Suggestions extension for further details.

"self"

Represents the canonical URL of this description document.

"collection"

Represents a request for a set of resources.

 

So perhaps a fully qualified rel value token indicating the type of search template.

-Patrick

--
You received this message because you are subscribed to the Google
Groups "Open Publication Distribution System" group.
 
To post to this group, send email to ope...@googlegroups.com
To unsubscribe from this group, send email to
openpub+u...@googlegroups.com
 
For more options, visit this group at
http://groups.google.com/group/openpub?hl=en

[Keith Fahlgren]

http://www.opensearch.org/Specifications/OpenSearch/1.1#Url_rel_values ?

[Hadrien Gardeur]

My bad...

I'm not sure that we need one though. We'll still serve "results" here and 

<Url type="application/atom+xml" template="http://www.feedbooks.com/search.atom?query={searchTerms}&title={atom:title}&author={atom:author}"/>

is a valid Open Search URL Template that would work both for "basic" and "advanced" search. 

The only thing that I'm worried about is whether existing clients will process correctly such URLs or not. 

[Patrick Thompson]

I agree, the rel value is unnecessary. Though I suppose it would allow us to identify particular search templates, so clients aren't surprised by complex templates like you describe.

-Patrick

From: Hadrien Gardeur <hadrien...@feedbooks.com>
Reply-To: <ope...@googlegroups.com>
Date: Sun, 5 Jun 2011 21:17:10 +0200
To: <ope...@googlegroups.com>
Subject: Re: [openpub] Advanced Search in OPDS 1.1

--

[Hadrien Gardeur]

I agree, the rel value is unnecessary. Though I suppose it would allow us to identify particular search templates, so clients aren't surprised by complex templates like you describe.

During the transition from 1.0 to 1.1, I agree but moving forward, clients should be capable of parsing both which is why I'm not sure that using a different rel value is such a good incentive. 

[Hadrien Gardeur]

Updated the section about search in the 1.1 draft with a paragraph & an example: http://code.google.com/p/openpub/wiki/CatalogSpecDraft#Search

[Patrick Thompson]

That is short and sweet. I think it's good. Just a couple of suggestions…

To make it more clear that the extra parameters are optional, we might add (without the bold, of course):

"An OPDS Catalog MAY also provide more advanced possibilities for its search endpoint, using one or more fully qualified parameters from the Atom namespace such as:"

Also, it may be helpful to client developers to add some language saying that the parameters are optional, though at least one parameter must be used.

Some examples may make it obvious too. For example, the search template:

<Url type="application/atom+xml;profile=opds-catalog"
     xmlns:atom="http://www.w3.org/2005/Atom"
     template="http://example.com/search?q={searchTerms}&author={atom:author}&contributor={atom:contributor}&title={atom:title}" />

Would allow search calls such as:

http://example.com/search?q=gardening

http://example.com/search?q=gardening&author=smith

http://example.com/search?author=drucker

http://example.com/search?author=ferriss&title=four

-Patrick

From: Hadrien Gardeur <hadrien...@feedbooks.com>
Reply-To: <ope...@googlegroups.com>
Date: Sun, 12 Jun 2011 16:35:17 +0200
To: <ope...@googlegroups.com>
Subject: Re: [openpub] Advanced Search in OPDS 1.1

--

[Hadrien Gardeur]

All good suggestions. I've updated the draft based on your feedback.