In his post, Sam also brings up two very important questions regarding the OpenSearch 1.1 format.
The first question pertains to the use of Qualified Names as an extensibility mechanism in attribute values. OpenSearch 1.1 uses QNames in the
role attribute of the Query element, and also in the substitution rules for URL template parameters.As Mark has pointed out, while the use of QNames in attribute values is technically correct, (insofar as there is enough context to uniquely resolve each value), there are legitimate questions about the practicality of doing so. Like many people familiar with the subject, Sam and Mark both advocate for the use of fully qualified URIs, rather than the abbreviated approach taken with QNames.
By way of comparison, here are two example URL templates, each using a custom template parameter. The first example is written using QNames, as is specified in OpenSearch 1.1 Draft 3:
<Url type="application/rss+xml"
xmlns:example="http://example.com/opensearchextensions/1.0/"
template="http://example.com?q={searchTerms}&c={example:color?}"/>
You'll observe that the extended parameter is written as simply "
example:color". This is a concise, compact representation, which can be fully qualified by mapping the "example" prefix back to a namespace URI via the "xmlns" attribute on the containing XML content.Versus this example, which uses explicit fully-qualified URIs to perform the mapping:
<Url xml:base="http://a9.com/-/spec/opensearch/1.1/"
type="application/rss+xml"
template="http://example.com?q={searchTerms}&c={http://example.com/opensearchextensions/1.0/#color?}"/>
The latter approach is also unambiguous, but has the significant advantage that the parser can interpret the meaning of each template parameter without (much) access to the surrounding XML context.
(Note that I'm being a bit pedantic by including the "xml:base" attribute, but I do so to point out that even URI-based attributes often are not fully qualified without a bit of surrounding XML context.)
The position advocated by those worried about using QNames in attribute values is that a) attribute values and the XML container should be considered orthogonal, and thus b) the attribute parser should not be required to be aware of the XML namespace mappings. Indeed, as many attribute parsers do not have access to the xml namespace prefix mappings, there are scenarios in which QNames are a practical impossibility. As a result, many clients are implemented by hard-coding the prefix, which is undeniably broken.
In that sense, the "URIs not QNames" camp is totally, 100% correct.
And yet I made the conscious decision to use QNames when writing the OpenSearch 1.1 specification. I did this partly out of a sense of aesthetics, insofar as I realized that the more intuitive and "cleaner" the spec was, the more likely people would be to use it. This is particularly evident when one has many extended values in a single template, as is a strong possibility in scenarios such as this one.
For better or for worse (better, I think), the 1.1 specification is now being used in enough shipping code that it would be unreasonable to make such a highly incompatible change at this point. (Not that Sam is advocating for that, I believe he is just pointing out an important point for open debate.) That said, if there is ever another version of OpenSearch, I would probably not press a strong case for QNames, and would likely side instead with guys like Sam and Mark.
The second thing that Sam observes is that mixed-case element names is a leading cause of invalid feeds. The OpenSearch description document uses mixed case element names.
I concur completely with Sam here. If I had to do it all over again I would have used lowercase names consistently everwhere. Again, that was a decision made for aesthetic reasons, but one that I never anticipated mattering as much as it did, as I never really planned for the description documents to be such an important part of the specification.
Truth be told, I'm amazed that the format has lived up to the scrunity as well as it has. Just to have people like Sam and Mark and everyone else give OpenSearch 1.1 a passing grade is still quite a thrill in itself.
Note that there is still time to make some minor changes to OpenSearch 1.1 before it goes final. I will work out the best places to make your proposals, though it is important to keep in mind that high profile code is shipping using the existing draft. Thus we would need to limit our changes to the small scope of things that do not materially impact existing servers or clients. In that sense, changing the handling of extended template parameters is probably off the table, though I suspect we might be able to make the change for the "role" attribute on the Query element without breaking many applications.
Many thanks again to Sam for wrapping his brain around this. Sam and I have been IM'ing back and forth non-stop for the past several weeks, demonstrating to me once again how important it is to stop and listen to those willing to take the time to mentor you. Sam is a particularly good teacher, and I am happy that he has taken such an interest in this work.