Home » Documentation » Recommendations » OpenSearch and microformats
Contents |
[edit] Notice
This is a draft document for public review.
[edit] Introduction
"Microformats are a set of simple, open data formats built upon existing and widely adopted standards for the purpose of adding machine-readable semantic meaning to human-readable content." (From "About Microformats")
In the same way, OpenSearch is a set of simple, open data formats built upon existing and widely adopted standards for the purpose of sharing search results.
The goals and philosophies of the two initiatives are highly compatible; OpenSearch and microformats can work together in bringing rich data to end users simply and intuitively.
The microformat approach of adding semantic markup to existing and human-readable content works particularly well within the context of search. OpenSearch search engines can return search results in a human-readable XHTML format; thus it is easy to apply a well-defined layer of semantic markup to indicate the underlying meaning of that content.
[edit] Interoperability
Microformats offer a convenient way of adding machine-readable semantic information to human-readable search results. The use of microformats in an OpenSearch context does not preclude the use of alternate techniques.
[edit] Namespaces
All elements, attributes, and parameters in an OpenSearch context must be associated with an XML namespace.
[edit] Microformats with XMDP profiles
If a microformat declares a formal XMDP profile then the XMDP profile URI should be used as the XML namespace name.
[edit] Microformats without XMDP profiles
If a microformat does not declare a formal XMDP profile then the most reasonable homepage URI for the microformat markup should be used as the XML namespace name.
[edit] Example namespaces
Example XML namespaces for common microformats:
xmlns:hcalendar="http://microformats.org/wiki/hcalendar" xmlns:hcard="http://www.w3.org/2006/03/hcard" xmlns:hreview="http://microformats.org/wiki/hreview" xmlns:xfn="http://www.gmpg.org/xfn/11"
[edit] Responses
Microformats can be used in OpenSearch response formats that contain explicitly typed and well-formed markup, such as XHTML text constructs in Atom 1.0. Care must be taken to ensure that the client can reasonably parse and interpret any microformat information, thus microformats can not be reliably used with opaque or unstructured search result content, such as encoded HTML.
[edit] Atom 1.0 Responses
[edit] Elements that can contain microformat markup
Microformat markup can be used in the Atom 1.0 elements classified as text constructs, such as atom:title, atom:subtitle, atom:summary, and atom:content.
[edit] XHTML content
Text construct elements must be of type="xhtml" to be parsed for microformat content.
[edit] Other content
Text construct elements of type="text" and type="html" are considered opaque and can not be parsed for microformat content.
[edit] Resolving ambiguities
If an entry contains both an atom:summary element and an atom:content element then only content of the atom:summary element should be displayed to the end-user. The atom:content element may still be parsed for microformat markup.
[edit] Example Atom 1.0 response
Example Atom 1.0-based OpenSearch response with microformat content:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
<title>Example.com Phonebook Search</title>
<!-- ... -->
<entry>
<title>Jane Smith</title>
<link href="http://example.com/people/jsmith"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<summary type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml" class="vcard">
<div class="n">
<span class="honorific-prefix">Ms.</span>
<span class="given-name">Jane</span>
<span class="family-name">Smith</span>
</div>
<div class="tel">
<span class="type">Work</span>:
<span class="value">(212) 555-0101</span>
</div>
</div>
</summary>
</entry>
</feed>
[edit] RSS 2.0 Responses
Search engines that wish to include semantic markup in OpenSearch results are encouraged to use the Atom 1.0 syndication format instead of RSS 2.0. The description element in RSS 2.0 does not convey enough formal context about the type or encoding of the enclosed content to reliably be used to deliver machine-readable semantic data.
[edit] URL Templates
Microformat class names can be used in OpenSearch URL templates to provide conventional query parameter names.
[edit] Parameter namespaces
All template query parameter in the template must be associated with an XML namespace name via an XML namespace prefix.
[edit] Optional Parameters
The search server can use the "?" flag when requesting a microformat-based parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension.
[edit] Example URL templates
Example of the hCalendar microformat used in an OpenSearch URL template:
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
xmlns:hcalendar="http://microformats.org/wiki/hcalendar">
<Url type="application/atom+xml"
template="http://example.com?q={searchTerms}&start={hcalendar:dtstart?}&end={hcalendar:dtend?}"/>
<!-- ... -->
</OpenSearchDescription>
Example of the hCard microformat used in an OpenSearch URL template:
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
xmlns:hcard="http://www.w3.org/2006/03/hcard">
<Url type="application/atom+xml"
template="http://example.com?q={searchTerms}&address={hcard:adr?}"/>
<Url type="application/atom+xml"
template="http://example.com?q={searchTerms}&zip={hcard:postal-code?}"/>
<!-- ... -->
</OpenSearchDescription>
[edit] Query Elements
Microformat classes can be used as attribute names in OpenSearch Query elements. Each fully qualified attribute name corresponds to a parameter in an OpenSearch URL template.
[edit] Query attribute namespaces
Each attribute in the Query element must be associated with an XML namespace name.
[edit] Example Query elements
Example of microformats in OpenSearch Query elements:
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
xmlns:hcard="http://www.w3.org/2006/03/hcard">
<Url type="application/atom+xml"
template="http://example.com/{searchTerms}?city={hcard:locality?}&state={hcard:region?}&country={hcard:country-name?}&zip={hcard:postal-code?}"/>
<Query role="example" searchTerms="pizza" hcard:postal-code="94117" />
<Query role="example" searchTerms="car dealership" hcard:locality="San Francisco" hcard:region="California" />
<Query role="example" searchTerms="hydroelectric dam" hcard:country-name="United States" />
</OpenSearchDescription>
[edit] Author
DeWitt Clinton <dewitt@opensearch.org>