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}&amp;start={hcalendar:dtstart?}&amp;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}&amp;address={hcard:adr?}"/>
   <Url type="application/atom+xml"
        template="http://example.com?q={searchTerms}&amp;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?}&amp;state={hcard:region?}&amp;country={hcard:country-name?}&amp;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>

[edit] Further Reading