$Id: namespaces.html 3506 2005-01-27 05:12:37Z eddie $
Table of Contents
The first part of the identifier for Fedora namespaces is the publication url, http://www.fedora.info/ The URL identifies the project, and the project team has indefinite control over the hostname, so this works to
uniquely identify the software, and
ensure the URL won't change
Further, the namespace identifiers have their own common path in the URL that is separate from the website so that
we logically separate Fedora namespace URIs from Fedora website URLs, and
this leaves open the option to use something like RDDL to describe (in human and machine-readable form) the XML resources related to the Fedora application without colliding with the Fedora site's web pages.
The path is definitions/. So now we have http://www.fedora.info/definitions/
Next, we recognize that Fedora will be versioned, and with this will likely come new/different items and meanings. To keep things simple and intuitive, we will version the namespaces (and identifiers) along with releases of the Fedora software. We use the major and minor version identifiers in the next part of the namespaces' URIs. In a namespace URI, we use the "/" character to separate the major and minor parts of the version identifier. Thus, the remaining portion of a URI becomes M/m, where M is "major version number" and m is "minor version number". Following this specification, the beginning of the namespace identifiers for the first major release of Fedora is http://www.fedora.info/defintions/1/0/
To avoid name collision, and to expose only those names necessary to converse and/or develop around a particular logical part of Fedora, we have grouped the names into the following namespaces:
api/ - WSDL definitions and SOAPAction header names for API-A or API-M operations.
auditing/ - The types/elements defined in the XML Schema for audit records. This is based on the UVA digiprov schema.
binding/ - The types/elements defined in the XML Schema for binding specifications.
javadoc/ - The java source code documentation; one namespace per class (see below).
types/ - The types defined in the XML Schema used for specifying API-A and API-M requests and/or responses.
In accord with the specifications above, we explicitly define the following namespaces for the first release of Fedora:
http://www.fedora.info/definitions/1/0/api/ - The web service API (WSDL-based) for version 1.0 of Fedora. There is a name entry in this namespace for each of the SOAPAction header names defined by version 1.0 of Fedora.
http://www.fedora.info/definitions/1/0/auditing/ - The audit trail XML Schema types/elements as defined by version 1.0 of Fedora.
http://www.fedora.info/definitions/1/0/binding/ - The binding specification XML Schema types/elements as defined by version 1.0 of Fedora.
http://www.fedora.info/definitions/1/0/javadoc/ - The api documentation for the source code of version 1.0 of Fedora (one namespace per class). Java has it's own namespace identifiers built-in (based on package.package.package.class). The Fedora javadocs namespaces follow that convention, except they start at http://www.fedora.info/definitions/majorVersion/minorVersion/javadoc ... and the individual namespace for the javadoc of each package is package/package/ClassName.html. Names in each class' namespace (methods and fields) are designated by packageNamespace#name(param1Type, param2Type) For instance, the namespace for the documentation of the Server class for release 1.0 is http://www.fedora.info/definitions/1/0/javadoc/fedora/server/Server.html, and the getHomeDir() method is fully qualified as: http://www.fedora.info/definitions/1/0/javadoc/fedora/server/Server.html#getHomeDir().
http://www.fedora.info/definitions/1/0/types/ - The other XML Schema types/elements necessary to support API requests and responses as defined by version 1.0 of Fedora.
For convenience, we say that the following namespaces are implied by the above:
http://www.fedora.info/definitions/1/api/
http://www.fedora.info/definitions/1/auditing/
http://www.fedora.info/definitions/1/binding/
http://www.fedora.info/definitions/1/javadoc/[...]
http://www.fedora.info/definitions/1/types/
These identify the namespaces for "the latest minor version of the version 1 release of Fedora".
http://www.fedora.info/definitions/api/
http://www.fedora.info/definitions/auditing/
http://www.fedora.info/definitions/binding/
http://www.fedora.info/definitions/javadoc/[...]
http://www.fedora.info/definitions/types/
These identify the namespaces for "the latest major and minor version of Fedora".
Implicit namespace identifiers are useful in specification documents and discussion, but we always use explicitly versioned identifiers in code and recommend that developers/integrators using Fedora use explicitly versioned namespace identifiers.
http://www.w3.org/TR/REC-xml-names - W3C Recommendation on XML Names
http://www.xml.com/pub/a/2001/02/28/rddl.html - Answering the Namespace Riddle - An Introduction to the Resource Directory Description Language
http://www.rddl.org/ - XML Resource Directory Description Language - Formal Description
http://lists.xml.org/archives/xml-dev/200103/msg00995.html - Eric van der Vlist's description of Examplotron's scheme for implicit namespace identifiers.
http://lists.xml.org/archives/xml-dev/200105/msg00068.html - Tony Coates' point: Why applications should not embed general version ids.
The history of this document follows.
$Log$
Revision 1.1 2005/01/27 05:12:36 eddie
moved all devdoc-related files to src/doc/devdocs,
edited buildfile accordingly
translated docbook to html and deleted the dbx files
Revision 1.3 2002/09/11 11:17:20 cwilper
Added ..javadoc/... namespaces description
Revision 1.2 2002/07/18 20:07:00 cwilper
changed 'actions' namespace to 'api' because it's more sensible
Revision 1.1 2002/07/16 16:26:14 cwilper
First import of namespaces spec/design doc, converted to docbook from txt