RE: [xri] Pre-draft of "HTTP-based Resource Descriptor Discovery"

["Drummond Reed" <drummond.reed@cordance.net>]

Eran, 

This is a really solid doc. As you requested, here's my first-pass feedback,
broadly divided into formatting/wording and structure/substance:

FORMATTING/WORDING:

All
As a rule, a hyphenated name or phrase used as a heading or proper noun uses
First-Letter-Caps, e.g. heading "7.3 Site-meta Document" should be "7.3
Site-Meta Document". In running text, it should either be "Site-Meta"
(proper noun) or "site-meta" (generic noun) but not "Site-meta" (except, if
it is generic noun, when capitalized at the start of a sentence).

3. (whole section)
You hyphenate "resource-discovery" and "service-discovery" throughout, I
think to emphasize them as separate terms, but they are not hyphenated in
normal use or elsewhere in the document. I wouldn't hyphenate them in this
section or elsewhere. To emphasize the terms the first time you use them in
this section you could use quotes or italics.

5. 
third para: "In the case of multiple descriptors, selecting which descriptor
to use is application-specific using factors such as the descriptor document
format, accessibility, and other typed relationships, and is beyond the
scope of this memo." Suggest breaking into: "In the case of multiple
descriptors, selecting which descriptor to use is application-specific. It
may involve factors such as the descriptor document format, accessibility,
and other typed relationships, and as such is beyond the scope of this
memo."

paras 5-7 (the example). I found it confusing that the text says, "For
example, the following HTTP response header returned with the HTTP
representation of the resource http://example.com/resource/1"; and then the
example shows:

	  Link: <http://example.com/resource/1;descriptor>;
          rel="describedby"; type="application/xrd+xml"

You don't explain Link Templates until later in the doc, so it baffled me
why "http://example.com/resource/1"; and
"<http://example.com/resource/1;descriptor>" didn't match. I'd either take
out ";descriptor" in this example -- so the two URLs match as the reader
expects -- or explain here why they are different.

6. first para: "A somewhat complete analysis of the potential methods..."
Suggest, "A reasonably complete analysis of the potential methods..."

7.3
second para: "It can be considered a registry for "known-location"
resource..." should be "resources"

third para: "Site-meta offers a convenient location for storing information
about how to map between resource URIs to their descriptor URIs" should be
either "map resource URIs to their descriptor URIs" or "map between resource
URIs and their descriptor URIs".

third para: "...provide descriptor locations to URIs with schemes
other..."/s/"...provide descriptor locations for URIs with schemes other..."


STRUCTURE/SUBSTANCE

3. First Para: This seems to overlap quite a bit with the Intro section. The
rest of the section draws a very useful distinction between resource
discovery and service discovery. Suggest: a) renaming this section "Resource
Discovery Vs. Service Discovery", b) flipping the order of first and second
paras.

3. I think your definition of "service discovery" can be tightened and I
have some other feedback about how this section can make its point (which I
completely agree with), but that can wait until the next draft.

4.3 bullet #2: You say, "The resource descriptor document is retrieved and
parsed based on the descriptor document format used." I think the point you
made in section 1 is that retrieval is NOT based on the descriptor document
format used but should be generic for all descriptor formats. That means
only parsing would be format-specific, no?

4.3 last sentence: You say, "Capabilities usually carry a known identifier
that can be matched to a database of known capabilities by the consuming
application." I'd broaden that (thinking about RDF and XDI) to something
like, "Capabilities are usually described with identifiers or description
languages that the consuming application can match to a database of known
capabilities or process via an interpreter."

5. Heading: Currently "Resource-Descriptor Link Relationship". This term
really confused me standing alone as a heading. Were you talking about the
Resource? The Descriptor? The Link Element? The Link Header? I had to read
the section to figure out what it covered. Suggestion: use a longer but more
self-descriptive heading such as, "Link Between Resource URI and Descriptor
URI"

6. Second set of bullets. In my first reading, the text introducing this set
of bullets says, "The methods are:" I continued reading, saw the references
and technical meat, and thought, okay, these are the actual definitions of
the methods. Then I kept reading and thought, hmmm, these are pretty short
definitions for a spec like this. It wasn't until I read further that I
realized that the full definitions were in the following section. So three
suggestions: a) change the intro sentence to: "The three methods, described
in detail in the next section, are:", b) number the bullets (1, 2, 3), c)
keep these three paras to just plain English descriptions so as to quickly
educate the reader without introducing any technical details or references
here, and move all those down into sections 7.1, 7.2, and 7.3.

6. Second-to-last bullet. You say, "...all methods MUST produce the same
resource descriptor (either by returning the same descriptor URI or a
different descriptor URI that points to the same descriptor document
content)." The latter part confuses me. Do we really want to promote the
same descriptor document living at different URIs? Or did you mean different
aliases that redirect to the same URI?

7.2 How much of this section repeats normative requirements of
I-D.nottingham-http-link-header vs. how much are new requirements of this
profile? It's good to repeat the most relevant requirements here, but it's
important to distinguish which ones are from that spec versus which ones are
unique to this "profile" of that spec. You might even want to break them
into a 7.2.1 and 7.2.2 to do that.

7.3 Fourth/Fifth Paras: - I think I know what you are trying to say here but
these paras are not enough to communicate a really hard concept -- which is
actually quite a critical one for implementers. I personally think this
point requires a longer explanation and at least one example and thus should
get its own subsection called something like "7.3.1 Abstract Site Vs.
Concrete Root Resource Description".

7.3 Sixth Para+: This section is so important that I would break it be
broken into its own subsection called "7.3.2 Link Templates".

**********
That's all I have tonight. Again, great job. I hope all our specs in this
cycle end out this clean.

=Drummond 


> -----Original Message-----
> From: Eran Hammer-Lahav [mailto:eran@hueniverse.com]
> Sent: Wednesday, January 07, 2009 11:41 PM
> To: xri@lists.oasis-open.org
> Cc: Mark Nottingham
> Subject: [xri] Pre-draft of "HTTP-based Resource Descriptor Discovery"
> 
> Please do not share this outside the TC until it is published officially.
> 
> Attached is my working copy of the 'HTTP-based Resource Descriptor
> Discovery' proposal. I still need to clean up the last third, but please
> do provide feedback both editorial and content. Editorial changes at this
> point should be sent directly to me. Content should be discussed on the
> list.
> 
> I plan to spend most of Thursday cleaning it up and pushing it out as an
> IETF I-D. I will then move back to working on the XRD 1.0 schema document.
> 
> There is nothing new in this document except for additional details about
> HTTP response codes and such. Also, it uses the current published /site-
> meta schema and not the new text-based format. This will be changed as
> soon as there is something to reference.
> 
> EHL