OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

xri message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: FW: Feedback on the XRD specification draft



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.


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.


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.


9) Update the example.


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&amp;fmt=foo" />

  <link rel="describedby" type="application/rdf+xml"

        href=""http://s2.googleusercontent.com/webfinger/?q=bradfitz%40gmail.com&amp;fmt=foaf" />




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.


Hope this helps!






[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]