OpenService Format Specification for Accelerators - Version 0.8

  • Article

Accelerator are a contextual service to access and retrieve service information from any Web page. An Accelerator is described using the OpenService Format. Similar to how the OpenSearch Description describes a search provider, the OpenService Format can be used to describe any type of service provider.

  • Description - The service interface that specifies the functionality of a service provider.
  • File - The specific description of a service provider based off of the template for the type of service it provides.

This document covers the minimum properties necessary to enable the publication and consumption of an Accelerator.

  • OpenService Format
  • Accelerator Description
  • Accelerator URL Template
  • Extensibility
  • Licensing Information
  • Revisions

OpenService Format

The OpenService format describes the core set of properties for a service.

Example:

This is an example of how to describe a map Accelerator using the OpenService Format.

<?xml version="1.0" encoding="UTF-8"?>
<openServiceDescription
    xmlns="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <homepageUrl>http://maps.live.com</homepageUrl>
    <display>    
        <name>Map with Windows Live</name>
        <icon>http://www.live.com/favicon.ico</icon>
    </display>
    <activity category="Map">
        <activityAction context="selection" >
            <preview action=" http://maps.live.com/geotager.aspx">
                <parameter name="b" value="{selection}" /> 
                <parameter name="clean" value="true" /> 
                <parameter name="w" value="320" /> 
                <parameter name="h" value="240" /> 
            </preview>
            <execute action=" http://maps.live.com/default.aspx">
                <parameter name="where1" value="{selection}" type="text" /> 
            </execute>
        </activityAction>
    </activity>
</openServiceDescription>

The 'OpenServiceDescription' element

The root node of the OpenService document.

Parent: None

Requirements: The element must appear exactly once as the root node of the document.

Namespace - This namespace defines all of the elements in this specification. https://www.microsoft.com/schemas/openservicedescription/1.0

The 'homepageURL' element

Contains the URL of the homepage of the service provider.

Parent: openServiceDescription

Requirements: There must be only be one instance of this element

The 'display' element

Contains the display properties that are presented to the user.

Parent: openServiceDescription

Requirements: There must be only be one instance of this element

The 'name' element

Contains the name of the service. It should be able to standalone and succinctly describe the service.

It is recommended to lead with the verb followed by the name of the service.

Parent: display

Requirements:

  • There must be only be one instance of this element
  • The value must contain 50 or fewer characters of plain text

Examples:

<name>Map with Windows Live</name>
                        
<name>Define with Encarta</name>

The 'icon' element

Contains a URL that identifies the location of the icon that can be used in association with the service.

Parent: display

Requirements: There can be zero or one instance of this element

Example:

<icon>http://www.live.com/favicon.ico</icon>

The 'description' element

Contains a brief description of the service.

Parent: display

Requirements:

  • There can be zero or one instance of this element
  • The value must contain 250 or fewer characters of plain text

Accelerator Description

This section covers the Accelerator description.

The 'activity' element

Contains the information specific to the Accelerator service.

Parent: openServiceDescription

Requirements: There must be exactly one instance of this element

The 'category' attribute

Contains the type of Accelerator. This is used in conjunction of the domain of the homepageUrl element as the identification of an Accelerator.

Requirements: The value must be plain text.

It is recommended to reuse a category that other similar providers use. For example, all map providers should use the "map" category.

Example:

<activity category="map">

The 'activityAction' element

Contains the information to the specific context.

Parent: activity

Requirements: There must be at least one instance of this element

The 'context' attribute

Contains what the Accelerator should act on: the user selection, the current document, or the selected URL.

Requirements:

  • There may be one instance of this attribute
  • The value must be either "selection", "document", or "link"
  • The default value is "selection"

Example:

<activityAction context="selection">

The 'preview' element

Contains the information for previewing a webpage. The returned content must be HTML that fits within a 320 width x 240 height window.

Parent: activityAction

Requirements: There can be one instance of this element

The 'action' attribute

Contains the URL template to get the webpage to preview the Accelerator. The Accelerator URL Template section contains more detail.

Requirements: There must be one instance of this attribute

The 'method' attribute

Contains the type of HTTP submission for previewing the webpage.

Requirements:

  • There may be one instance of this attribute
  • The value must be either "get" or "post"
  • The default value is "get"

The 'enctype' attribute

Contains the type of content for submitting data to the server as defined by HTML form submission.

Requirements:

  • There may be one instance of this attribute
  • The value must be a supported Form Content Types
  • The default value is "application/x-www-form-urlencoded"

The 'accept-charset' attribute

Contains the character encoding to use for submitting data to server as defined by HTML form submission.

Requirements:

  • There may be one instance of this attribute
  • The value must be a supported charset
  • The default value is "utf-8"

The 'execute' element

Contains the information for executing an Accelerator.

Parent: activityAction

Requirements: There must be one instance of this element

The execute element uses the same set of attributes as the preview element.

The 'parameter' element

Contains the parameter name and values to for the action URL. The parameter value can reference an Accelerator variable. The Accelerator URL Template section contains more detail.

Parent: preview, execute

Requirements: There can zero or one instances of this element

The 'name' attribute

Contains the name of the parameter to use.

Requirements: There must be one instance of this attribute

The 'value' attribute

Contains the value of the parameter to use. The value can reference an Accelerator variable.

Requirements: There must be one instance of this attribute

The 'type' attribute

Contains how to transform the Accelerator variable {selection}.

Requirements:

  • There can be zero or one instance of this attribute
  • The value must be either "text" or "html"
  • The default value is "text"

Example:

<parameter name="body" value="{selection}" type="html" />

Security Warning: If you create an Accelerator that uses a {selection} parameter of type "html", then the service must be explicitly set up to correctly sanitize and handle arbitrary HTML input. Web services that allow arbitrary input without filtering or encoding are susceptible to HTML/script injection attacks. For more information, see the "Selection Types" section of OpenService Accelerators Developer Guide.

Accelerator URL Template

The Accelerator URL template represents content to pass to the service provider. There are two ways to define parameters in a URL template: inline and form-based parameters.

Examples

This is an example of an Accelerator URL template using inline parameter.

<execute action="https://encarta.msn.com/encnet/refpages/search.aspx?q={selection}" />

This is an example of an Accelerator URL template using form-based parameter.

<execute action="https://encarta.msn.com/encnet/refpages/search.aspx">
    <parameter name="q" value="{selection}" type="html" />
</execute>

Variables

Variables are properties within the webpage. Variables are referenced using braces {}.

The {selection} variable Represents the user selection within the webpage.
The {documentUrl} variable Represents the URL of the webpage where the Accelerator is invoked.
The {documentTitle} variable Represents the title of the webpage where the Accelerator is invoked.
The {documentDomain} variable Represents the top-level domain of the documentUrl variable.
The {documentHost} variable Represents the fully qualified domain of the documentUrl variable.
The {link} variable Represents the URL of the user selected URL.
The {linkText} variable Represents the text of the user selected URL.
The {linkRel} variable Represents the relationship of the user selected URL.
The {linkType} variable Represents the MIME type of the user selected URL.
The {linkDomain} variable Represents the top-level domain of the user selected URL.
The {linkHost} variable Represents the fully qualified domain of the user selected URL.

 

Optional variables

All variables are treated as required unless it the modifier "?". An optional variable that cannot be resolved is treated as an empty string for an inline parameterized URL. In a form-based parameterized URL the entire parameter element is ignored.

Example of an optional variable in an inline parameterized URL:

<execute action="https://encarta.msn.com/encnet/refpages/search.aspx?q={selection?}" />

Escape Character

To specify { and } literally, escape them with a backslash \. Backslash can be used to escape any character.

\{{selection}\}

Extensibility

The OpenService format and Accelerator description can be extended through using W3C XML Namespace Spec convention. The XML namespace must be distinct from the OpenService namespace.

Licensing Information

Microsoft's copyrights in this specification are licensed under the Creative Commons Attribution-Share Alike License (version 3.0). To view a copy of this license, please visit http://creativecommons.org/licenses/by-sa/3.0. There is a separate patent promise called the Microsoft Open Specification Promise available to parties interested in implementing software that conforms to this specification. This patent promise is available at this location: https://www.microsoft.com/interop/osp/default.mspx.

Revisions

Version 0.8 (Beta 2)

  • OpenService Activities renamed to OpenService Accelerators
  • Add 'Escape Character' section
  • Fix minor errors

Version 0.8

  • First release