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.
OExchange is a simple specification for URL-based content sharing on the web. It defines:
The specification consists of two parts:
This specification is both licensed and versioned.
Intended use-cases for the specification include:
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:
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.
The following terminology is used throughout this document.
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.
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.
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.
For theoffer
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).
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.
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.
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)title
(optional)description
(optional)tags
(optional)ctype
(optional)link
is the default type.The content type is handled as follows:
url
parameter) that uniquely identifies the content to be shared, and is reasonable for navigation by an end userctype
is present, then the offer call will take additional parameters dictated by that type (including potentially additional related URLs)ctype
is not present, the type defaults to "link"ctype
ValuesThe 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).
link
Typelink
is the default ctype, and therefore not required. It indicates that the content is limited to the user-browsable URL provided viaurl
. Again, this URL may itself offer content that includes metadata description of various types (microformats, open graph protocol elements, etc.)
flash
TypeA 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)
iframe
TypeContent 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)
image
TypeA 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
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:
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:
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.Link
element of the relation type http://www.oexchange.org/spec/0.8/rel/offer
, whose href
points to the target's Offer endpoint.Link
element of the relation type icon
, whose href
points to an icon representing the target, designed to be rendered at 16x16 pixels.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.Property
element of type vendor
, whose content provides a human-readable name of the target vendor.Property
element of type title
, whose content provides a human-readable long title for the target.Property
element of type name
, whose content provides a human-readable short name of the target.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.
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>
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.
An Internet host that contains an OExchange Target SHOULD support the following Discovery mechanism, to allow clients to locate Targets by host name alone:
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.
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.
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.
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:
http://hostname/.well-known/host-meta
. Follow standard host-meta rules when doing so.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.http://www.oexchange.org/spec/0.8/rel/offer
relation).
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.
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"/>
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:
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>
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:
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.http://www.oexchange.org/spec/0.8/rel/offer
relation).This indicates that this user uses the Target described by a given XRD document.
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.
This specification document is version 0.8, WORKING DRAFT 7. It may be superseded by future versions.
The following specification documents are referenced directly or indirectly by this specification.