Re: [xri] Quick overview of descriptor discovery flow

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

Title: Re: [xri] Quick overview of descriptor discovery flow

The ‘syntax’, ‘vocabulary’, and ‘scheme’ attributes are far from an actual proposal, and have not been discussed much (i.e. I’m the committee). It really boils down to where the definition of Link-Template is included and how generic it needs to be.

‘syntax’ is important because there is no standard for URI templates but we expect to have at least one in 1-2 years. But we can omit it and let future extensions override the default syntax.

‘vocabulary’ is almost always application specific and we can define the proposed one as specific to ‘describedby’. Again, it can be set as the default and the attribute can be added later on when someone has an alternative.

‘scheme’ is needed to differentiate between the vocabulary of http URIs and mailto URIs (or anything else). It is not needed if the only variable defined is ‘uri’ (that is, no domain, username, etc.).

So there is much to be discussed about the structure of the Link-Template record... But the idea is that this example is as complex as it is going to get, so it gives you a complete idea of how it will work. We might very well move some of the configuration to implied assumptions.

EHL


On 12/15/08 1:53 PM, "Dirk Balfanz" <balfanz@google.com> wrote:

> On Mon, Dec 15, 2008 at 12:55 PM, Eran Hammer-Lahav <eran@hueniverse.com> wrote:
> > The following method describes how to perform R-URI --> D-URI: finding the descriptor URI from the resource URI. The process starts with a resource URI. It doesn't matter how that URI has been obtained. In the examples below, 'D-URI' is used to indicate the placeholder containing the desired descriptor URI.
> >
> > 1. Method selection
> >
> > The consumer (entity performing discovery) has three options based on information available to it with regard to the resource:
> >
> > * If the resource is known to be an HTML or ATOM document, and the document has been and will be retrieved via HTTP GET either way, the consumer can look for <Link> elements:
> >
> >     <Link href=""D-URI"" rel="describedby" type="application/xrd+xml">
> >
> > * If the resource is going to be retrieved via HTTP GET/HEAD, the consumer can look for Link: headers:
> >
> >     Link: <D-URI>; rel="describedby"; type="application/xrd+xml"
> >
> > * If the first two options are not applicable, the consumer obtains the /site-meta document for the resource's domain. The consumer may request an XRD representation but must be able to parse the text representation. It is not clear if there is real value in offering an XRD representation of /site-meta (please discuss).
> >
> > Text:
> >
> >     Link-Template: <http://example.com?meta={+uri} <http://example.com?meta=%7B+uri%7D> >; rel="describedby"; type="application/xrd+xml"; syntax="plain"; vocabulary="uri"; scheme="mailto http"
>
> I'm probably a bit late to the party, but are these really all necessary? Especially the "syntax" and "vocabulary" pieces smell of design by committee. Won't we in practice just all use vocabulary=uri? Also, enumerating the possible schemes seems like a pain in the neck. Why can't the servlet serving the XRD branch on the scheme, instead of putting this in site-meta?
>
> Dirk.
>  
> > XRD:
> >
> >     <XRD>
> >         <Link>
> >             <Rel>describedby</Rel>
> >             <MediaType>application/xrd+xml</MediaType>
> >             <TemplateURI syntax="plain" vocabulary="uri">http://example.com?meta={uri}</ <http://example.com?meta=%7Buri%7D%3C/> TemplateURI>
> >             <site-meta:scheme>mailto http</site-meta:scheme>
> >         </Link>
> >     </XRD>
> >
> > The 'plain' template syntax means simple substitution of {variable}s. If the variable name is prefixed with a '+', it must be percent-encoded prior to substitution. The 'uri' template vocabulary includes: uri, scheme, authority, domain, port, path, query, fragment, and username.
> >
> > Using the template, the consumer construct the D-URI from the R-URI.
> >
> >
> > EHL
> > Ps. The above syntax for /site-meta is the expected format in the next draft. This flow does not use the regular Link records in /site-meta as those are used for the entire site (an abstract concept) and not for individual resources. There is no such URI identifying the "site".