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

 


Help: OASIS Mailing Lists Help | MarkMail Help

xri-comment message

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


Subject: Comments on Extensible Resource Descriptor (XRD) Version 1.0


Greetings!

On behalf of the OASIS Technical Advisory Board I reviewed Extensible 
Resource Descriptor (XRD) Version 1.0 and have the following comments 
(these reflect my view of the draft and not any official TAB position or 
the views of any other TAB member):

Extensible Resource Descriptor (XRD) Review

Under "Related Work:" you say:

****
This specification replaces or supersedes:
• Extensible Resource Identifier (XRI) Resolution Version 2.0, Committee 
Specification 01, April
2008 [http://docs.oasis-open.org/xri/2.0/specs/xri-resolution-V2.0.html]

This specification is related to:
• Extensible Resource Identifier (XRI) Version 3.0, Working Draft 02, 
August 2009 [http://
www.oasis-open.org/committees/download.php/33877/xri-syntax-3.0-wd02.pdf]
****

In what way does it "replace or supersede" the earlier work? From what
I read, it is a protocol for resolution of identifiers, which isn't
the same thing as association of metadata with an identifier for a
resource. Sounds like entirely different work to me.

Why not simply say it is a different standard?

It also isn't clear how you are using the category "related to" with
reference to Extensible Resource Identifier (XRI) Version 3.0. Ah, is
this simply a prior draft, parts of which are now reflected in the
current proposal? TCs produce lots of drafts and documents. It isn't
necessary to cite them for the final version.

General comment:

Hanging Paragraphs:

A hanging paragraph is one where it isn't possible to determine the
scope of a reference. For example,

2.1. XRD Elements
The XRD elements provide information about the resource described by
the XRD document and list its properties. They also provide
administrative information as to how the document should be cached, as
well as information necessary for the authentication and trust
verification of the XRD document.

2.1.1. Element <XRD>
The <XRD> element encapsulates the entire resource descriptor, and is
most commonly the root element of the document. It contains the
following attributes and elements:

If I say, see: 2.1 do I mean 2.1 or do I mean to include 2.1.1 and
following?

Better practice:

2.1. XRD Elements

2.1.1 General

The XRD elements provide information about the resource described by
the XRD document and list its properties. They also provide
administrative information as to how the document should be cached, as
well as information necessary for the authentication and trust
verification of the XRD document.

2.1.2. Element <XRD>
The <XRD> element encapsulates the entire resource descriptor, and is
most commonly the root element of the document. It contains the
following attributes and elements:

So all references can be specific.

BTW, lose the trailing period (U+002E FULL STOP) on all section
numbers.

Hanging paragraphs (may not be complete):

1, 1.5, 2, 2.1, 2.2, 3, 4, 5, and 7 (current numbering).

Fixing this will cause a renumbering of the child sections so better
to do it now rather than later.

Section by Section Comments

1.5 - vague language, where it says:

The following sections define how to use and interpret common data
types that appear throughout the XRD schema.

Err, what "following sections"? The ones in section 1 or the rest of
the document?

Better practice (it also cures the hanging paragraph in this case) is
to simply lose this sentence. It doesn't add anything to the standard.

As a general standards writing practice, don't use terms like
"following," "above," etc. Be explicit and precise or be silent.

2.1 XRD Elements, reads in part:

The XRD elements provide information about the resource described by
the XRD document and list its properties.

Err, "the XRD document" -> "an XRD document" (unless you mean to
describe only one XRD document)

And, "...list its properties." OK, I'll bite, the properties of the
resource or the XRD document?

Better? Just lose this paragraph as intro text (not necessary for
element definitions) and the content should appear in an
introduction to the standard as a whole.

2.1.1 Element <XRD>

I think most XML users will recognize <XRD> as an element. Drop
the "Element" prefix. (here and generally)

Content of 2.1.1 read in part:

The <XRD> element encapsulates the entire resource descriptor, and is
most commonly the root element of the document.

Well, I suppose it is comforting to "encapsulate the entire resource
descriptor" but a search of the document reveals that "resource
descriptor" isn't defined by this document or reference to another
one.

BTW, "is most commonly the root element of the document." ??

Ah, I had to read to the end but this is because of the "alternative"
content model with <XRDS>. Yes? Lose the <XRDS> element, then say:

"The <XRD> element encapsulates information about a resource and is
the root element of an XRD document."

Short, sweet, to the point.

The next sentence reads:

"It contains the following attributes and elements:"

Another example of "following" and not being specific.

OK, the listing of attributes and child elements:

First, when there is a separate definition of a child element, like
<Expires>, simply list a reference to that definition. Do not
repeat. Say any definition or rule once and only once. To do otherwise
simply invited variation and difficulty in long term maintenance (did
we change it everywhere it occurs?)

So that reduces this part to a series of references (leave the content
model remarks to their definition sections).

I would put xml:id in a separate section, mostly for updating and
reference purposes. In any case, please lose all the "most commonly
used" type language or put it in a note.

Compare 2.1.2 and 2.1.3 lead sentences. Do you see a difference?
Uniformity in language makes it easier to see *meaningful* variation
in standards.

Take 2.1.3 as another example:

"<Subject> is a URI value which identifies a resource. This value MUST
be an absolute URI."

Really? I thought <Subject> (btw, was the capital case intentional?),
was an element, not a value or a URI. Must be all those years of
writing XML. ;-)

How about: "The <Subject> element contains a URI value that identifies
a resource. The URI value appearing in a <Subject> element must be an
absolute URI."

Compare 2.1.4 which reads:

"This URI value provides an additional identifier for the resource
described by the XRD. This value MUST be an absolute URI."

An element definition that doesn't even mention the
element. Perhaps:

"The <Alias> element contains a URI value that is an additional
identifier for a resource. The URI value appearing in an <Alia>
element must be an absolute URI."

was what was intended. (I am working from the text and not trying to
parse the schema to see what it means.)

2.1.5 reads in part:

"The <Type> element declares a property of *the* resource described by
*the* XRD using a URI value. The meaning of *the* <Type> value is
application-specific, and is used by *the* XRD provider to describe *the*
resource to consumers familiar with the type identifier." (emphasis
added)

Suggest:

"The <Type> element declares a property of a resource specified by
an XRD element using a URI value. The meaning of a <Type> value is
application-specific, and is used by an XRD document to describe the
identified resource."

Note that a resource is described by a <Type> value whether it is
understood by a consumer or not. I changed "XRD provider" to "XRD
document" since you are defining a document format. Note the changes
from "The meaning of the <Type> value...." to "The meaning of a <Type>
value...." The first one describes some <Type> value in particular,
the second any <Type> value that is encountered, such as in an XRD
document.


2.2 Linked Resource Elements

First, "primary use" language goes in a non-normative introduction,
not here. Second, note the ambiguous "following elements"
language. Which also lacks content that will be useful to the reader.

2.2.1 Element <Link>

The first clause is ok but then "...and carries *similar* semantics as
the..." No, the <Link> element has the semantics this TC is
defining. That those may be "similar" to some other element could be
observed in a note but better in a commentary on a successful
standard. It is completely inappropriate in *normative* text.

I will comment here on <MediaType> - "Provides a hint at the media
type..." The <MediaType> element states the media type drawn from some
registry. That isn't a "hint." That is statement of the media
type. (full stop)

2.2.2 Element <Rel>

"....semantically and syntactically equivalent to the Link Relation
Types defined in Web Linking, with the exception..." It is equivalent
but not. Just define the semantics of the element for XRD and leave
the observations for notes or outside commentary. Less opportunity for
confusion, not to mention that such observations are not appropriate
for normative text.

2.2.3 Element <MediaType>

Note the inconsistency between the "hint" language and the "must"
requirement to be a value from the IANA registry.

2.2.4 Element <URI>

Reads in full:

"The <URI> element provides the URI of the linked resource. If no
<URI> element is defined, it is assumed the URI can be obtained from a
<URITemplate> element or by other means outside this specification."

Hmmm, does that mean that I can have a <link> element with no
specified URI for the linked resource? And no explicit linking to
either a <URITemplate> element or some other means to obtain one?

First, doesn't that seem to defeat the purpose of the standard to have
a "linked" resource that lacks a link?

Second, allowing either some non-specified use of <URITemplate> or
"some other means" looks like it will quickly defeat any
interoperablitiy between applications using XRD. Yes?

Recalling that sharing of this linked information is a "primary use"
of XRD, this looks like a fairly serious short fall in the proposal.

2.2.5 Element <URITemplate>

Reads in full:

"URI Templates provide a mechanism for URI construction, taking a list
of variables as input and producing a URI string as an output. The
template syntax and vocabulary are dependent upon the combination of
the application through which the XRD document is obtained, and the
link relation type indicated by the <Rel> child element of the
corresponding <Link>. Applications that wish to utilize the template
mechanism need to define the variable vocabulary for each relation
type, as well as the template syntax and processing rules.

If a template uses an unknown syntax or contains unknown variable
names (without rules on how to handle such variables), the parent
<Link> element SHOULD be ignored."

By definition templates only use *unknown syntax* because XRD doesn't
define any and explicitly because of "...template syntax and
vocabulary are dependent upon the combination of the
*application*....") So we can ignore the second half of the statement
and conclude that the "parent <Link> element SHOULD be ignored." in
all cases.

This is entirely application specific, which means there is no
interoperability by definition. That is made even worse by providing
that in any event, the "parent <Link> element" SHOULD be ignored.

I am assuming that interoperable exchange of XRD documents is a goal. Yes?

2.2.6 Element <Title>

Reads in part: "The semantics of this value are intended only for
human consumption and MUST NOT be used to imply any additional
meaning."

"...imply any additional meaning" for who? Applications? Users? Better
to just drop this sentence.

3 XRD Extensibility

General observations inappropriate here as well. If reliance on the
extensibility and registration requirements defined in "Web Linking"
then cite the appropriate section, etc.

Probably should do that and collapse the next two sections into
one. Just do the normative reference and then briefly state the rules
about extensions.

4 Processing XRD Documents

Is any of this normative until we reach the third paragraph of
4.1. Linked Resource Selection?

If not, put in a note or drop entirely.

What are "qualified" documents? I am assuming that "disqualified"
means documents that don't meet some criteria but that isn't free from
doubt. But then the process of examination continues until "...success
is acheived or all elements are exhausted." That sounds like I can
have a "qualified" document that still doesn't meet some selection
criteria.

5. XRD Signature

Hanging paragraph.

5.1 Signing Formats and Algorithms

Sufficient to state the constraint with a normative reference to a
particular section of XML Signature. No need to mention options that
aren't allowed.

For example, here say:

"XRD documents MUST use enveloped signatures as defined by XML
Signature if an XRD document is signed. Any signature algorithm
defined by XML Signature MAY be used."

5.2 References

First paragraph, what does it mean to "...be included within another
document schema."?? Do you mean in another document instance?

Second paragraph, take out the example language.

5.3 Canonicalization

First sentence, reform to make reference to the digital signature
standard that defines the cited elements. Drop the rest of the prose
or put in a non-normative note. Certainly cannot constrain profiles
(the concluding "though it MAY be required by particular profiles."
What is or is not allowed, required, etc., but other standards or
profiles is beyond the purview of any standard.

5.5 KeyInfo

If XRD does not address the use of <ds:KeyInfo> then simply pass over
it in silence. It's presence or absence is then governed by another
standard.

6. XRD Sequence

Past practice with <XRDS> wasn't following *this* standard and so
shouldn't be memorialized here. The cleanest solution is to not define
an alternative syntax that you intend to deprecate as soon as it is
defined.

7. Conformance

7.1 Looking at the schema, it is intended that xrd:Expires and
xrd:Subject can both be absent? I can understand why xrd:Expires might
be absent but am puzzled why xrd:Subject could be absent.

Ah, is this another case where an exception is being made for the
<XRDS> element? That is an <XRD> element can omit xrd:Subject because
the container <XRDS> element may have a "ref" attribute to point at
the resource described by the various <XRD> elements contained by
<XRDS>? Allowing the <XRDS> element as an alternative syntax is just
bad design.

If the goal is interoperability and least burden on *all* 
implementers/users, kill <XRDS> now.

7.2 Introduces without definition the notion of a "published" XRD document.

BTW, should add a conformance clause for XRD documents as well.

Hope that these prove helpful in refining the current draft.

Patrick

-- 
Patrick Durusau
patrick@durusau.net
Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)



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