doc.devdocs.namespaces.html Maven / Gradle / Ivy
Show all versions of fcrepo-client Show documentation
Namespace Specification & Design Rationale Fedora-Mellon Project
$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.
A. Implicit Namespaces and Versioning
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.
B. References
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.
C. Revision History
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