"OpenSearch is a collection of simple formats for the sharing of search results."[1]

This page concerns how an OpenSearch supporting search service might indicate that it facilitates queries filtered by license and how results might be annotated with license info.

OpenSearch consists of a format describing a search service and extensions of RSS 2.0 and Atom 1.0 to faciliate returning search results in these syndication formats.

OpenSearch Description Document

OpenSearch Description Document is a file format for describing a search service that supports OpenSearch.

Attribution and SyndicationRights elements are not relevant -- they describe search results, not the content referred to by search results.

How should a CC-enabled search engine describe itself? Three options:

CC options as special keywords

Search engines already support many special keyword operators, e.g., link:, site:.

Absolutely no extension of the description document is required to faciliate this use.

Going this route, it would be useful if search services supported a consistent syntax for license restrictions, as many do for link, site, etc.

Multiple description documents

  • Multiple descriptions, one corresponding to each filter services wishes to expose, e.g., one of four for each of the examples here, specifically four OpenSearch Description Documents, each with a Url element (or elements, corresponding to HTML/RSS/Atom outputs) hardcoding desired filter, like

<Url type="application/rss+xml" template="http://flickr.com/search/?l=cc&q={searchTerms}" />

<Url type="application/rss+xml" template="http://flickr.com/search/?l=comm&q={searchTerms}" />

<Url type="application/rss+xml" template="http://flickr.com/search/?l=deriv&q={searchTerms}" />

<Url type="application/rss+xml" template="http://flickr.com/search/?l=commderiv&q={searchTerms}" />

Note that each of these would be in a separate description document; there would be four description documents.

Extension with custom parameters

URL templates used in the template attribute of the Url element may have custom parameters. A CC extension could define these, or possibly OpenSearch Description Documents could utilize the parameter extension to describe license filter parameters.

An extension approach would be more elegant than a multiple description approach, but may not work well for existing services that may have URL formats difficult to map to parameters for each license attribute one may want to filter on.

An imaginary CC extension might include the following custom parameters:


Others may be useful as well, e.g.,


All of the above would presumably expect a boolean value (1/0, true/false), except the last, which might expect a license URL or pattern.

Example use in a Url element:

<Url type="application/atom+xml" template="http://example.com/?q={searchTerms}&cc-distribution={cc:permitsDistribution?}&cc-nocommercial={cc:prohibitsCommercialUse?}&cc-derivs={cc:permitsDerivativeWorks?}"/>

This solution may not be practical. How do OpenSearch consumers handle custom parameters?

OpenSearch Response Elements

OpenSearch Response Elements extend syndication formats to faciliate using these to convey search results.

It should be possible to use existing RSS 2.0 and Atom 1.0 license extensions to indicate the licensing of resources referred to in search feeds.


Open Questions

  • Determine best practice for using OpenSearch Description Document to faciliate CC filtered search.
    • Multiple description documents?
    • Extension with custom parameters -- how in practice to OpenSearch consumers deal with custom parameters?
    • CC filters entirely specified in searchTerms.


  • Implement best practices in CcHost
  • Encourage search services that support OpenSearch and remember license info for searchable materials to include license annotations in OpenSearch result feeds, per existing extensions.

See Also