Proposal 3.0: OGDI Versioning
Author: Frank Warmerdam, 3i, firstname.lastname@example.org
Last Edited: 2001/01/03
A methdology to keep track of OGDI specification version supported, and
extensions supported is introduced via the UpdateDictionary() calls.
To establish a standard mechanism for OGDI clients to identify the version
of the OGDI specification supported by a server (driver), and to identify
standard, and non-standard extensions supported by the server.
The cln_UpdateDictionary() call will be used to fetch one of two documents,
one describing the version of the server, and one containing a list of
extensions. The documents are returned as flat text with a defined format.
The version is a textual representation of a numerical version number.
Each legal version number will be defined by the 3i, with an associated
specification document indicating the requirements for claiming to support
Version numbers will be decimal values (such as "3.0", "3.1"), where a
higher version number always implies that all capabilities of previous
versions are supported. (This may be violated when the major version changes,
for instance a switch from 3.x to 4.x). The version numbers will always be
numerically comparable, so 3.10 is really just 3.1. If we want to have
minor versions after 3.9 we might number them 3.91 rather than 3.10.
The version is fetched by passing the string "ogdi_version" to the
If the returned document does not match the regular expression
"[0-9]+.[0-9]+" then the returned value should not be treated as a version.
This is to ensure that pre 3.0 servers which return something from
cln_UpdateDictionary() regardless of the argument are still handled properly.
The extensions supported by a server are returned as a textual document.
The document contains a list of extension identifiers separated by a single
space. The presence of the extension identifier indicates that this server
(at least for the current datastore) supports the indicated extensions.
The extension identifiers will conform to the following restrictions:
A possible example return result might be:
- Identifiers only contain the characters a-z, 0-9, '_', '-', '.'. Note
only lower case to avoid case sensitivity issues.
- Identifiers may only have the prefix "ogdi_" if issued by the 3i as
standard predefined extensions.
- Other vendors may create their own extension identifiers. To guarantee
no collisions, vendors may prefix the extension with a DNS domain they
control in reversed order. For instance "com.cubewerx.". Vendors will
avoid using a prefix that is currently, or could ever be, a valid DNS
The extensions will be fetched via the cln_UpdateDictionary() call with
an argument of "ogdi_extensions".
Essentially the same information is returned, still via cln_UpdateDictionary()
but the version and extensions information are merged into one document, and
the document is in XML format. If this approach is desired I can prepare a
simple DTD and examples descibing the format. A potential example might be:
While not strictly necessary, I would also suggest the OGDI reference API
be extended for the convenience of application programmers. It would:
- Cache version and extension information in the ecs_Client structure.
- Provide a cln_GetVersion() function to return the version as a double.
- Provide a cln_CheckExtension(const char *) call to return TRUE or FALSE
indicating if a given extension is supported.
Servers not returning a valid version to a cln_UpdateDictionary("ogdi_version")
request should be presumed to be pre-versioning servers, and thus would also
not generally support the cln_UpdateDictionary("ogdi_extensions") call.
We need to define what our initial version number is. I would suggest we
call the old core people have been using for a couple of years 3.0, and
define the "ogdi_version", and "ogdi_extensions" protocol as part of a "3.1"
Because we use cln_UpdateDictionary() to transport the information, we aren't
requiring any changes to the GLTP protocol, nor necessary changes to the
OGDI API. This should mean that drivers, and clients can be easily upgraded
with minor changes, and not requiring incorporation of any actual source
code from 3i.
Even if we choose to use the CubeWerx "GetCapabilities" approach, and want
to incorporate version and extension information in that returned document,
I would suggest that we still try to utilize similar semantics to those in
In general, I also feel that we should use the cln_UpdateDictionary() call
as a mechanism to transport assorted metadata back from servers, with
special argument values having assorted semantics. Furthermore, I suggest that
values prefixed with "ogdi_" be reserved for standardization by the 3i.