RFC: Really Simple Discoverability 1.0

This version of the RSD specification contains modifications in order to make the document self contained, such as including the example. Nothing else has been altered from the original. This pointer must remain in any copies of this document. Thanks --Daniel 08/11/2003

Thu, Oct 31, 2002; by Daniel Berlinger

Really Simple Discovery is a way to help client software find the services needed to read, edit, or "work with" weblogging software. Although I talk about weblogging software, there's no reason this format can't apply to other forms of web client/system software that I wasn't considering, or may not even exist as of this writing. (There is an example below where I did just that.) This format is simple but flexible. One of the deisgn goals was to ensure that it would be human writeable. This was my "test" for ensuring that the format was easy for everyone to implement.

The goal is simple. To reduce the information required to UserName, Password, and homepage URL.

Hopefully, it'll work for you.

Daniel

PS For early adopters there is a BDG for moving from 0.6 to 1.0. Thanks for jumping in.

The Problem

The number one customer service issue I've had with "Archipelago" is settings for services. Specifically, the "Path To Service" setting, but more generally where to point for services.

"I'm afraid I could not get very far with Archipelago. The download and install was fine, but I'm not sure what to set for the rest. I have my account with blogger (that I use now) and the site itself is hosted somewhere else. Both of these have different names and passwords. What do I do?"

The solution I propose below will simplify the discovery of settings information by reducing the information a user must supply to three well known elements. Assuming that the RSD file is generated by the blogging software (Radio, Manila, Moveable Type, SnipSnap, Conversant, Drupal, etc.) the other required bits of information not well known to the user can be easliy discovered and supplied.

Examples of difference

Blogger has "plant.blogger.com", "api/RPC2", and the blogID. The "Path to Service is case sensitive. If a user enters "/api/rpc2" in their preferences they get an error in html, courtesy of Tomcat, that states "The requested resource (/rpc2) is not available.". The error message is subject to change in format. This same problem could apply to every case. Moveable Type uses an endpoint of "mt/mt-xmlrpc.cgi", and the domain level of the URL depends on the installation. The site identifier is the blogID number. Manila and Radio use "rpc2", case insensitive. Manila's domain level URL depends on the installation but it does provide the "sitename" through the ManilaRPC API. Whew! Radio has a consistent siteID (as of this writing). Conversant has its own API plus support for basic Blogger API. It uses x|x|x identifier where the various flexible elements of Conversant are "x". Familiarity with Conversant is somewhat required. These elements are also required when specifiying a message, so you need a message "number" that looks like this x|x|x|123. Path to service is rpc2, and case insensitive (not tested). As you can imagine, plenty of folks have struggled to get this information exactly correct for each case. Anything that helps automate the process or gives users up to date information on the specific service their employing would help mitigate this difficulty.

RSD

I'd think that something simple, like an xml document that lists the critical info would be about right. It should be simple enough to be written by hand. I'm calling this document "Really Simple Discoverability". I want to address the needs of blogging software, not be terribly general at first, and leave room for growth. I hope the RSS and XML folks dive in and help create a great format. The goal is to reduce the information required to set up editing software to three well known elements. UserName, Password, and homepage URL. Any other critical bits should either be defined in the related RSD file, or discoverable using the information provided.

Location, Location, Location

Jon Udell provided another piece to the puzzle, reminding me about the RSS link we have buried in our homepages. A similar link would serve the purpose here. This idea as it relates to RSS (I believe) was first proposed by Mark Pilgrim. It works perfectly here as well. By inserting a link such this <link rel="EditURI" type="application/rsd+xml" title=\"RSD" href="http:\//whereever the rsd.xml lives." /> into a homepage's header we uncouple the need to know where to find the RSD file. Each vendor can control where it makes sense for them to "place" the RSD file, accessible via the embedded URL. Client software only need to look at the homepage headers to discover where to look for more information. Excellent. At the same time, it has been suggested that we have a "best practice" location that represents a location where clients can try to find the file in cases where the link above has been removed, broken, or simply is not present. Having surveyed where folks are keeping their RSS files, we recommend http:\//www.userdomain.com/rsd.xml (There can be validation issues with the closed form (<something />) as shown above, which is important for say XHMTL but not for HTML 4.01 Transitional. The link will work just as well either way.)

Elements

<service> is a container element. It's a hedge against the future. Sub-elements of <service>

<engineName> a string that is the name of the engine that is providing the services being described.
<engineLink> is the URL to the home of the engine.
<homePageLink> is the URL of the users homepage.
<apis> is a container element.

Sub-elements of <apis>

<api> has 4 required attributes. "name" is a string that is the name of the api. There is a list of "well-known" names below. A name does not need to be listed here or elsewhere to be valid. (see below). Multiple api elements are allowed.
- "preferred" is a boolean and takes either "true" or "false". The point is to allow weblog software to list all the APIs supported, but choose which one to "recommend" to the client software. Only one API should set as prefered.
- "apiLink" is the URL for this API. The location the client should speak to.
- "blogID" is a common bit of data that most APIs currently require. It can be specified here. If your system doesn't require it, include the attribute, but leave it blank like so blogID="" (this is demonstrated in the example.)

Optional sub-elements of <api> The api element doesn't require these elements. Information required by more flexible or capable systems can be expressed here. <settings> is a container element and is required if you are going to include the following optional sub-elements.

<docs> is a URL that points to the documentation for this API.
<notes> is text that should be used to explain features and their settings. Intended to be human readable.
<setting> requires a single attribute "name" a string which refers to the name of the "service-specific-setting". The value is the service setting. Multiple setting elements are allowed.

Well known API names

The well known names are a list of suggested names at the time of publication (Wednesday, December 18, 2002). Being listed in this table is not required for an api name to be included in a valid RSD document. Further, we recommend that, if possible, you look to the api name implemented by the creator of that api as the definitive "name". (What is implemented is real.) To suggest additions, please use the form below.

Blogger
MetaWeblog
Conversant
Manila
MetaWiki
Antville
LiveJournal

Example RSD

Example 1 (Displayed below to make this version of the spec self contained.)

<?xml version="1.0" ?> 
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd" >
    <service>
        <engineName>Blog Munging CMS</engineName> 
        <engineLink>http://www.blogmunging.com/ </engineLink>
        <homePageLink>http://www.userdomain.com/ </homePageLink>
        <apis>
                <api name="MetaWeblog" preferred="true" apiLink="http://example.com/xml/rpc/url" blogID="123abc" />
                <api name="Blogger" preferred="false" apiLink="http://example.com/xml/rpc/url" blogID="123abc" />
                <api name="MetaWiki" preferred="false" apiLink="http://example.com/some/other/url" blogID="123abc" />
                <api name="Antville" preferred="false" apiLink="http://example.com/yet/another/url" blogID="123abc" />
                <api name="Conversant" preferred="false" apiLink="http://example.com/xml/rpc/url" blogID="">
                    <settings>
                        <docs>http://www.conversant.com/docs/api/ </docs> 
                        <notes>Additional explanation here.</notes>
                        <setting name="service-specific-setting">a value</setting> 
                        <setting name="another-setting">another value</setting> 
                         ... 
                    </settings>
                 </api>
        </apis>
    </service>
</rsd>

Here is an early example of an RSD file for the RESTLog API.

Extending RSD

Developers are welcome to extend RSD using modules defined in namespaces, as specified by the W3C. A RSD feed may contain elements not described on this page, only if those elements are defined in a namespace. All core RSD elements are defined in a namespace. Below is an example that extends RSD to include two additional elements generatorAgent and errorReportsTo. Another example can be found further down the page. Example (optional module)

Down the road, down the way

Extension and modification should occur via modules. This should provide enough flexibility for anyone to extend the format in the direction they require. Backward compatibility must be maintained by any future versions. As an example I wrote a module for Dave's weblog archives format. Everyone wants easy access to archives! And it displays how RSD can be flexible about its purpose. *

Thanks

Stephan Schmidt, Seth Dillingham, Brent Simmons, and Dave Winer have all lent a hand in getting this together. Their support and ideas are greatly appreciated. I also would like to thank all the developers who decided to join the fun and implement RSD prior to 1.0. It really helped other developers understand what RSD is accomplishing.

Changes

Wiped the changes clean (they're archived)

Notes

Contact

Feel free to write.

Copyright and disclaimer

© Copyright 2002 Circumstance Technology. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works. This document may not be modified in any way, such as by removing the copyright notice or references to Circumstance Technology or other organizations. Further, while these copyright restrictions apply to the written RSD specification, no claim of ownership is made by Circumstance Technology to the format it describes. Any party may, for commercial or non-commercial purposes, implement this format without royalty or license fee to Circumstance Technology. The limited permissions granted herein are perpetual and will not be revoked by Circumstance Technology or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and CIRCUMSTANCE TECHNOLOGY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

(Suggestions without an email address will not be given consideration. Thanks for your understanding and trust. )
Suggested addition to the list:
Your email address: