Re: [xri] Working Draft 12

[Drummond Reed <drummond.reed@xdi.org>]

On Sat, Jan 16, 2010 at 2:38 PM, Will Norris <will@willnorris.com> wrote:

please review Working Draft 12 below[1], and submit any feedback this next week.  We (read: Scott) were able to address the changes mentioned on Thursday's call quite quickly, so we should be on schedule for starting the Committee Draft 02 vote this next week (Jan 22).

Please note that we have also amended the Namespace URI versioning policy.  The proposed version can be found here[0].  I would imagine we have to vote on that separately, but we'll have to check with Mary to be sure.  Please review that as well.

[0]: http://tools.oasis-open.org/version-control/svn/xri/xrd/1.0/drafts/wd12/namespace.html

Thanks,
will

[1]http://www.oasis-open.org/committees/download.php/35954/xrd-1.0-wd12.html

Will,

 

Great job on WD 12. Following are my “fine read” comments, which are 100% editorial. If these seem like “fine tooth comb” level, in many ways they should be – with CD 02 we want the bar for any further changes to be very high. So I read this with my English editor’s hat on (which I wear frequently in my day job ;-)

 

=Drummond

 

NOTICES

 

Mary McRae may be the one to take care of this, but the Copyright notice is still 2009.

------------

 

SECTION 1

 

First para: “Resource descriptor documents provide machine-readable information about resources (resource metadata) for the purpose of promoting interoperability, and assist in interacting with unknown resources that support known interfaces.”

 

Suggest (to eliminate comma splice): “Resource descriptor documents provide machine-readable information about resources (resource metadata) for the purpose of promoting interoperability. They also assist in interacting with unknown resources that support known interfaces.

--------

 

SECTION 1.5.3

 

Current: “Time values MUST be expressed in UTC form, with no time zone component (represented by the UTC 'Z' timezone).”

 

That’s not accurate – Z represents the 00:00 timezone.

 

Suggest: “Time values MUST be expressed in UTC form, and MUST use the UTC timezone 'Z'.”

--------

 

SECTION 2

 

Second para: “An XRD document MUST be a well-formed XML document as defined by [XML 1.0] with a root element of <XRD>, MUST validate against the normative XRD schema identified in Section 1.4, “Schema Organization and Namespaces”, and MUST adhere to the additional syntactic constraints defined by Section 1.5, “Common Data Types” and this section.”

 

That’s a lot of MUSTs in the same sentence.

 

Suggest: “An XRD document MUST: a) be a well-formed XML document as defined by [XML 1.0] with a root element of <XRD>, b) validate against the normative XRD schema identified in Section 1.4, “Schema Organization and Namespaces”, and c) adhere to the additional syntactic constraints defined by Section 1.5, “Common Data Types” and this section.”

---------

 

Third para: “…to include any other metadata about the resources and links they describe.”

 

I suggest striking the word “any” because it makes it sound like XRDs are the only place you can put metadata about a resource, which of course they are not.

---------

 

SECTION 2.5

 

First para: “The <Property> element declares a property of a resource or link relation, expressed as a key-value pair.”

 

To a new reader this might be confusing. Suggest: “The <Property> element declares a property of a resource (when used as a child of the <XRD> element) or link relation (when used as a child of the <Link> element), expressed as a key-value pair.”

 

SECTION 2.6

 

Second para: “This element carries similar semantics as the…”

 

“similar…as” sounds funky. Suggest: “This semantics of this element are similar to the…”

----------

 

Second para: “The one distinction is that link relations described by the <Link> element are between the resource described by the XRD (referred to as the context resource by [Web Linking]) and the linked resources (referred to as the target resource by [Web Linking]), and not between the XRD document itself and the linked resource.”

 

The singulars and plurals are not parallel. Suggest: “The one distinction is that the link relation described by the <Link> element is between the resource described by the XRD (referred to as the context resource by [Web Linking]) and the linked resource (referred to as the target resource by [Web Linking]), and not between the XRD document itself and the linked resource.”

-----------

 

“The rel attribute is semantically and syntactically equivalent to the Link Relation Types defined in [Web Linking], with the exception that it only allows for a single relation type and does not allow for multiple space delimited values.”

 

Given the objection that Patrick had to the way this was phrased in CD 01, I suggest: “With one exception, the rel attribute is semantically and syntactically equivalent to the Link Relation Types defined in [Web Linking]. The exception is that it does not allow for multiple space delimited values; rather it allows for only a single URI value that defines a single relation type.”

-----------

 

“Applications utilizing the template mechanism must define the template syntax and processing rules (including error handling) as well as the variable vocabulary.”

 

Shouldn’t that be a normative MUST?

-----------

 

SECTION 2.7

 

“The <Title> element contains a string value that provides a human-readable description for the linked resource.”

 

Suggest: “The <Title> element contains a string value that provides a human-readable description for the relationship with the linked resource.”

-----------

 

SECTION 3

 

First para: “…with the explicit intention that applications will extend XRD to include any other metadata about the resources they describe.”

 

Same comment as above: strike the word “any”.

-----------

 

SECTION 3.1

 

“It is expected that applications will use appropriate established URI identifiers for these purposes, or define new identifiers as necessary. It is RECOMMENDED that any new identifiers be defined in a formal specification of use.”

 

This does not seem to say strongly enough that people really should reuse existing identifiers whenever possible.

 

Suggest: “Whenever possible, applications SHOULD use established URI identifiers for these purposes to promote interoperability and shared semantics. Only when absolutely necessary should new URI identifiers be defined. It is RECOMMENDED that any new URI identifiers be defined in a formal specification of use.”

------------

 

SECTION 4

 

My only feedback about this section is that it’s always funky if a section has only one subsection. Since the entire section is really about one topic – selecting linked resources – I would remove the 4.1 section heading completely and just retitle section 4 as “Selecting Linked Resources”.

--------------

 

SECTION 7.1

 

Bullet 1: “It MUST implement parsing of XRD documents, as defined in Section 2, “XRD Document Structure”.”

 

Remove comma.

--------------

 

SECTION 7.2

 

Bullet 2: “In addition, it MUST support the verification of…”

 

Remove “In addition,”

--------------

 

SECTION 7.3

 

Bullet 1: “It MUST support the creation of XRD documents, as defined in Section 2, “XRD Document Structure”.”

 

Remove comma.

---------------

 

SECTION 7.4

 

Bullet 2: “In addition, it MUST support the creation of…”

 

Remove “In addition,”

--------------