Technical Specification

Abstract

This document describes OExchange, a simple specification for URL-based content sharing on the web. OExchange codifies an existing model in wide use today, adds a dynamic discovery capability, and creates a foundation for additional verbs.

This is the technical specification. The Quick Start Guide provides a short introduction to the protocol and its practical implementation.



Table of Contents



1. Introduction

OExchange is a simple specification for URL-based content sharing on the web. It defines:

  • An endpoint at which a service on the web can receive links and related rich content on behalf of a user
  • A specific flow for how the sending and receiving services interact with each other and with the user during this exchange
  • Several mechanisms for discovering the existence and capabilities of a service that can perform this type of exchange

The specification consists of two parts:

This specification is both licensed and versioned.


1.1 Motivation

Intended use-cases for the specification include:

  • Post a link to followers on a stream or microblogging platform
  • Send a page to a content service like a translator or spell-check
  • Add a link to a personal bookmarking service
  • Post a video or photo to a media-blogging platform

Generally, any operation that involves sending URL-based content from one service to another, with a user mediating the transaction, is addressed. Special focus is given to the fact that all the possible services a user will want to push their content to cannot be known a-priori.

This specification takes the following general approach:

  • Codify the link-sharing mechanism and user experience in wide use today, providing a structured but compatible recommendation
  • Define a discovery component on top of the core exchange mechanism, supporting dynamic integration between services
  • Add advanced features only on top of a core layer of defined interoperability and practical deployment

1.2. Document Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.


1.3. Definitions & Terminology

The following terminology is used throughout this document.

Source
A website or application that has content to be shared or offered to a Target.

Target
A website or application that can receive content offered from a Source.

User
A real-world user that interacts with Source and Target websites and applications.


2. OExchange-Offer


2.1. The Endpoint

The Offer verb is the core of the sharing transaction within OExchange. A target must implement a simple URL endpoint on which other applications can send it web content. For example: 

http://www.example.com/share.php?url={URI}

Or, illustrating the use of several additional optional parameters: 

http://www.example.com/share.php?url={URI}&title={title for the content}&description={short description of the content}&ctype=flash&swfurl={SWF URI}&height={preferred SWF height}&width={preferred swf width}&screenshot={screenshot URI}

The specific form of the endpoint is: 

http://{host}/{arbitrary offer endpoint name}?url={URI}&ctype={type}&{type-specific arguments}

It defines one required parameter, url, which represents the url to be offered. There are a small number of additional parameters, such as title, that apply at this level. There is also an optional parameter, ctype, which indicates additional optional detail about the type of content to share. The presence and value of this parameter specifies additional optional parameters, specific to this type.

Note that the offer verb MAY be implemented at any URL the site chooses, as long as it is known to sources. In the general form above, the "endpoint" is: 

http://www.example.com/services/oexchange/offer

Alternatively, a site could implement an endpoint at a url like this instead: 

http://www.example.com/offer.php?url={URI}

...or even something like... 

http://www.example.com/offer/?url={URI}

This flexibility is allowed so that implementing Targets do not have substantial work to do to modify their web stacks to deal with different or missing file extensions, trailing slashes, or the like. It is simply required that sources know (perhaps via OExchange-Discovery) the full endpoint such that they can pass arguments to it appropriately.


2.2. The Offer Flow

The offer endpoint accepts requests from a user's browser, not from a backend. When a Source site wishes to share content with a Target, it sends the user's browser to this well-defined endpoint via an HTTP GET with appropriately URL-encoded parameters. The Target then takes over the control flow for the remainder of the transaction.

This model allows the target site and its users to fully participate in the sharing transaction. The Target is responsible for ingesting the provided content in a manner intrinsic to the service it offers (e.g. translate it, post it to a microblog), providing feedback to the user, and leaving the user at a site-appropriate completion point.

2.2.1. User Experience Implications
The Target endpoint is designed to be a complete browsing experience for the user. A Source may send the user to the Target and lose control itself, but it may also use a target _blank link. OExchange does not impose a restriction on the Target of having to return to the Source when the transaction is complete.
2.2.2. Handling Errors
For the offer verb, the exchange happens in the user's browser, so all errors that occur within the target site must be handled gracefully in a way that the end user sees and understands.

In practice, since there is no type negotiation and URLs are always required, there should not be any mismatch error condition; assuming a source forms a valid offer call, any target will be capable of accepting it (at the protocol level).
2.2.3. Authentication, Security, and the Offer Flow
The Target and Source are each responsible for their own authentication and access control. That is, OExchange does not define or require any additional security layer on top of the exchange transaction. Typically, a Target that requires an authentication and/or authorization step before ingesting content will perform that step at the beginning of its handling of the Offer. This allows the AA layer to exist independent of the offer transaction and specification, and for the Source and Target to employ whatever means they have deemed appropriate for their user interactions.

OExchange does specify that targets MUST NOT require their offer endpoints to be HTTPS URLs. Though this does prevent certain real-world scenarios, it also prevents interoperability problems caused by variability between sites. A Target may certainly redirect from HTTP to HTTPS URLs as desired once the offer flow is initiated.

2.3. OExchange Data Typing

All Offer transactions MUST include a URL. The URL is the core of the transaction; it is the thing being posted, shared, exchanged, translated, or otherwise operated on. The ctype type parameter defines a mechanism to specify additional rich content, such as an image, but this is as an extension to the basic Offer flow, not a specialization of it. All parties should assume that the core URL is something that a user can and will navigate to directly, if they choose.

For example, a user might be on a photo site and want to copy an image to an online web-cliping service they use. The URL will most likely be of the photo site's photo page, and the actual image data would be specified through an image ctype and related parameters (such as the URL of the actual image). Similarly, a video page (the primary url) and an associated flash video player (the url of the SWF, and some additional attributes) could be shared. If the target chooses to look for and take special action on the video player, such as embedding it into a user feed, it may, but targets that only absorb urls are unaffected and will still offer a reasonable experience.

It is key that it is always possible to conduct a simplest-case transaction between any OExchange compliant entities, regardless of whatever rich type-specific logic they may support. OExchange adopts this "we're always sharing a link, if you can do more with it, great!" practice as opposed to a (complex) type-negotiation system, whether dynamic or at build time.

Note that it is fully expected that URLs will increasingly contain microformat, open graph protocol, RDFa, and other meta information via appropriate specifications and channels. Targets are free to inspect for these as they would any URL.


2.4. Offer Parameter Details

The Offer endpoint accepts several parameters, only one of which, url, is required. All parameters must be properly URL-encoded. The following parameters are common across all content types:

url (required)
The URL of the content being offered. It should be expected that this URL is something a user could navigate to directly in a browser.

title (optional)
A human-readable title for the content. This is typically equivalent to the page"s title meta tag, and is used to convey the same type of information.

description (optional)
A human-readable description of the content. This is typically equivalent to the page"s description meta tag, and is used to convey the same type of information.

tags (optional)
A set of comma-delimited "tags" that further describe the content. The meaning of tags is determined by the target, but a target should not heavily overload the meaning of tags beyond the generally accepted one: text strings used by users to assist in organizing content. This parameter is a CSV-format string obeying the rules for line content from RFC 4180. Specifically, a list of comma-separated values with no trailing comma. Values with commas in them must be placed in double quotes (e.g. foo, bar, "Miami, FL").

ctype (optional)
Additional information on the type of content being shared. See the list of supported ctypes; link is the default type.

The content type is handled as follows:

  • An offer MUST include a URL (via the url parameter) that uniquely identifies the content to be shared, and is reasonable for navigation by an end user
  • The offer MAY include additional type information for that content
  • If a ctype is present, then the offer call will take additional parameters dictated by that type (including potentially additional related URLs)
  • If a ctype is not present, the type defaults to "link"

2.5. Supported ctype Values

The set of possible ctypes is finite, and defined by this specification.

Valid ctypes, and the specific additional arguments appropriate for each type, are described in the following sections (the general parameters are valid for all types).

2.5.1. The link Type
link is the default ctype, and therefore not required. It indicates that the content is limited to the user-browsable URL provided via url. Again, this URL may itself offer content that includes metadata description of various types (microformats, open graph protocol elements, etc.)
2.5.2. The flash Type
A Flash movie element which can be directly embedded by the target. This type supports the following specific parameters:
swfurl
The URL of the actual SWF resource, with appropriate parameters as necessary

height
The preferred height of the content (which the Target can use to render the tag)

width
The preferred width of the content (which the Target can use to render the tag)

screenshot
The URI of an image representation of the Flash content. The image should be suitable for display the same size as the Flash object (as specified by height and width parameters)
2.5.3. The iframe Type
Content that can be embedded by a target by including an HTML iframe sourced to a specified URL. This type supports the following specific parameters:
iframeurl
The URL to be used as the actual iframe of the actual SWF resource, with appropriate parameters as necessary

height
The preferred height of the content (which the Target can use to render the iframe)

width
The preferred width of the content (which the Target can use to render the iframe)

screenshot
The URI of an image representation of the iframe content. The image should be suitable for display the same size as the iframe object (as specified by height and width parameters)
2.5.4. The image Type
A simple web-renderable image. This type supports the following specific parameters:
imageurl
The URL that is the source of the image

height
The preferred height of the image

width
The preferred width of the image


3. OExchange-Discovery


3.1 Discovery Overview

OExchange-Discovery defines a manner in which clients can discover information about OExchange Targets dynamically, at run-time. The specification defines four elements, with related technical solutions:

  • Target specification: how to specify the details of a particular Target, including the location of its Offer endpoint
  • Host discovery: how to identify OExchange Targets available at a given host
  • Page discovery: how to identify OExchange Targets suggested by a web page
  • Personal discovery: how to identify OExchange Targets appropriate for an individual user


3.2 Target Specification via the OExchange Target XRD

Each target must be defined in an individual XRD file. OExchange leverages standard XRD elements to convey all information. The XRD is defined as follows:

  • The Subject of the document must be a navigable URL representation of the Target. This is used to globally and uniquely identify the Target, as well as to send users for reference as required.
  • There must be a Link element of the relation type http://www.oexchange.org/spec/0.8/rel/offer, whose href points to the target's Offer endpoint.
  • There should be a Link element of the relation type icon, whose href points to an icon representing the target, designed to be rendered at 16x16 pixels.
  • There may be a Link element of the relation type icon32, whose href points to an icon representing the target, designed to be rendered at larger sizes, most typically 32x32.
  • There must be a Property element of type vendor, whose content provides a human-readable name of the target vendor.
  • There must be a Property element of type title, whose content provides a human-readable long title for the target.
  • There must be a Property element of type name, whose content provides a human-readable short name of the target.
  • There must be a Property element of type prompt, whose content provides a human-readable call to action for sending links to this target.

The Target XRD file may live at any location on a host, but SHOULD remain consistent over time. Clients may refer to this XRD directly as the definitive source for Target metadata. In addition, Host Discovery can be used to look up the location of the Target's XRD document.

3.2.1 Example Target XRD

An example of a target XRD file: 

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
        
    <Subject>http://www.example.com/linkeater</Subject>

    <Property 
        type="http://www.oexchange.org/spec/0.8/prop/vendor">Examples Inc.</Property>
    <Property 
        type="http://www.oexchange.org/spec/0.8/prop/title">A Link-Accepting Service</Property>
    <Property 
        type="http://www.oexchange.org/spec/0.8/prop/name">LinkEater</Property>
    <Property 
        type="http://www.oexchange.org/spec/0.8/prop/prompt">Send to LinkEater</Property>

    <Link 
        rel= "icon" 
        href="http://www.example.com/favicon.ico"
        type="image/vnd.microsoft.icon" 
        />

    <Link 
        rel= "icon32" 
        href="http://www.example.com/favicon32.png"
        type="image/png" 
        />

    <Link 
        rel= "http://www.oexchange.org/spec/0.8/rel/offer" 
        href="http://www.example.com/linkeater/offer.php"
        type="text/html" 
        />
</XRD>

3.2.2 Internationalization of the Target XRD

The Target XRD contains strings intended for display to users. In some cases the target may wish to express these strings, such as the action prompt, in various languages. This is supported through the use of the standard xml:lang attribute, which can be included as an attribute on the associated Property element.

Multiple instances of the particular Property element may be included, each with a unique language indicator. In such cases, there MUST be one of each element with no lang attribute, indicating the "default", and this element SHOULD be the first such element in the XRD to simplify default parsing.

This attribute is intended to be used in standard fashion, with values corresponding to RFC 4646.


3.3 Host Discovery

An Internet host that contains an OExchange Target SHOULD support the following Discovery mechanism, to allow clients to locate Targets by host name alone:

  • For each Target, there MUST be an individual Target XRD file that describes its OExchange-related capabilities. Again, this document can technically live anywhere on the host.
  • The host must include a reference to the target XRD(s) inside its .well-known/host-meta XRD document.

When a client wishes to discover available OExchange targets on a given host, it looks up the .well-known/host-meta resource, parses for referenced XRDs for each target, then loads those XRD documents to determine the details of each target, including their Offer endpoints.

3.3.1 The /.well-known/host-meta Document

The /.well-known/host-meta resource is an XRD document that describes services available on the host (as defined here), and is available via simple HTTP request. If the host does not already contain such a resource for other purposes, this is an opportunity to create one.

3.3.1.1 The resident-target Relation

Within host-meta, OExchange targets are identified withLink elements of the http://oexchange.org/spec/0.8/rel/resident-target relation type. The href attribute of the relation must be the location of the target-specific XRD descriptor.

3.3.1.2 Example host-meta XRD

An example of the relevant Link element required within a host-meta resource to identify the location of a target's XRD descriptor: 

<Link 
    rel="http://oexchange.org/spec/0.8/rel/resident-target" 
    type="application/xrd+xml"
    href="http://www.example.com/linkeater/oexchange.xrd" >
</Link>

A complete host-meta resource, therefore, might look like the following: 

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0' 
    xmlns:hm='http://host-meta.net/xrd/1.0'>
    <hm:Host>www.example.com</hm:Host>

    <Link 
        rel="http://oexchange.org/spec/0.8/rel/resident-target" 
        type="application/xrd+xml"
        href="http://www.example.com/linkeater/oexchange.xrd" >
    </Link>

</XRD>

3.3.2 Detailed Target Discovery Flow

The exact flow of a client attempting to discover OExchange compatibility of a given host must be:

  1. Request the host's host-meta resource, following redirects as necessary, at http://hostname/.well-known/host-meta. Follow standard host-meta rules when doing so.
  2. Look for any Link elements that use the http://oexchange.org/spec/0.8/rel/resident-target relation type. Each such Link's href is the location of a specific target's XRD document.
  3. Request each Target's XRD document.
  4. Inspect the XRD, obtaining metadata about the target, including its offer endpoint (a Link with a http://www.oexchange.org/spec/0.8/rel/offer relation).

3.4 Page Discovery

It is possible for a web page to suggest to a user agent that a related Target is available. For example, the pages of a social networking site might include references to a Target that allows users to post content into that network. Pages do this by including an HTML/XHTML link tag that points to the XRD for a related target. The presence of this tag indicates to the user agent that there is a Target related to this content, and where to locate the XRD document that describes that Target in detail.

3.4.1 Link Elements and the related-target Relation Type

Link elements of relation type http://oexchange.org/spec/0.8/rel/related-target point, via their href attribute, to the XRD document of the Target that is related to the page on which the Link is located.

For example, a link tag like the following may appear in the head of the page: 

<link rel="http://oexchange.org/spec/0.8/rel/related-target" type="application/xrd+xml" href="http://www.example.com/linkeater/oexchange.xrd"/>


3.5 Personal Discovery

PROPOSED METHOD

Tools that facilitate end-user sharing and link-sending require a means to provide a personalization mechanism. Presenting the user with too many options, or with options that are not appropriate to them (commonly referred to as "the Nascar problem"), significantly reduces their use in general. This problem increases dramatically if services are able to, via OExchange Discovery mechanisms, dynamically make themselves available without any prior integration. This specification approaches this problem in two parts:

  • Temporal, single-machine user state: the notion of which services, in which priority order, a user is engaged with at any given moment. This is typically handled through tool-specific implementations, and potentially moving forward with shared-storage approaches such as XAuth. Depending on the specific means used, OExchange integrates in different ways. With a shared-storage, hostname-based model such as that used by XAuth, for example, the hostnames reported can be used in a Host Discovery flow and be treated as formal Targets.
  • Long-term public expression of a user's "preferred" services: the idea that a user should be able to express, in a public way, the services that they use on the web, to encourage sources and sharing tools to prioritize those on their behalf. OExchange proposes that this occur via a user's personal XRD. The personal XRD can be obtained via WebFinger and potentially other means.

3.5.1 Personal XRDs and the user-target Relation Type

To indicate a preference for certain OExchange Targets, a user's personal XRD should include a Link element of the http://oexchange.org/spec/0.8/rel/user-target relation type. The href attribute of this link MUST be the location of the Target's XRD resource.

For example, an individual XRD may contain the following Link element: 

<Link 
    rel="http://oexchange.org/spec/0.8/rel/user-target" 
    type="application/xrd+xml"
    href="http://www.example.com/linkeater/oexchange.xrd" >
</Link>

3.5.2 Example Personal Discovery Flow: WebFinger

As an example, WebFinger can be used to locate a personal XRD, which expresses the users preferred OExchange services. The exact flow in this case is as follows:

  1. Per WebFinger protocol, look up the individual XRD of a user given their email address.
  2. Look for any Link elements that use the http://oexchange.org/spec/0.8/rel/user-target relation type. Each such Link's href is the location of a specific target's XRD document.
  3. Request each Target's XRD document.
  4. Inspect the XRD, obtaining metadata about the target, including its offer endpoint (a Link with a http://www.oexchange.org/spec/0.8/rel/offer relation).

This indicates that this user uses the Target described by a given XRD document.



4. Licensing

This specification is made available under the Open Web Foundation Agreement, Version 0.9.

Your use of this Specification may be subject to other third party rights. THIS SPECIFICATION IS PROVIDED "AS IS." The contributors expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the Specification. The entire risk as to implementing or otherwise using the Specification is assumed by the Specification implementer and user. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS SPECIFICATION OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



5. Document Status

This specification document is version 0.8, WORKING DRAFT 7. It may be superseded by future versions.


5.1. Revision History

  • 2008-05-01: original concept draft created
  • 2008-05-26: added gadget and opensocial types
  • 2008-06-14: added embed-raw type
  • 2008-12-07: minor changes per second round implementor review
  • 2009-4-20: prepped for additional "open" feedback
  • 2009-6-12: major update per aggregated feedback, primarily simplifying the typing mechanism
  • 2009-9-1: pinned version at 0.8 WD 1 for concrete implementors
  • 2010-2-1: removal of oexchange-link and inclusion of oexchange-discovery via host-meta and xrd
  • 2010-3-1: added finalized discovery specification
  • 2010-3-4: misc textual clarifications on ctype handling
  • 2010-4-16: added agreed-to personal and page discovery methods
  • 2010-4-23: added icon32 image link
  • 2010-4-23: published WD 5
  • 2010-5-3: promoted "tags" parameter, clarified encoding rules; updated reference; clarified use of xml:lang for localization; formalized OWFa licensing
  • 2010-5-6: published WD 6
  • 2010-5-12: reformatted introductory content; updated for new site styling;
  • 2010-5-14: published as WD 7


6. Related & Background

The following specification documents are referenced directly or indirectly by this specification.