From: webfinger@googlegroups.com
[mailto:webfinger@googlegroups.com] On Behalf Of DeWitt Clinton
Sent: Friday, August 21, 2009 12:26 AM
To: webfinger@googlegroups.com
Subject: Feedback on the XRD specification draft
Hi all,
After implementing an XRD parser in the webfinger test
client I've collected some feedback on the XRD spec, listed here roughly in
order of how important the various issues felt at the time.
First, there are some things I liked a lot, in particular
the orthogonality of the rel/uri/type tuple. Also, I'll readily admit
that I haven't been closely following the OASIS list for the XRD spec (or
XRDS), and don't know how much is carry-over from specs like XRI. So
consider this as feedback from someone coming from a web background with
relatively fresh eyes.
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.
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.
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.
4) Move the Signature out of band.
5) Use a more conventional capitalization scheme.
Acronyms are words, lowerCameCase, etc.
6) Be consistent with prior specs.
'Type' not 'MediaType', 'Href' not 'URI', etc.
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.
8) Add a Title to the Link element
So when presented to humans, something readable can be
displayed.
The example is out of sync with the text above.
Wrapping that all up, I present a mock XRD using those
ideas:
<?xml version='1.0'?>
<xrd xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
expires="2019-01-01T00:00:00Z">
<link rel="describes canonical"
type="http://webfinger.info/account"
href=""acct://bradfitz@gmail.com"
/>
<link rel="describes"
type="text/html"
href=""http://www.google.com/profiles/bradfitz"
/>
<link rel="http://portablecontacts.net/spec/1.0"
type="text/html"
href=""http://www-opensocial.googleusercontent.com/api/people/"
/>
<link rel="describedby http://webfinger.info/rel/profile-page"
type="text/html"
href=""http://www.google.com/profiles/bradfitz"
/>
<link rel="describedby"
type="text/x-foo"
href=""http://s2.googleusercontent.com/webfinger/?q=bradfitz%40gmail.com&fmt=foo"
/>
<link rel="describedby"
type="application/rdf+xml"
href=""http://s2.googleusercontent.com/webfinger/?q=bradfitz%40gmail.com&fmt=foaf"
/>
</xrd>
This also has the advantage of being largely consistent with
the HTML, Atom, and the Link header specs, which will facilitate reuse in those
environments, and ease of use for people with a web background.
Again, I understand the intention of XRD a lot better now
after implementing the parser, and really like the link/rel/href-based nature.
However, even partially implementing it was more work than I expected, mostly
due to relatively minor issues.