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

 


Help: OASIS Mailing Lists Help | MarkMail Help

xri message

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


Subject: Decisions RE Patrick Durusau Comments on XRD V1.0 CD 01


This email documents the TC's decisions regarding the greatly appreciated comments from OASIS TAB member Patrick Durusau at the close of the first public review period on XRD V1.0 CD 01. Note the decisions are recorded after comments inserted by spec co-editor Will Norris. Each decision is prefixed on a separate line by:

DECISION:

=Drummond

****** BEGIN DISPOSITION OF COMMENTS FOR PATRICK DURUSAU COMMENTS **********

On Thu, Jan 7, 2010 at 2:31 PM, Will Norris <will@willnorris.com> wrote:

> On Jan 2, 2010, at 2:32 PM, Patrick Durusau wrote:
>
>> 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?
>
> XRI Resolution defines the XRDS descriptor format.  XRD 1.0 replaces that document format.
>
>
>> 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.
>
> We could actually leave this off.  I don't have strong feelings either way.  It makes sense for XRI to maybe reference XRD, but not necessarily the other way around.


DECISION: Remove the second reference (the "related to" reference).

 
>> 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)
>
> Patrick also points out the use of "a" versus "the" when talking about the <Type> element (now <Property>, of course).  I don't have really strong feelings either way on this, but am leaning toward making the proposed changes where necessary to disambiguate what the sentence is referring to.


DECISION: Will will update the document to be consistent.


>> And, "...list its properties." OK, I'll bite, the properties of the
>> resource or the XRD document?
>
> He has a point, but the funny part is that the answer to his question is "both".  <Expires> is a property of the document, whereas <Property> is a property of the resource.  Not sure if that is worth making any changes.


DECISION: Clarify that properties may be for "either/or" the document or the resource.

 
>> 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.
>
> Not sure about this note on "most commonly used" language.  I like the idea of telling the reader how certain elements are intended to be used.. I think that's important.  However, I don't really have an opinion on whether that should be part of normative versus non-normative text.


DECISION: It does not make sense to put xml:id into a separate section, nor to remove the explanatory text. We feel it is appropriate.


>> 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."
>>
>> <snip>
>
> Here I agree.  I think I was actually changing the language slightly on purpose to give it a more conversational tone, but I agree with his statement that "Uniformity in language makes it easier to see *meaningful* variation in standards."  I think this is worth clarifying in the spec.


DECISION: Will will make the language consistent.


>> 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.
>
> see previous note about "a" versus "the".  Patrick's note about "XRD Provider" versus "XRD Document" doesn't matter anymore since that language was removed when we switched <Type> to <Property>.


DECISION: This section is no longer included in WD 11.


>> 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.
>
> see my previous note about "primary use" language.  I disagree that "following elements" is ambiguous.


DECISION: Will to use his judgement. Where possible, references across sections should use section numbers.

 
>
>> 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.
>>
>> <snip>


DECISION: Move the non-normative text making the comment into at least the second paragraph, or, if Will thinks it makes sense, move it into a Note, and check with Mary about the format the note should take.


>> 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.
>
> Since we're intentionally building on the Web Linking framework, I think it's absolutely appropriate to draw the comparison here.  Perhaps it should be worded differently?  I don't know.


DECISION: Make sure that the normative relationship is clear, and text that is not normative gets clearly distinguished either by being in a separate paragraph, or in a Note.


>> 2.2.3 Element <MediaType>
>>
>> Note the inconsistency between the "hint" language and the "must"
>> requirement to be a value from the IANA registry.
>
> No this is not inconsistent.  Media type is always a hint... the resource itself is authoritative for its own media type.  However the value of the media type (hint or not) must follow the IANA registry.


DECISION: Reverse the order of the statements, so the normative MUST statement comes first, and the guidance being a "hint". Eran suggests using the language from the latest Web Linking draft, which suggests that there is a conflict, the actual resource media type wins.


>> 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.
>
> I don't recall, what was the use case for providing the URI by "other means"?  Is there a real case where neither URI or URITemplate would be sufficient?  Is it safe to say that one or the other MUST be present?


DECISION: Change the language to say that if the URI or URITemplate is not present, then the means of determining the link target is application-specific.

 
>> 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.
>
> I disagree, it means exactly what it says.  <Title> must not be used imply additional meaning for anyone... application, user, or otherwise.


DECISION: "The semantics of the value of this element is intended only for human display and MUST NOT be used to affect the processing of the XRD consumer."


>> 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.
>
> Is Web Linking stable enough for us to reference a specific section?


DECISION: No change due to current timing issues with Web Linking. Add a sentence that clarifies that "relation types MUST be URIs or registered relation types."


>> 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.
>
> Disagree... these are very different kinds of extensibility, and are worth separating.


DECISION: No change. These are two very different types of extensibility. Will to use his judgement.


>> 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.
>
> This section has always been one of the hardest.  Perhaps some of the language still isn't as clear as it could be?


DECISION: Add SHOULD into the processing language. Change "qualified" into "matching".

 
>> 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.


DECISION: Agree. Will will make the change.

 
>>
>> 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."
>
> Would love to get Scott's thoughts on this.


DECISION: Agree to make the change.


>
>
>> 5.2 References
>>
>> First paragraph, what does it mean to "...be included within another
>> document schema."?? Do you mean in another document instance?
>
> I agree with Patrick that it is inaccurate to say "included within another document schema".  "Document instance" is probably more accurate.


DECISION: Drop the word "schema".
 

>> 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.
>
> I don't recall when this was added... I think it may have been at Scott's suggestion?


DECISION: Lowercase the word "MAY" in this section. Try to work in a normative reference to XML dSig.


>> 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.
>
> I actually agree with this, and always felt a little weird about including this in the spec.  It is however one sentence at the very end of the spec, so it's not really *that* big a deal.


DECISION: Drop language referring to past practice. Move the normative statement up to the first paragraph, and change it to say "SHOULD include either zero or more than one XRD...".


>> 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.
>
> we've been through this, and addressed it in WD11.


DECISION: Already clarified in WD 11.

 
>
>> 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.
>
> I don't think this is the last we're going to hear about dropping <XRDS>.  I am afraid he may be right in terms of achieving interop.  I bet a LOT of libraries are simply not going to support it.


DECISION: Reference the actual XSD file for schema conformance. Secondly, explicitly state that XRDS support is optional. In section 7.1 #3 - replace "calculating" with "verified".


>
>> 7.2 Introduces without definition the notion of a "published" XRD document.
>
> agreed.  I'll change this to "provided" XRD document, since it is inline with an "XRD Provider".


DECISION: Agreed. "While signatures are optional, if they are supported, they MUST support SHA-RSA 256". This should apply to both document production and consumption. This should also be covered in section 2.


>> BTW, should add a conformance clause for XRD documents as well.
>
> I don't think that's necessary.  The conformance section is for implementations, is it not?  An implementation is either a provider or consumer of documents, not a document itself.


DECISION: Add a conformance section with a defintion of conformant documents. That section will be referenced from the other 2 conformance sections. The document conformance section will point to BOTH section 2 and the schema. Also, add a note near the start of the spec that clarifies that it is OASIS policy that schema documents are normative.



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