Introduction
An OpenSearch description document is a small XML file with which a site tells search clients, chiefly browsers, how to search it: its name, a
description, and URL templates for search results and suggestions. The file is usually called opensearch.xml and is linked from a page with
<link rel="search" type="application/opensearchdescription+xml" title="Site" href="/opensearch.xml">. The specification read for this site is
OpenSearch 1.1 Draft 6, whose namespace is http://a9.com/-/spec/opensearch/1.1/. The media type is
application/opensearchdescription+xml, which the draft says was pending registration with IANA.
Structure
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Web Search</ShortName>
<Description>Use Example.com to search the Web.</Description>
<Url type="text/html" template="http://example.com/search?q={searchTerms}"/>
<Image height="16" width="16" type="image/x-icon">http://example.com/favicon.ico</Image>
<Query role="example" searchTerms="cat"/>
</OpenSearchDescription>
| Element | Times | Rule (Draft 6) |
|---|---|---|
OpenSearchDescription | root, once | The root node of the document. |
ShortName | exactly once | A brief title: 16 or fewer characters of plain text, no markup. |
Description | exactly once | A text description: 1024 or fewer characters, no markup. |
Url | one or more | Attributes template (required) and type (MIME type, required); optional rel (space-separated tokens, default results), indexOffset and pageOffset (integers, default 1). Rel tokens: results, suggestions, self, collection, or a fully qualified URL; an unqualified token is lower-case, of the form [a-z][a-z\-]+. A client that recognises none of a Url’s tokens ignores that Url. |
Contact | 0 or 1 | An email address (addr-spec of RFC 2822). |
Tags | 0 or 1 | Single words separated by spaces; 256 or fewer characters. |
LongName | 0 or 1 | An extended title: 48 or fewer characters. Clients should use ShortName when absent. |
Image | 0 or more | A URI of an image; optional height, width (non-negative integers) and type (MIME type). A 16x16 icon and a 64x64 PNG or JPEG are recommended. |
Query | 0 or more | A search query clients can run. role is required: request, example, related, correction, subset or superset (the list of local role values is exhaustive), or a role fully qualified with a prefix that is declared as an XML namespace on the Query or an ancestor (a client ignores a Query whose qualified role it does not know). title is optional: 256 or fewer characters of plain text, no markup. totalResults is optional: a non-negative integer. The attributes searchTerms, count, startIndex, startPage, language, inputEncoding and outputEncoding give the value of the parameter of the same name; extended attributes must belong to a namespace. Authors should provide at least one role="example" query that returns results (a SHOULD rule). |
Developer | 0 or 1 | The creator of the description document: 64 or fewer characters. |
Attribution | 0 or 1 | Sources to credit: 256 or fewer characters. |
SyndicationRight | 0 or 1 | open (default), limited, private or closed, case-insensitive. |
AdultContent | 0 or 1 | “false”, “FALSE”, “0”, “no” and “NO” are false; any other string is true. Default false. |
Language | 0 or more | A language identifier (RFC 5646), or * for any (default). |
InputEncoding, OutputEncoding | 0 or more | A character encoding name from the IANA registry; default UTF-8. |
URL templates
A template is a URL in which {name} is a required parameter and {name?} an optional one that may be replaced by the empty string.
The unqualified names are an exhaustive list: searchTerms, count, startIndex, startPage,
language, inputEncoding and outputEncoding. A qualified name {prefix:name} needs the prefix declared as an
XML namespace on the element or an ancestor; names and prefixes are case sensitive. The grammar is an ABNF in the draft that builds on RFC 3986: a scheme,
://, an authority, and so on, with parameters allowed in each part.
In the explorer
A file named opensearch.xml, or any .xml file whose root element is OpenSearchDescription in the 1.1 namespace, opens here: the XML
tree with the elements read as described above, tabs for the Url elements (their rel, type, template, parameters, method and Param elements), the images and the queries, the
elements of other specifications, the problems and the notes. Each MUST-level rule above that the file breaks is a problem, quoted from the draft. A note is not a problem: it is in the Notes tab,
not in the Problems tab and not in the problem count. The notes are the SHOULD rule (no Query role="example"), a results template that has no {searchTerms} in its template or in a
Param value (the draft text read does not say that outright), and a template that is only a parameter such as {searchTerms}, which is accepted (the draft shows it as an example of a required
parameter and does not say a scheme must precede a parameter; our reading). A POST Url that carries {searchTerms} in a Param value is not reported. The
method attribute, the Param elements and elements such as moz:SearchForm belong to other specifications that are not in Draft 6: they are shown in the Urls table and in the
Extensions tab, labelled with the specification they come from (our knowledge, not text read for this work), and are never called errors. The Problems tab numbers its rows from 1. Other XML files named opensearch.xml open as XML, as before.
Nothing is fetched and no template is expanded.
Not described
Known, not yet covered
- Reference: the OpenSearch response elements (
totalResults,startIndex,itemsPerPagein a search response) and the autodiscovery rules are in the draft and are not described here (the Query element, its roles and attributes are described above). - Reference: the Suggestions and other extensions named in the draft are not described.
- Viewer: the full template ABNF is not implemented: braces, parameter names, prefixes and a leading scheme are checked; the allowed characters of each part are not. Language identifiers, encoding names and MIME types are checked for shape, not against their registries. OpenSearch 1.0 documents (a different namespace) are not read.
- Reference:
method,Param(the Parameter extension) and the Mozilla elements (moz:SearchForm, the MozSearch 1.0 format) are not in Draft 6 and their rules are not described: the viewer only labels them, by namespace, from general knowledge (not from text read), and applies one thing from the Parameter extension, that aParamvalue may carry{searchTerms}for a POST request. - Viewer: the role of a
Queryis judged case-sensitively (our reading of the draft’s list); a role with a declared prefix is accepted without knowing what it means; extended attributes of aQueryare not checked. - Viewer: long
Url,ImageandQuerytables are paged 200 rows at a time with Previous and Next, and none is cut; the Overview says so in a “Long table” row. The strict test reads up to 1 MiB before the root element, past comments, processing instructions and a DOCTYPE.
Unknown
- Reference: the text of the OpenSearch Parameter extension and of the Mozilla search plugin format was not read, so what they require (for example whether
methodmay take values other than GET and POST) is not known here.
Links
Reference
- dewitt/opensearch – the repository of the OpenSearch specification, including the 1.1 Draft 6 text
- MDN: OpenSearch description format – how browsers use the file