Discovery Change Proposal-9
DCP-9: Identifying Version of ESIP Discovery Conformance
- Progress (fill in the dates as the process moves forward)
- Submitted on: 2012-08-21
- Review period: the review period
- Revision: when revisions are being made based on feedback
- Vote: the voting period
- Final review: when final adjustments are being made and final review
- Ratified: when approved.
- Rejected: or when rejected.
- Facilitator: the primary editor to help the DCP move along the process.
As the ESIP Discovery conventions evolve, it becomes necessary for clients to understand what version of the ESIP conventions a particular server is conforming to. This Discovery Change Proposal describes how servers can advertise their conformance with one ESIP Discovery version or another.
In many cases, a client must know what version a discovery server or cast is conforming to. Features may be added (e.g., new elements in the response) or in some cases even rolled back in subsequent versions (e.g, DCP-2). Thus, clients need an easy way to identify which version a given document conforms to, be it:
- Atom response from an OpenSearch query
- Data cast
- OpenSearch Description Document
(1) The ESIP Discovery Version with which a provider complies would be identified by declaring an ESIP namespace within the root element of the document, i.e.: a) the <feed> element for Atom responses b) the <OpenSearchDescription> element for OpenSearch Description documents
(2) The namespace prefix shall by convention be "esipdiscovery".
(3) The namespace URI shall be http://commons.esipfed.org/ns/discovery/<version>/.
(4) The root <feed> element shall also include an explicit assignment of esipdiscovery:version attribute, e.g., esipdiscovery:version="1.2". This inclusion helps applications that are using off-the-shelf XML parsers, many of which resolve, and then drop, the namespaces before returning to the calling program.
(5) Thus, the opening element for an ESIP-compliant atom feed may look like:
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:esipdiscovery="http://commons.esipfed.org/ns/discovery/1.2/" esipdiscovery:version="1.2">
Likewise, the beginning of an OpenSearch Description Document would look like:
<?xml version="1.0" encoding="UTF-8"?> <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:esipdiscovery="http://commons.esipfed.org/ns/discovery/1.2/" esipdiscovery:version="1.2">
Note that the rather long "esipdiscovery" namespace is used in preference to the simpler "esip" to allow for other ESIP efforts (e.g. semantic web) to carve out their own namespaces within ESIP.
(6) The namespace URI will be dereferencible to the text describing the ESIP discovery conventions for that version.
(7) New versions should be declared within a given DCP, unless discovery change proposers want to lump several together into one version. In this case, a DCP should be authored to declare a version and refer to the other DCP's to be included within that version.
(8) This DCP, together with all DCPs approved up through 31 August 2012, shall constitute Version 1.2 of the ESIP Discovery specification.
Rationale for the Solution
Identifying versions through namespace URIs is a common practice, though the forms the versioning takes varies. The W3C, for example, uses the year in which a particular specification was adopted, e.g., http://www.w3.org/2005/Atom. Dublin core uses a mix of standard major.minor versions (e.g., http://purl.org/dc/elements/1.1/) and year/month/day (http://dublincore.org/documents/2001/10/26/dcmi-namespace/). The progress of ESIP conventions is as yet somewhat informal, making date-based versions unenlightening, so we instead gravitate toward the major.minor formulation.
The namespace prefix of "esipdiscovery" is not strictly necessary to qualify the namespace. However, since a major goal is to make the creation of ESIP discovery clients as easy as possible on the client side, we will use this convention to make it easier to "find" the version in a document, especially in languages that do not have much support for XPATH.