Changes to WD07

[Eran Hammer-Lahav <eran@hueniverse.com>]

NOTE: Please continue to review WD07 and provide feedback. There should only be one more draft to incorporate feedback and move directly to a vote. This means you should keep track of this thread but continue to read the latest draft and list any issues found. The next draft you will see will be for a committee vote.

---

I have made two changes to the draft (since WD07) and want to bring up another issue found. The two changes are:

* Clarified that the <Rel> value is a single relation type and is different from HTML and HTTP which allow space-delimited values.
* Removed the default template syntax ({var} and {%var}) and made the syntax and vocabulary based on the combination of the application and relation type.

-- Templates

I made the template change because the proposed syntax was incompatible with the template syntax proposed by Roy Fielding and somewhat broken. RFC 3986 contains three types of characters: reserved, unreserved, and everything else. Everything else must always be encoded (which is not the care in my earlier proposal when % is not used). The other two modes are to encode the reserved characters or not. In Roy's proposal, the default is to encode but leave the reserved characters as-is when the variable name is prefixed with a +. The proposal has a lot more features but this is the most basic subset needed and also the most stable part.

I removed the previous syntax because it was broken. I didn't replace it with the new {+var} syntax because I am not sure it is appropriate given that we only have a single use case for templates at this point (host-meta). I can quickly add it back but take a look at the new language and let me know what you think:

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

I don't think we should have a default syntax anymore, but we should define *a* syntax so that other applications can use as a reference (since we know they will need something and the RFC will not be ready for a while). The question is, should XRD provide this (as a separate section of Appendix) or should host-meta (which is the only use case I have). Either way, applications will be able to reference it.

-- Link Subject

The current definition of <Link/Subject> is broken:

"When <Subject> appears as a child element of a <Link>, it identifies the linked resource.  This asserts the value that should be expected for the <Subject> in the XRD of the linked resource."

In WD06 it used the term 'linked XRD' instead of 'linked resource'. This was a critical distinction since it limited <Link/Subject>'s meaning only for linked-XRD. However, since we no longer define linked XRD, the link level subject is no longer defined. The way it is currently written doesn't work for linked XRDs.

Consider this example:

<XRD>
	<Subject>http://example.com/resource/1</Subject>
	<Link>
		<Rel>example</Rel>
		<URI>http://example.com?fetch=2</URI>
		<Subject>http://example.com/resource/2</URI>
	</Link>
</XRD>

Regardless of the media type of http://example.com?fetch=2, the subject is not about anything in that resource, but in its XRD document (which will be linked to it using an HTTP header). If http://example.com?fetch=2 is a linked XRD, the subject is not what is in this XRD but in another XRD that describes the http://example.com?fetch=2 resource (which just happens to be an XRD).

Because we don't allow XRD elements to be reused where they don't belong, we can't drop the <Link/Subject> from the schema and let it be an extension. But we need to figure out how to define it. I don't have a general purpose definition. It only has any meaning if the linked resource is an XRD document. We can simply say that but without some extra prose, it will probably confuse people who were not part of the trust and linked-XRD discussion.

Any suggestions?

EHL