FYI
From:
[mailto:] On Behalf Of DeWitt
Clinton
Sent: Saturday, August 22, 2009 8:31 AM
To:
Cc:
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 <>
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:
[mailto:]
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:
[mailto:]
On
> Behalf Of Blaine Cook
> Sent: Friday, August 21, 2009 1:26 AM
>
> 2009/8/21 DeWitt Clinton <>:
> > 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:
[mailto:]
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
