FW: Feedback on the XRD specification draft

[Eran Hammer-Lahav <eran@hueniverse.com>]

FYI

 

From: webfinger@googlegroups.com [mailto:webfinger@googlegroups.com] On Behalf Of DeWitt Clinton
Sent: Saturday, August 22, 2009 8:31 AM
To: webfinger@googlegroups.com
Cc: xri@lists.oasis-open.org
Subject: Re: Feedback on the XRD specification draft

 

Thank you for the detailed reply, Eran.   I'll save a detailed response to your comments until after the spec leaves the TC and is open for public review.  However, the TC might agree that my feedback introduces no new intellectual property considerations, as all I'm suggesting is that the XRD format follow pre-existing standards, and hence hopefully this feedback might be considered even before the spec is completed.

 

Really the essence of what I'm encouraging is twofold.  First, that the XRD specification should follow pre-existing standards because doing so offers substantial non-technical advantages, and second that those pre-existing standards in fact offer a technical advantage.  In other words, it's a win/win to follow prior art here and not invent something new.

 

Regarding the first, the proposed XRD <Link> element is not just different than HTML or Atom <link>, it feels arbitrarily different.  Given the overwhelming popularity of HTML and Atom <link>, it seems to me that the burden should be on the TC to present a convincing case why prior art can not work for XRD.  Note that I'm not saying "is not optimal", I'm intentionally saying "not work."  My back of the envelope math suggests that there are roughly a trillion <link> tags already existing in the wild in HTML alone (more if you count Atom feeds).  That's a lot of precedent, and it means that there are a lot of people that already know how to generate and parse them.  The cognitive overhead of learning a new syntax and naming convention just for this one specification is non-negligible, and further, inventing a new format to do the same thing inhibits interoperability and reuse.

 

Regarding the second, I feel that the proposed XRD <Link> element is actually technically inferior to the HTML and Atom <link> element.  The presence of multiple zero-to-many child elements (MediaType, URI, URITemplate, etc), and the out-of-document-order ordering introduced by 'priority' do in fact make the XRD <Link> element harder to parse and harder to use.  I say this with confidence having now written a partial parser for the XRD <Link> element and having seen the complexity it creates firsthand.

 

That said, I'm willing to entertain the notion that my experience implementing and using an XRD parser was not representative.  Can you point me to other (preferably open source) implementations of an XRD-based client?

 

Thanks again for the reply!

 

-DeWitt

 

On Fri, Aug 21, 2009 at 11:42 AM, Eran Hammer-Lahav <eran@hueniverse.com> wrote:

First, thanks for the detailed feedback! It is great to get fresh eyes looking at XRD and taking the time to report back from actual deployment experience. You are also the first person looking at it who was not deeply involved in the conversations about discovery, OpenID, and XRDS-Simple.

Before this thread goes too deeply, I must remind people that while feedback is always desired, this list is the wrong forum for discussing XRD (if you hope to actually influence its design). XRD is a product of the OASIS XRI TC and like any standards body, OASIS has rules about how feedback should be submitted for consideration. I hate to be a pain in the ass about this, but IPR, as well all know too well, is important. The good news is that within a week or two we expect to have a committee draft and open it officially for public review.

Meanwhile, if you want to offer feedback use:

http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=xri

And those who would like to join the TC can contact me directly.

XRD has a lot of use cases that go far beyond WebFinger and social web applications. While it can certainly be simplified in the case of WebFinger, that will not serve well the needs of other communities and the goal of having a common format for describing resources. We have worked hard to keep it as simple as possible.

Also, in the context of WebFinger, there is nothing saying you cannot profile XRD to add some restrictions. That was the approach we took originally with XRDS-Simple when used in OAuth discovery. I personally don't think it is worth it because XRD *is* pretty simple now, but it is possible.

> -----Original Message-----
> From: webfinger@googlegroups.com [mailto:webfinger@googlegroups.com] On
> Behalf Of DeWitt Clinton
> Sent: Friday, August 21, 2009 12:26 AM

> 1) Denormalize the Link elements.
>
> Currently the Link elements contain lists of Rel, MediaType, URI, and
> URITemplate elements.  While this may make *publishing* an XRD easier,
> it definitely complicates the implementation of a client, which either
> needs to perform messy looping logic, or denomalize the whole thing
> ahead of time.  I highly recommend making Rel, MediaType, URI, and
> URITemplate zero-or-one values.

This is not how current links work. Both HTML and HTTP allow multiple rel values (space delimited) on a single link. HTTP Link header explicitly allows for multiple variables on a single link as well (multiple types, etc.). The only new thing here is allowing multiple URIs which has been proven convenient. I agree that it makes it easier for XRD providers than consumers.

There is obvious need for multiple <Rel> values on a single link. Just take a look at how OpenID is using XRDS with multiple <Type> elements (now <Rel>) on a single <Service> (now <Link>). It is true you can split it over multiple links but that makes the document much harder to understand by people and right now it is pretty readable without a parser.

The complexity of link selection is not a byproduct of the schema but of how applications choose to use it. If a protocol requires looking for matching links with a whole set of requirements (a combination of multiple rels and other values), it is going to be a complex task regardless of allowing multiple child elements.

In terms of past experience, we looked at using a single <Rel> element with space delimited values like HTML but we noted that this has caused many problems in HTML where people use primitive tools to search the document for string patterns and such spaces break their limited expectations. OpenID tries to use it to combine support for 1.1 an 2.0 and most RPs fail to find the combined link.

> 2) Attributes for key/value pairs, not elements
>
> Most of the elements contain only a string text value.  Those should be
> attributes, not child elements.  Moving to attributes makes the
> document easier to parse (no need to worry about child text
> normalization) and more importantly, this ensures that those nodes
> won't be extended or modified down the road.  This will make the XRD-
> as-JSON crowd happier, too, as it is very cumbersome to express
> key/value pairs in JSON that might someday have extra attributes or
> children.

Given #1, this will not be very practical. Repeating attributes multiple times isn't pretty and putting multiple values into a single attribute is a known problem and requires more parsing of value strings. I understand the desire to express XRD in JSON but it has never been a requirement for XRD. XRD has good reasons to use XML (and I don't think any of us want to have the XML vs JSON debate here) which is at the core of XRD's extensibility model. After all, that's what the X in XRD is for.

I personally find the current XRD schema a lot more readable and approachable by people (who don't make a living coding HTML by hand). There is also benefit to making XRD look somewhat different to reduce the expectation that link attributes from HTML are valid in XRD.

> 3) Drop the Priority attribute on Link and URI and URITemplate.
>
> XML document order is sufficient.  If clients are expected to honor
> priority order, then discovering that order needs to be simple.

We are going to soften the text about priorities in the spec and make it a lot simpler and shorter. Right now the spec is pushing XRD providers to use it but the next text will simple mention it as an optional feature. We are still debating whether clients *must* obey priorities or *should*.

Dropping the priority attribute has consistently been the number one feedback for XRDS-Simple. Personally, I am very fond of it when I publish XRDs and hate it when I write XRD clients. Dealing with priorities in my first XRDS parser was a big pain in the ass. But once done, it is a useful feature to have and hopefully people will reuse libraries so this pain will not have to be repeated. If the only reason not to have it is the need for some extra code, I don't think it is enough to remove it (same way I feel about removing crypto from OAuth because people find signatures hard).

This is something the TC has explicitly discussed recently and voted to keep. However, when we open the spec for public review and request feedback, we will monitor the responses and reevaluate if this proves to be a bigger issue.

> 4) Move the Signature out of band.
>
> Can you link to a signature by URL?   My gut tells me very, very few
> clients will implement to http://www.w3.org/TR/xmldsig-core/, and
> that's the bulk of the payload here.

The reality is that until we actually try it, we will not have any real answer about the right way to sign XRD documents and verify trust. The solution proposed by XRD is the compromise accomplished after almost a year of constant debates with representation and feedback coming from a wide-range of people and communities. But all that means is that we have something we were able to agree to put on paper. I would also defer to Will Norris on implementation experience because has been working on a PHP library.

The Google team rejected linking to signatures and certificates due to the complexity of deploying such an setup (it was our very first proposal). At the same time, they did not like the signature in the document but instead in an HTTP header. That keeps the signature as part of the same message, but makes signing the document easier because it can be signed as a blob without any canonicalization. The concerns expressed about using HTTP headers included dependency on the transport protocol, inability to distribute XRD using other means that do not include a message envelope, and limitations in manipulating and consuming HTTP headers.

So my answer to this is that this is very much an open issue and that the XRD spec is offering one solution that represents the best compromise we were able to reach after talking about this since last December.

> 5) Use a more conventional capitalization scheme.
>
> Acronyms are words, lowerCameCase, etc.

I don't think the current style is so out of the ordinary. Personally, I couldn't care less as long as it is consistent.

> 6) Be consistent with prior specs.
>
> 'Type' not 'MediaType', 'Href' not 'URI', etc.

That's where XRD history comes in. XRD is really a rewrite of XRDS. Since XRDS had <Type> element at the <Service> level, and XRD has a <Type> element at the <XRD> level, we decided against using the name <Type> in <Link> to avoid confusion with existing XRDS implementations. <URI> was always <URI> and changing it to href doesn't make it any clearer (and beside, href is not an accurate term here). Note that HTTP does not use href but only wraps the URI in '<>'.

> 7) Move the top-level Subject and Alias into a Link
>
> Consider using an additional Link element with an appropriate rel value
> ('describes'?) instead of making new top-level elements.

<Subject> describes the XRD itself and is critical for trust. We considered expressing <Alias> as a link but eventually decided that its semantics are so clear and specific that a link will just make it more difficult for implementation. This is an optimization that only makes the spec shorter but makes consuming XRD longer and more complex. It also means you have to parse all the links before you can even verify trust which a simple <Subject> element offers (and enforces cardinality).

Also, <Subject> has a special meaning at the <Link> level that is critical for resolving trust when changing authorities. It is how one XRD can express what is permitted over at the other end (be it a service endpoint or another XRD).

> 8) Add a Title to the Link element
>
> So when presented to humans, something readable can be displayed.

This is a good idea but one that failed to produce any actual proposal during the XRDS-Simple discussions. If more people find it useful, we can add it building on the HTTP Link header. So it would look something like:

<Title lang="en-us">I'm a link</Title>

> -----Original Message-----
> From: webfinger@googlegroups.com [mailto:webfinger@googlegroups.com] On
> Behalf Of Blaine Cook
> Sent: Friday, August 21, 2009 1:26 AM
>
> 2009/8/21 DeWitt Clinton <dclinton@gmail.com>:
> > Hi all,

> > 1) Denormalize the Link elements.
>

> This should also make the microformats and CSS crowd happy, as it's
> completely in line with what they're doing already. You get publicity
> for free when a designer realises that they can [easily] pretty-ify
> XRD.

I would consider this a bad thing. XRD is taking a completely different approach than Microformats and relies on strict semantic meanings of its links and other elements. While XRD is extremely extensible, it would be incorrect to use Microformats within XRD, primarily because XRD is designed to be consume exclusively by machines (but readable by developers) unlike HTML which is primarily for people.

As for making XRD pretty using CSS, that doesn't make any sense.

> > 2) Attributes for key/value pairs, not elements
>

> This is probably the most important bit - XRD as per the spec right
> now reminds me of Apple's plist format. Which I hate with seething
> passion. Often when I'm playing with XML, I want to be able to grep
> through it and try some free throw-away experiments. PList and XRD are
> much less amenable to that approach than DeWitt's proposal.

While I can appreciate the desire not having to parse XML in some cases, this is an XML document and should be parsed with an XML parser.

> -----Original Message-----
> From: webfinger@googlegroups.com [mailto:webfinger@googlegroups.com] On
> Behalf Of DeWitt Clinton
> Sent: Friday, August 21, 2009 7:48 AM

> I haven't thought through match yet, but that's partly because I
> haven't convinced myself it is needed.  : )

There is a long story behind the need for the 'match' attribute on <Subject>, but the short version is that it was the best compromise we found for dealing with giving host-meta a subject. Host-meta needs a subject for trust purposes, but there is no way to express 'a host' using URIs. What the match attribute does is express a group of resources using a simple matching rule.

We tried hard to avoid adding subject sets into XRD because we don't have any other use case right now than host-meta. But minting a URI for host received very negative feedback from the IETF community, and changing the subject from a URI to something else required a new attribute to indicate the type of the subject string. Another option was to define a whole new element just for host-meta link <Host>, but the meant having to write custom code to verify trust for host-meta that is different from other <XRD> documents.

---

Hope this helps explain the design decision behind XRD.

EHL