Putting XRDS-Simple in Context

What are we trying to do?

XRDS-SimpleXRDS-Simple is a protocol for service discovery. The level of discovery is kept intentionally simple to accommodate existing use cases and apply established patterns. Service discovery at this level is technically trivial. After all, how hard can it be to list a bunch of URIs and add some descriptions next to each one? The only issue is agreeing on some format that everyone can understand and implement. In developing a discovery protocol, we are trying to answer two questions:

  1. How to find information about a resource through its URI?
  2. What format is this information provided in?

The URI can be anything, but we are currently scoping XRDS-Simple to HTTP(S) only (the format can support any URI scheme but does not define a discovery method for non HTTP(S) URIs). The URI can point to a web page, in which case you have the option of using HTML tags. Or it can point to any other combination of bytes, be it an image, video, non-html document, etc. More importantly, they can be API URIs producing a wide range of results.

Microformats are a great solution for adding a machine-readable layer to human readable content. It is a great example of how an HTML resource can include discovery information. But that is extremely limited to the use-case in which the data is visible and lives in an HTML page. So we need something much more flexible and generic. XRDS-Simple in no way attempts to replace Microformats, and in fact, is likely to be used in a complementary way.

Within HTTP, this resource metadata can only live in one of three places. In the header, the body, or another document linked from header or body. We just ruled out using the body (since it is media-type specific), and putting potentially a lot of information in the header isn’t appropriate. So we are left with pointing elsewhere.

Once this document is found, we need to parse it. Since the use cases are generally simple at this point, we need a simple format. It needs to allow grouping of URIs and assigning them types, media-types, and a method for redundancy or alternatives (with priorities). Anything else is really type-specific or use-case-specific. The most important part is that the format is widely understood and simple to parse.

How did we get here?

What I just described is exactly what Yadis 1.0 is for and without picking at details, is the solution XRDS-Simple promotes. Perhaps it will help people understand it better if they think of it as Yadis 2.0. The name XRDS-Simple was chosen because it is more accurate. It is a simplification of the XRDS format which is accomplished by removing elements and placing more rigid constrains.

XRDS-Simple also removes the need to understand XRI. This is mostly political but for whatever reasons, XRI is being treated unfairly with some strong (usually unfounded or uneducated) bias. XRDS-Simple remove the XRI context from XRDS making it more politically accessible. This is true for other politically-sensitive technologies such as RDF.

It is important to understand how XRDS-Simple came about, to understand the decisions made within the specification. Working on OAuth Discovery, we needed a format to store the OAuth configuration in a machine-readable method. Looking at what was available, and admittedly we did not perform a thorough search, we held a session on the topic at the last Internet Identity Workshop and decided that using the same discovery mechanism as OpenID made sense.

The biggest selling point in using XRDS and Yadis over other existing discovery protocols was that the community in need was OAuth, which is highly linked to the OpenID community. Most of us were already using it – it was a natural fit.

The OAuth community lives by the idea of not inventing whenever possible. So when writing OAuth Discovery, we decided to use Yadis. As it turned out, Yadis 1.0 was officially made obsolete by OpenID 2.0 directly referencing the XRI Resolution 2.0 specification (which adopted the parts of Yadis the XRI resolution workflow didn’t support in previous versions). The end result was OAuth Discovery referenced XRI Resolution 2.0 for use of its XRDS format (section 4) and HTTP discovery (section 6).

This raised a problem. The OAuth community is very passionate about simplicity to point of (and I mean no offense by it) stupidity. In this case stupid isn’t bad, it’s a virtue. It means specs should be easy to read and implement, and should at all cost avoid the need for bible-scale interpretations. To me it means I should never need a library to use a spec, but be able to write my own implementation without pain. So when we picked XRDS as did OpenID 2.0, it introduced a problem.

Reviewers of OAuth Discovery 1.0 Draft 1 agreed that XRI Resolution 2.0 section 6 (Yadis discovery) was easy to follow, but when it came to the full power of XRDS, well, it opened the door to a lot of hesitation. The problem is, XRI offers a very complex selection process with redirects, references, and scoring mechanism that is just not needed for OAuth Discovery. It also talks a lot about, well, XRI. In other words, the sentiment of the community was that using XRDS for non-XRI OpenID or OAuth is an overkill.

Now, unlike some other passionate communities, the XRI folks, lead by Gabe Wachob and Drummond Reed, stepped forward in light of the OAuth community feedback, and offered to help define a simpler use cases and come up with a way to allow for a more restrictive subset that will still be compatible, but easy to implement. They could have said ‘just use an XRDS library if it is hard to follow’, but they didn’t. Their offer was too good to resist.

The first idea was to write an appendix within OAuth Discovery detailing how it will use a subset of XRDS and how parsers can tell only that subset is being use, protecting them from breaking if someone decides to use one of the more advanced XRDS elements. As we discussed this, we realized this can be extremely useful for many other needs, even within OpenID. At the same time, the DiSo folks were looking for something just like that as well.

Of course, we could have just used Yadis 1.0, but again, that would have created a problem. Yadis 1.0 is not valid XRDS (since it explicitly ignores the XRDS selection rules) and OpenID no longer uses it for discovery. It uses XRI Resolution 2.0. This might sound like petty details, but it is not. Discovery is all about interoperability and having an extremely tight spec is critical.

Why not use…?

I don’t know. I can only explain why we picked XRDS as the basis of our solution. I’ve been following the discussions over Data Portability, DiSo, and other related lists/groups, and so far haven’t seen another spec that answers the two questions raised above well. But I am happy to learn. If there is another solution that is both complete and implemented, it is worth our time to look into it. After all, this is just draft 1.

What I would like to avoid are suggestions on how mixing a bunch of existing things can accomplish the same thing. As I said in the very beginning, we can accomplish this with anything that we agree on. But XRDS is already deployed and is driving many OpenID 2.0 implementations. It is a proven solution.

If you notice, I titled myself as ‘editor’ on the specification instead of author. The reason for that is that I view XRDS-Simple as an editorial work rather than creating something original. This is a key point in presenting XRDS-Simple (and my role in it).

For a solution to be considered as an alternative to XRDS-Simple, it must be:

  1. Simple! Developers should not need to read a long list of other specifications first. An average developer should be able to implement it from scratch (with the help of an XML parser) in just a couple of days or less, and on any platform.
  2. Deployed. XRDS-Simple via Yadis/OpenID is already used. While not 100% compliant with the new version, the way OpenID currently uses XRDS fits right in the XRDS-Simple subset. To pick something else as the basis of service discovery, we need something that has a similar deployment base. After all, proven track record is pretty important for discovery.
  3. Politically attainable. This isn’t easy. With XRDS-Simple, we are taking out XRI references because it helps sell the solution. Does it make sense? No, politics rarely does. But let’s face it – standards are nothing-but politics. So picking RDF as the basis for web-wide service discovery is a hard sell. So is SOAP or other existing descriptor formats. XRDS has the advantage of already breaking through the XRI/OASIS world and being adopted by the OpenID community. It has momentum.

Can we make changes?

Generally, No. Changing the way XRDS-Simple works means moving away from XRDS. That means breaking at least one of the rules above: it must be deployed. The explanation to most of the questions raised so far regarding XRDS-Simple valid but from a process perspective, should have been asked over a year ago when all this was being created but OpenID, XRI TC, and Yadis.

The answer to most of these questions is: “because that is how XRDS/Yadis does it“. We picked an existing standard and (hopefully) made it easier to use and implement by limiting its scope and functionality. I am sure this is not a satisfactory answer for many people, but the same can be said and asked about any other *existing* solution we might have picked.

What we can do is make the spec easier to read and implement. We can make sure the restrictions do not prevent widely-needed use cases. We can reach out to people using XRDS/Yadis today and see what they have learned and if we addressed some of the issues they had to deal with.

And yes, we can potentially drop XRDS-Simple and pick a whole other solution. I’ll even make it easier for people who want to suggest one: don’t write your own spec – just post a link to the spec you want to use or base your solution on, and explain how it complies with the 3 requirements listed above.

6 thoughts on “Putting XRDS-Simple in Context

  1. This is excellent news. As someone who was concerned about the “baggage” of OpenID 2.0 referencing a chapter of the XRI Resolution spec, I’m glad to see that we finally have a more accessible document that achieves the same thing.
    As you say, it’s all about politics and perception. The XRI Resolution spec is long and intimidating.
    By the way, the initial link in your entry here seems to be missing the top-level domain in its URL.

  2. Link corrected. Thanks.
    The XRI Resolution 2.0 spec is still a very interesting read. But like any other specification, if you are getting 2-3 pages of value out of reading over 100 pages (because your use case doesn’t need the other stuff), it is not the best use of your time.
    I hope people reading and implementing XRDS-Simple would still take the time to at least glance over at the XRI spec. But yes, the goal is to pick what is most common and explain it as simple as possible.

  3. “Perhaps it will help people understand it better if they think of it as Yadis 2.0.”
    Yes, that’s what I needed to understand. Thanks!

  4. Over here at DataPortability, we’d very much like to put other services (such as FOAF URL location or OpenSocial People Data API endpoint) into the same XRDS file. But I’m feeling daunted by trying to work out exactly what the entries should look like. Can you tell me where I should start?

Comments are closed.