Link to original RFC: Really Simple Discoverability 1.0.0
Thu, Oct 31, 2002; by Daniel Berlinger (@danielberlinger):
Really Simple Discoverability 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. This format is simple but flexible. One of the design 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.
Communicating with services requires knowledge about the service whereabouts and settings. Specifically, discovering the "Path To Service" setting, but more generally where to point for services is a common issue.
The solution proposed below will simplify the discovery of settings information by reducing the information a user must supply to three well known elements. Something simple, like an XML document that lists the critical info would be about right. It should also be simple enough to be written by hand. This document is called Really Simple Discoverability, or RSD document.
Assuming that the RSD file is provided or generated by the service software the other required bits of information not well known to the user can be easliy discovered and supplied. The goal is to reduce the information required to set up service communication to three well known elements: UserName, Password, and root URL. Any other critical bits should either be defined in the related RSD file, or discoverable using the information provided.
A link similar to the RSS link burried into blogs would serve the purpose here.
By inserting a link into a homepage's HTML head section we uncouple the need to know where to find the RSD file.
The link relationship is expressed in the following format:
<link rel="RSD" type="application/rsd+xml" href="http://www.userdomain.com/rsd.xml" />
Each service provider 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.
A "best practice" location that represents the location where clients can try to find the file in cases where the link above has been removed, broken, or simply is not present, would be the following:
http://www.userdomain.com/rsd.xml.
The RSD document specification consists of the following XML element structure:
| Element | Description |
|---|---|
<rsd> |
RSD document root element |
<service> |
Container element. The RSD document can contain one or more service elements. |
<engineName> |
A string that is the name of the engine that is providing the services being described. |
<engineLink> |
The URL to the home of the engine. |
<homePageLink> |
The URL of the users homepage. |
<api> |
Container element. The service element can contain one or more api elements. |
Required attributes of the <api> element are:
| Attribute | Description |
|---|---|
| name | A string that is the name of the API. |
| preferred | A boolean; either true or false. Only a single api element should be listed as preferred for a given service element. |
| apiLink | A string that is the URL of this API. |
| blogID | A common bit of data that most APIs currently require. If you system doesn't require it, then include the attribute but with a blank value: blogID="" |
Optional sub-elements of the <api> element are:
| Element | Description |
|---|---|
| docs | A string that is the URL pointing to the documentation of this API. |
| notes | Text that is used to explain features and their settings. It is supposed to be human readable. |
| setting | Requires a single attribute name: a string which refers to the service-specific setting. The value is the service setting. Multiple setting elements are allowed. |
<?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>Developers are welcome to extend RSD using modules defined in namespaces, as defined 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.
© 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.