Re: Updated URI Template proposal

On 11/7/07, James M Snell <jasnell@gmail.com> wrote:
>
>
> The main use case is to allow standardization and disambiguation of
> varnames.  You can look at OpenSearch for an example of this in the real
> world.  Local names are indeed more readable, but they can be ambiguous.


Exactly.

OpenSearch -- as one example of a real-world format -- depends on:

 a)  names with universally defined semantics, such as "searchTerms",
"startIndex", "count", etc.  and,
 b)  names with locally defined semantics, such as application ids, start
and end dates, addresses, etc.

As an example of (a), consider the template for the Yahoo search API (line
breaks for legibility):

 http://search.yahooapis.com/WebSearchService/V1/webSearch
<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>
     ?query={searchTerms}&results={count}&start={startIndex}
<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>

In the context of OpenSearch templates, the semantics of the local names,
such as "searchTerms", "startIndex", "count", etc., are well known.

As an example of (b), consider the following extended URL template:

  http://search.yahooapis.com/WebSearchService/V1/webSearch<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>
    ?appid={yahoo:appid}&query={searchTerms}&results={count}
<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>
    &start={startIndex}<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>

Here the qualified name "yahoo:appid" has semantic meaning because it
appearance in a context where the "yahoo" prefix is explicitly mapped to a
meaningful namespace.  With OpenSearch templates, that mapping is done via
XML namespaces.

E.g.:

  <Url xmlns:yahoo="http://developer.yahoo.com/search/web/V1/webSearch"
        template="http://search.yahooapis.com/WebSearchService/V1/webSearch<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>

?appid={yahoo:appid}&query={searchTerms}&results={count}<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>

&start={startIndex}<http://search.yahooapis.com/WebSearchService/V1/webSearch?appid=YahooDemo&query=madonna&results=2>"/>


That it to say, clients and servers assign semantic meaning to the qualified
name around the fully qualified name based in the XML namespace declaration.


And to be really accurate, even the default semantic context (for
"searchTerms", "count", etc.) comes from the container's default namespace (
i.e., "http://a9.com/-/spec/opensearch/1.1/<http://a9.com/-/spec/opensearch/1.1/>"),
so it really isn't "universally" meaningful at all.

Now to be fair, many people have expressed distaste for how the namespace to
prefix mapping is based entirely on an XML container's namespace
declarations.   That could change in future iterations of OpenSearch, but
I'm not sure the use of qnames in parameters should go away entirely.  I
personally prefer the short notation of the "prefix:name" approach.  Though
this implies that there is some acceptable way of mapping prefixes to
namespaces, and there is much debate about what constitutes "acceptable."

...

The challenge that I see is that the URI Template draft is designed to make
the template string stand on its own.   We need to pack a whole lot of
information into one string as is.  And this only gets when we start trying
to define conventions here for namespaces and prefixes when we don't allow
for additional context.

I'm certainly *not* saying that we should couple this specification to XML
namespaces.  On the contrary, we may want to just agree to keep all of that
out of the spec, and simply say that "the template-var token is opaque and
interpretation is defined by the application".

Joe, please note that, if we agree on this, then the production of
"template-char" should include the ":" character.

...

Hmm, that was a long winded way of saying that qualified names, prefixes,
and whatnot, are all out of scope.   I just can't see a way to include it
all elegantly in a single string.  (But would certainly enjoy being shown
otherwise.)


-DeWitt