Re: [xri] FW: Feedback on the XRD specification draft

[Joseph A Holsten <joseph@josephholsten.com>]

Given denormalized link elements and order-based priority, everything  
else seems reasonable. That example is crystal clear to anyone with  
HTML or Atom experience.

Turning subject/alias into a link makes a lot of sense, but doesn't  
jive with pattern matching. Neither do templates in an href attribute.  
Perhaps hreftemplate or hrefpattern?

Ultimately I'd like to see a CRUD API for XRD, and I've only though  
about that in terms of explicit priorities. But ultimately adding  
links programatically probably means that the new link is lower  
priority than earlier ones that match.

But if the syntax is going to change dramatically, I'll be spending  
some time investigating XLink's syntax to see if there are any useful  
patterns there.

On Aug 21, 2009, at 2:40 AM, Eran Hammer-Lahav wrote:

>
>
> 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.
>
> I was using the XRD draft spec 4 found at: http://www.oasis-open.org/committees/download.php/33772/xrd-1.0-wd04.html
>
> 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 tohttp://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 
> " />
> </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.
>
> Hope this helps!
>
> -DeWitt
>
>
>