[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]