hobbies & projects. cars, watches, drones, code, whatever.

2 June 2010

A Short Tech Introduction to OExchange

OExchange is an open spec that I've been involved with for a while -- it provides a protocol framework for sharing URL-based content across the web.  You can get more general background on the site, but here's a quick rundown of its actual technical details.  You can also just jump right to the Quick Start Guide if you want to start supporting it. 

OExchange deals with Sources, sites that have content to share, Targets, services that can accept this content (like social networks, translation services, whatever), and Users, people that use these things.  There are three general pieces to the protocol:

1. Content exchange. How does the content actually get from the source to the target?

In what is known as the Offer transaction, sources send targets content by directing the user to a browser-based endpoint that takes the URL as an argument.  For example:


The target site ingests that content in some appropriate way, and messages the user when finished.  The source will have sent the browser there in its own tab.  This simple case is (intentionally) compatible with a huge majority of services deployed live on the web today, and is the minimum compliant OExchange transaction.  There are additional content parameters that the source may pass, and the target may accept, all on an optional basis.  These include things like Flash objects and image URLs.  The key concept is that there is ALWAYS a URL being shared as the primary entity, and that URL may also self-describe in a variety of extensible ways.  Take a look at the Offer specification for all the details on the call. 

2. Service discovery. How do you figure out how a target works, or even that one exists?  How do you integrate with targets you don't know about beforehand?

A target should specify its details, including the location of its Offer URL endpoint, in an XRD document that resides somewhere on the host.  This is just an XML document that uses a set of specific tags, and looks like this:

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


        type="http://www.oexchange.org/spec/0.8/prop/vendor">Examples Inc.</Property>

        type="http://www.oexchange.org/spec/0.8/prop/title">A Link-Accepting Service</Property>


        type="http://www.oexchange.org/spec/0.8/prop/prompt">Send to LinkEater</Property>

        rel= "icon"

        rel= "icon32"

        rel= "http://www.oexchange.org/spec/0.8/rel/offer"


This document has everything you need to communicate with the target.  

To allow the target to be discoverable from the hostname (I know a host, figure out if there is a service there that I can send content to), you can point to the location of the target XRD from your host's host-meta resource (host-meta is a emerging standard for locating information about hosts at well-defined locations), like the one at http://www.oexchange.org/.well-known/host-meta.

Finally, you can add a meta tag to any page related to the service, to allow clients to locate available content services as a user browses.  This works in a manner similar to that used to indicate RSS feeds, and the meta tag will look like this:

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

3. Personal discovery.  How does a user indicate the target services they prefer?  Can all tools honor this across the web?

OExchange proposes a user-centric method whereby individual users can express a preference for particular content services (targets) via a personal XRD file.  This XRD can be discovered theoretically via a variety of means, though OExchange recommends WebFinger as a low-touch method.  In this case, its possible for any intermediate tool, or even a content site, to determine a user's preferred targets by looking up their personal XRD via WebFinger, given only their email address.  Once obtained, the XRD will contain Link elements of a specific type, pointing to the XRD documents that describe the target in question.  

The flow looks like this:

1. Obtain user email address for setup

2. Per the WebFinger protocol, look up the XRD corresponding to that email address

3. Look for the user-target link relation types in this XRD; these correspond to individual target XRDs

4. Look up the target XRD as usual, if its not already been obtained 

The Link element in a personal XRD might look like this, by way of example:

    href="http://www.example.com/linkeater/oexchange.xrd" >

Personally I think this is a great use-case for some of the Personal Discovery ideas being worked on in the open web community. The limitation of this approach, and an area where the group is actively working, is in the lack of deployed support for provisionable personal XRDs.  Google, for example, offers WebFinger for all GMail addresses with a public Google Profile, though not currently a comprehensive way for users or services to edit those XRDs.       


Interested in supporting OExchange, or getting involved in its development?  Take a look at the Quick Start Guide, the actual specification, drop me a comment, join the discussion group, or all of the above. 


tagged: code  technews