What is a Catalog?

After version 0.9.2 DIGGSML was split into several parts to aid its development and there have been some problems with using the schemas in various different parsers, many stemming from the xsi:schemaLocation attribute and it's varied implementation.

Prior to 0.9.2 DIGGSML used relative paths to locate the schemas with respect to each other, the problem with using relative paths is that the location of schemas using relative paths is done differently in different parsers, the main problem being that referencing the same schema from different places within the hierarchy requires different relative paths to locate that schema dependent on the document the reference is in, this is not allowed since some parsers require all hints to be correct. Initially relative paths were used because this was the way GML 3.1.1 referenced its schemas however these problems have been publicly criticised by Simon Cox, one of GMLs authors, when he posted his own catalog file (line 28) for use in the GeoSciML wiki.

A more correct way of referencing the various schemas together is to use an Oasis XML Catalog, supported by all major validators this catalog file enables the DIGGSML instance document to use semantic URI's to identify its schema locations and give instruction to the validator on how to map these URI's to local files, this also allows the DIGGSML project to use meaningful paths within the schemas to link them together internally.

These canonical URI's are simply identifiers, not file locations, but a side effect of using these URI's is that they can be real file locations on the internet, allowing the use of DIGGSML without a local copy.

The process is such, when a parser finds a URI it should first look in the catalog and see if that URI is mapped anywhere, if that mapping locates a file that file is used. If this URI is not mapped the URI itself is used as a hint to find the file, that is not a path, just an indicator that the file might be where the URI points.

The structure of the DIGGSML catalog is very small, requiring only one mapping since all of the DIGGSML schemas reside under a common directory hierarchy.

The lines of interest in catalog.xml are:

<!-- rewriteURI's -->
<rewriteURI uriStartString="http://www.diggsml.org/schemas/0.9.2/" rewritePrefix="file:///c:/svn/diggs/trunk/source/schemas/"/>
<!-- rewriteSystem's too-->
<rewriteSystem rewritePrefix="file:///c:/svn/diggs/trunk/source/schemas/" systemIdStartString="http://www.diggsml.org/schemas/0.9.2/" />

This snippet illustrates that the http://www.diggsml.org/schemas/0.9.2/ URI should map to file://localhost/c:/svn/diggs/trunk/source/schemas/ which is the folder on my development machine that contains my schemas.

In order to use the catalog this file://localhost/c:/svn/diggs/trunk/source/schemas/ path will need to be customized for your specific installation of DIGGSML.

Customizing the Catalog

First, you will need to know where your local DIGGSML schemas are located. For this example I'll assume you have extracted the Schema distribution file in the C:\DIGGS\0.9.2 directory.

In order to specify the schema location correctly in the catalog you need to construct a replacement URI to locate the schema. Where the files are located on your local machine this URI will always start with file:/// (note triple /, not double as you would expect). Next we add the drive letter, c:. Then the path to the schema files themselves diggs/0.9.2/schemas/, it's important to note that since this is a URI you must use / not \ as the directory separator. It is also important to note that since this is a prefix and refers to a directory, a trailing / is important.

Putting these all together we have a new URI of file:///c:/diggs/0.9.2/schemas/.

You will also need to modify the four earlier lines in the catalog file, in order for the validator to find the definition of the schema for the catalog itself. Apply the same principals to the uri attribute of the <uri> and <system> elements listed in the file to allow the parser to locate the catalog.dtd and catalog.xsd files.

Using the Catalog

Once you have modified your catalog file to include your local URI you must tell your parser to reference that catalog, this process is slightly different for each system but I'll include some common examples.

Altova XMLSpy 2008

XMLSpy contains a "CustomCatalog.xml" file in the program folder, to use your custom catalog you must open this "CustomCatalog.xml" and add a "nextCatalog" line in between the <catalog> and </catalog>.

The format of the nextCatalog line is also dependent on the location of your DIGGS schemas, modify the following example so the catalog attribute includes the URI of your catalog.xml file:

<nextCatalog catalog="file:///c:/svn/diggs/trunk/source/schemas/catalog.xml"/>

Where the catalog attribute is the URI of your catalog file (not your replacement URI).

Previous versions of Altova XMLSpy

Note that in Altova XMLSpy versions prior to 2008 the nextCatalog tag was not recognised. This can be worked around by including the contents of the modified catalog.xml included with the DIGGS release inside the Altova CustomCatalog.xml

Stylus Studio

Add your catalog to your project, select it in the Project window, Right-click on it and select "Use Document as Catalog"

Oxygen XML

On the menu pick "Options" then "Preferences..."
Expand "XML" in the tree
Pick "XML Catalog"
Pick "New" on the right hand side
Browse to your Catalog file

jEdit with the Xerces Plugin

On the menu Pick "Plugins" then "Plugin Options..."
Expand "XML" in the tree
Pick "Catalogs"
Press the + button
Browse to your Catalog file

Using xjParse at the Command Line

Simply include -c "c:\diggs\0.9.2\source\schemas\catalog.xml" on the command line.

Others

You can find more information about using XML Catalogs in various editors on the GeoSciML wiki.

There we have it, you should now be able to validate and parse DIGGSML in any parser without having incurring slow loading times or having to pull the schemas from the internet every time you validate a file.