Creating an OpenSearch Description File in Windows Federated Search

[This documentation is preliminary and is subject to change.]

Describes Windows 7 how to create an OpenSearch Description (.osdx) file to connect external data stores to the Windows Client via the OpenSearch protocol. Federated search allows users to search a remote data store, and view the results from within Microsoft Windows Explorer.

This topic contains the following sections:

• osd/osdx File
  • Mininum Required Child Elements
• Standard Elements for Inclusion
  • Shortname
  • Description
  • Url Template for RSS/Atom Results
  • Url Template for Web Results
  • URL Template Parameters
  • Paged Results
  • Paging Using the Item Index
  • Paging Using the Page Index
  • Page Size
• Extended Elements for Inclusion
  • Maximum Result Count
  • Property Mapping
• Previews
• Open File Location Menu Item
• Additional Resources
• Related Topics

osd/osdx File

An OpenSearch Description (.osd) file for Windows federated search must abide by the following rules:

• Be a valid .osd document, as defined by the OpenSearch 1.1 specification
• Provide a Url template with either an RSS or an Atom format type
• Use the .osdx file extension
• Be associated with the .osdx file extension when downloading from the Web
• Provide a ShortName element value (recommended)

Mininum Required Child Elements

The following sample .osdx file consists of ShortName and Url elements, which are the minimum required child elements.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
        <ShortName>My Web Service</ShortName>
        <Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}&amp;cnt={count}" />
        </OpenSearchDescription>

Standard Elements for Inclusion

In addition to the minimum child elements, Windows federated search supports the following standard elements.

Shortname

Windows uses the ShortName element value to name the .searchconnector-ms (search connector) file that is created when the user opens the .osdx file. Windows ensures that the generated file name uses only characters allowed for Windows file names. If no ShortName value is provided, then the .searchconnector-ms file attempts to use the file name of the .osdx file instead.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
        <ShortName>My Web Service</ShortName>
         ...
        </OpenSearchDescription>

Description

Windows uses the Description element value to populate the file description shown in the Windows Explorer details pane when a user selects a .searchconnector-ms file.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
   ...
   <Description>Searches the example company book catalog</Description>
</OpenSearchDescription>

Url Template for RSS/Atom Results

The .osdx file must include one Url element and template attribute (a Url template) that returns results in either RSS or Atom format. The format attribute must be set to application/rss+xml for RSS formatted results, or application/atom+xml for Atom formatted results.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
   ...
   <Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}&amp;cnt={count}" />
</OpenSearchDescription>

Url Template for Web Results

If there is a version of the search results that can be viewed in a Web browser, then you should provide a Url format="text/html" element, and template attribute.

 <<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
   ...
   <Url format="text/html" template="https://example.com/html.php?query={searchTerms}" />
</OpenSearchDescription>

If you provide a Url format="text/html" element and template attribute, then a button appears in the Windows Explorer command bar that allows the user to open a Web browser to view the search results when the user performs a query.

The roll-over of the query back to the data store's Web UI is important in some scenarios. For example, a user may want to view more than 100 results (the default number of items the OpenSearch provider requests). If so, then the user may also want to use search features only available on the data store's Web site, such as re-querying with a different sort order, or pivoting and filtering the query with related metadata.

URL Template Parameters

The OpenSearch provider performs the following actions:

• Uses the Url template to send the request to the Web service
• Attempts to replace the tokens found in the URL template before sending the request the query to the Web service, as follows:
  • Replaces the standard OpenSearch tokens that are listed in the following table
  • Removes any other tokens found, that are not listed in the following table

Supported Token	How Used by OpenSearch Provider
{searchTerms}	Replaced with the search terms the user types in the Windows Explorer search input box
{startIndex}	Used when getting results in "pages" Replaced with the index for the first result item to return
{startPage}	Used when getting results in "pages" Replaced with the page number of the set of search results to return
{count}	Used when getting results in "pages" Replaced with the number of search results per page that Windows Explorer requests
{language}	Replaced with a string that indicates the language of the query being sent
{inputEncoding}	Replaced with a string (such "UTF-16") that indicates the character encoding of the query being sent
{outputEncoding}	Replaced with a string (such as "UTF-16") that indicates the desired character encoding for the response from the Web service

Paged Results

You may want to limit the number of results returned per request. You can opt to return a "page" of results at a time, or have the OpenSearch provider get additional pages of results either by item number or page number. For example, if you send twenty results per page, the first page you send starts at item index 1 and at page 1; the second page you send starts at item index 21 and at page 2. You can define how you want the OpenSearch provider to request items by either using the {startItem} or the {startPage} token in the URL template.

Paging Using the Item Index

An item index identifies the first result item in a page of results. If you want clients to send requests using an item index, you can use the {startIndex} token in your URL template attribute, as follows:

<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}" />

The OpenSearch provider then replaces the token in the URL with a starting index value. The first request starts with the first item, as shown in the following example:

https://example.com/rss.php?query=frogs&start=1

The OpenSearch provider can get additional items by changing the {startIndex} parameter value and issuing a new request. The provider repeats this process until it gets enough results to satisfy its limit, or reaches the end of the results. The OpenSearch provider looks at the number of items returned by the Web service in the first page of results, and sets the expected page size to that number. It uses that number to increment the {startIndex} value for subsequent requests. For example, if the Web service returns 20 results in the first request, then the provider sets the expected page size to 20. For the next request, the provider replaces {startIndex} with the value of 21 to get the next 20 items.

Note  If a page of results returned by the Web service has fewer items than the expected page size, then the OpenSearch provider assumes it has received the last page of results and stops making requests.

Paging Using the Page Index

A page index identifies the specified page of results. If you want clients to send requests using a page number, you can use the {startPage} token in your URL element template attribute, as follows:

<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&amp;page={startPage}" />

The OpenSearch provider then replaces the token in the URL with a page number parameter. The first request starts with the first page, as shown in the following example:

https://example.com/rss.php?query=frogs&page=1

Note  If a page of results returned by the Web service has fewer items than the expected page size, then the OpenSearch provider assumes it has received the last page of results and stops making requests.

Page Size

You may want to configure your Web service to permit a request to specify the size of the pages using some parameter in the URL. A request must be specified in the .osdx file using the {count} token, as follows:

<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}&amp;cnt={count}" />

The OpenSearch provider can then set the desired page size, in terms of number of results per page, as shown in the following example:

https://example.com/rss.php?query=frogs&start=1&cnt=50

By default the OpenSearch provider makes requests using a page size of 50. If you want a different page size, then do not provide a {count} token, and instead place the desired number directly in the URL template.

The OpenSearch provider determines the page size based on the number of results returned on the first request. If the first page of results received has fewer items than the count requested, then the provider resets the page size for any subsequent page requests. If subsequent page requests return fewer items, then the OpenSearch provider assumes that it has reached the end of the results.

Extended Elements for Inclusion

In addition to the standard elements, Windows federated search supports the following extended elements:

• MaximumResultCount
• ResultsProcessing

Because these extended child elements are not supported in the OpenSearch v1.1 specification, they must be added using this namespace:

https://schemas.microsoft.com/opensearchext/2009/

Maximum Result Count

By default Search Connectors only get up to 100 results for any given user query. This limit can be customized by including the MaximumResultCount element within the OSD file as shown in the following example:

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/" xmlns:ms-ose="https://schemas.microsoft.com/opensearchext/2009/">
        ...
        <ms-ose:MaximumResultCount>200</ms-ose:MaximumResultCount>
        </OpenSearchDescription>

The above example declares the namespace prefix ms-ose in the top-level OpenSearch Description element, and then uses it to prefix the element name. This declaration is mandatory because MaximumResultCount is not supported in the OpenSearch v1.1 specification.

Property Mapping

When results are returned by the Web service as an RSS or Atom feed, the OpenSearch provider must map the item metadata in the feeds to properties that the Windows Shell can use. The following figure illustrates how the OpenSearch provider maps some of the default RSS elements.

Default Mappings

The default mappings of RSS XML elements to Windows Shell system properties, are listed in the following table. XML paths are relative to the item element. The "media:" prefix is defined by the Yahoo Search Namespace  namespace.

RSS XML Path	Windows Shell Property (Canonical Name)
Link	System.ItemUrl
Title	System.ItemName
Author	System.Author
pubDate	System.DateModified
Description	System.AutoSummary
Category	System.Keywords
enclosure/@type	System.MIMEType
enclosure/@length	System.Size
enclosure/@url	System.ContentUrl
media:category	System.Keywords
media:content/@fileSize	System.Size
media:content/@type	System.MIMEType
media:content/@url	System.ContentUrl
media:group/content/@fileSize	System.Size
media:group/content/@type	System.MIMEType
media:group/content/@url	System.ContentUrl
media:thumbnail/@url	System.ItemThumbnailUrl

 

Note  In addition to the default mappings of standard RSS or Atom elements, you can map other Windows Shell system properties by including additional XML elements in the Windows namespace for each of the properties. You can also map elements from other existing XML namespaces such as MediaRSS, Itunes, and so forth, by adding custom property mapping in the .osdx file.

Automatic Windows Shell Property Mappings

You can choose to include other XML elements within the items in your RSS feed that automatically map to Windows Shell system properties. To do so, include an element named after the Windows Shell property and prefixed with the Windows Shell system namespace. The following example illustrated the namespace declaration win=" https://schemas.microsoft.com/windows/2008/propertynamespace", and the inclusion of an element for the property mapping win:System.Contact.PrimaryEmailAddress:

<rss version="2.0" xmlns:example="https://example.com/schema/2009" xmlns:win="https://schemas.microsoft.com/windows/2008/propertynamespace">
...
   <item>
      <title>Bill Gates</title>
      <win:System.Contact.PrimaryEmailAddress>billg@microsoft.com
   </win:System.Contact.PrimaryEmailAddress>
   </item>

The namespace prefix used here ("win") is a suggestion; you can use any prefix. However, you must use the exact Windows Shell property names, and must include the exact URI:

https://schemas.microsoft.com/windows/2008/propertynamespace

About Windows Shell System Properties

There is a complete list of System Properties defined in Windows, and the value type format required for each property. The documentation for the System.FileExtension Window Shell property, for example, specifies that the value must contain the leading period (".docx" and not "docx").

Date and Time Values

The preferred date and time format is ISO-8601, for example:

2008-01-16T 19:20:30:.45+01:00

.NET developers should use the DateTime class with ToString("R")to output the correct format.

Custom Property Mappings

You can customize the mapping of elements from your RSS output to Windows Shell system properties by specifying the mapping in the .osdx file.

The RSS output specifies:

• An XML namespace, and
• For any child element of an item, an element name to map against

The .osdx file identifies a Windows Shell property for each element name in a namespace. The property mappings that you define in your .osdx file override the default mappings, if they exist, for those specified properties.

Example RSS results and OSD Property Mapping

This example RSS output identifies https://example.com/schema/2009 as the XML namespace with the prefix example. This prefix must appear again before the element email.

<rss version="2.0" xmlns:example="https://example.com/schema/2009">
...
   <item>
      <title>Bill Gates</title>
      <example:email>billg@microsoft.com</example:email>
   </item>

In the following sample .osdx file the XML element email maps to the Windows Shell property System.Contact.EmailAddress.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/" xmlns:ms-ose="https://schemas.microsoft.com/opensearchext/2009/">
...
 <ms-ose:ResultsProcessing format="application/rss+xml">
   <ms-ose:PropertyMapList>
     <ms-ose:PropertyMap sourceNamespaceURI="https://example.com/schema/2009/" >
       <ms-ose:Source path="email">
         <ms-ose:Property schema="https://schemas.microsoft.com/windows/2008/propertynamespace" name="System.Contact.EmailAddress" />
       </ms-ose:Source>
     </ms-ose:PropertyMap>
   </ms-ose:PropertyMapList>
 </ms-ose:ResultsProcessing>
...
</OpenSearchDescription>

There are some properties that cannot be mapped because values for them are either overridden later or not edit able. For example System.ItemFolderPathDisplay or System.ItemPathDisplayNarrow cannot be mapped because they are calculated from the URL value provided in either the link or enclosure elements.

Thumbnails

Thumbnail image URLs may be provided for any item using the media:thumbnail url="" element. The ideal resolution is 150x150 pixels. The largest thumbnails supported are 256x256 pixels. Providing larger images takes more bandwidth for no extra benefit to the user.

Open File Location Context Menu

Windows provides a shortcut menu named Open file location for result items. If the user selects that menu item, the "parent" URL for the selected item is opened. If the URL is a Web URL, such as https://..., such as the Web browser is opened and navigated to that URL. Your feed should provide a custom URL for each item to ensure that Windows opens a valid URL. This can be accomplished by including the URL within an element inside the item's XML, as illustrated in the following example:

<rss version="2.0" xmlns:example="https://example.com/schema/2009" xmlns:win="https://schemas.microsoft.com/windows/2008/propertynamespace">
...
   <item>
      <title>Bill Gates</title>
      <link>https://example.com/pictures.aspx?id=01</link>
      <win:System.ItemFolderPathDisplay>https://example.com/pictures_list.aspx
   </win:System.ItemFolderPathDisplay>
   </item>
...

If this property is not explicitly set in the item's XML, then the OpenSearch provider sets it to the parent folder of the URL of the item. In the example above, the OpenSearch provider would have used the link value, and set the System.ItemFolderPathDisplay Windows Shell property value to "https://example.com/".

Customize Windows Explorer Views with Property Description Lists

Some Windows Explorer view layouts are defined by property description lists, or proplists. A proplist is a semicolon-delimited list of properties, such as "prop:System.ItemName; System.Author", that is used to control how your results appear in Windows Explorer.

The UI areas of Windows Explorer that can be customized using proplists are illustrated in the following figure:

Each area of Windows Explorer has an associated set of proplists, which themselves are specified as properties. You can specify custom proplists for individual items in your result sets or for all items in a set of results.

UI Area to Customize	Windows Shell property that Implements the Customization
Content view mode (when searching)	System.Proplist.ContentViewModeForSearch
Content view mode (when browsing)	System.Proplist.ContentViewModeForBrowse
Tile view mode	System.Proplist.TileInfo
Details pane	System.Proplist.PreviewDetails
Infotip (item's hover tool tip)	System.Proplist.Infotip

 

To specify a unique proplist for an individual item:

1. In your RSS output, add a custom element representing the proplist you want to customize. For example, this sample sets the list for the details pane:

   <win:System.Proplist.PreviewDetails>prop:System.ItemName;System.Author</win:System.Proplist.PreviewDetails>
   

2. To apply a property to every item in the search results without modifying the RSS output, specify a proplist within a ms-ose:PropertyDefaultValues element in the .osdx file:

     <ms-ose:ResultsProcessing format="application/rss+xml">
       <ms-ose:PropertyDefaultValues>
         <ms-ose:Property schema="https://schemas.microsoft.com/windows/2008/propertynamespace" name="System.PropList.ContentViewModeForSearch">prop:~System.ItemNameDisplay;System.Photo.DateTaken;~System.ItemPathDisplay;~System.Search.AutoSummary;System.Size;System.Author;System.Keywords</ms-ose:Property>
       </ms-ose:PropertyDefaultValues>
     </ms-ose:ResultsProcessing>
   

Content View Mode Layout of Properties

The list of properties specified in the System.Proplist.ContentViewModeForSearch and System.Proplist.ContentViewModeForBrowse proplists determines what is shown in Content view mode. For more information about property lists, see PropList.

The properties are laid out according to the numbers shown in the following layout pattern:

If we use the following list of properties,

prop:~System.ItemNameDisplay;System.Author;System.ItemPathDisplay;~System.Search.AutoSummary;System.Size;System.Photo.DateTaken;System.Keywords

Then we see the following display:

Note  For the best readability, the properties shown in the right-most column should be labeled.

Property List Flags

Only one of the flags defined in the proplists documentation applies to the display of items in Content View mode layouts:"~". In the previous examples, the Explorer view labels some of the properties, such as Tags: animals; zoo; lion. That is the default behavior when you specify a property in the list. For example, the proplist has "System.Author" which is displayed formatted as "Authors: value". When you want to hide the property label, place a "~" in front of the property name. For example, if the proplist has "~System.Size", the property is displayed as just a value, and without the label.

Previews

When the user selects a result item in Windows Explorer and the preview pane is open, the content of the item is previewed.

The content to show in the preview is specified by a URL, which is determined as follows:

• If the System.WebPreviewUrl Windows Shell property is set for the item, then use that URL. Note   The property needs to be provided in the RSS using the Windows Shell namespace, or explicitly mapped in the .osdx file.
• If not, then use the link URL instead.

It is possible to use a different URL for the preview than for the item itself. This means that if you provide different URLs for the link URL, and the enclosure or media:content URL, Windows Explorer uses the link URL for previews of the item but uses the other URL for file type detection, opening, downloading, and so forth.

How Windows Explorer determines what URL to use:

• If you provide a mapping to System.ItemFolderPathDisplay, then Windows Explorer uses that URL
• If you do not provide a mapping, then Windows Explorer identifies whether the link and enclosure URLs are different. If so, then Windows Explorer uses the link URL.
• If the URLs are the same or if there is only a link URL, then Windows Explorer parses the link to find the parent container by removing the filename from the full URL. Note  If you recognize that the URL parsing would result in dead links for your service, you should provide an explicit mapping for the property.

Open File Location Menu Item

When users right-click an item, the Open file location menu option appears. This command takes the user to the container for or location of that item. For example, on a SharePoint search, selecting this option for a file in a document library would open the document library root in the Web browser.

When a user clicks Open file location Windows Explorer attempts to find a parent container, as follows:

Additional Resources

• For a demonstration of how to create an OpenSearch Web service for a SQL database, see the Windows 7: Empower Users to Find, Visualize and Organize their Data with Libraries and the Explorer  video presentation given at PDC (October 2008).
• For information on Windows system-defined properties, see System-Defined Properties for Custom File Formats.
• For information on Windows Shell system properties, see System Properties.
• SharePoint Search Server 2008 and MOSS 2007 SP2 also support federated search of remote servers using OpenSearch. For more information about federated search and Search Server 2008 deployment with Office SharePoint Server 2007, see Welcome to Microsoft Search Server 2008.
• See the Microsoft Download Center Web site for the following downloadable resources:
  • Windows 7 Federated Search Provider Implementer's Guide
  • Search Server 2008 Sample: Federated Search Connector Sample
• For more information about the OpenSearch standard, see the OpenSearch  Web site.

Related Topics

• Federated Search in Windows
• Connecting Your Web Service in Windows Federated Search
• Enabling Your Data Store in Windows Federated Search
• Deploying Search Connectors in Windows Federated Search
• Overview of the Search Connector Description Schema
• Extending the Index