Home > Learn XML > XML Tutorials > XML Schema Tutorials > OASIS Catalogs for Fun and Profit

Download a Free Trial >

See What's New >

Buy Now >

OASIS Catalogs for Fun and Profit

By: Tony Lavinio, SW Architect, Principal, Stylus Studio® Team.

Understanding Catalogs

The primary reason catalogs exist is to redirect a request for a certain resource from one location to another. Typically, they are used so that schemas or modules that are on some remote machine can instead be referenced locally, either for performance or necessity (e.g. use when not connected).

One way to get around not having catalogs is to manually download the referenced document, and just use the local path. Then, for production, the files can all be edited to point to the correct location. But this is prone to error, and makes it difficult to work with existing documents in-place. And when one schema document references others, it begins to become complex.

Catalogs also map public ID strings (like "urn:oasis:names:tc:entity:xmlns:xml:catalog" or "//OASIS//DTD DocBook XML V4.2//EN") to system ID strings, which are actual URL strings (like "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd").

Catalog entries can change whole classes of URL strings by prefix substitution. So if the actual schema files were at http://www.somehost.com/somedirectory/*.dtd, but we had copied them to our C:\DTDs directory, we could do prefix substitution so that any URL that began with the string "http://www.somehost.com/somedirectory/" would have that portion stripped off and replaced with "C:\DTDs\".

And finally, catalogs can call other catalogs, by a process known as delegation. In this case, when an identifier matches, some other catalog is called to resolve it. This lets us group catalogs by purpose, and link them together.

A good overview for this is Norman Walsh's article If You Can Name It, You Can Claim It! (cached copy), but the really serious stuff is in OASIS XML Catalogs Working Draft 1.0 (Second Edition), 09 Jan 2004 (cached copy).

A Use-Case for Catalogs

How can an XML IDE like Stylus Studio® help us use catalogs effectively? Let's run through a little example:

I've got a voice-response system that uses VXML as the native configuration language, and we want to teach it just to say "Hello World!" Here's the basic XML file to do this:

But now we want to validate it, so we decide to add the following DOCTYPE:

When the validation occurs, a network access to the World Wide Web Consortium's web site must occur, which means we've got to be on-line. It also means the consumer of our document must be on-line.

Now, we might decide to make a local copy, like this:

But now we've got to remember to change it back when we're done.

Catalogs allow us to remove this mapping dependency from the documents and centralize the mapping in the catalog file. In this case, the following catalog file would map from the public ID "-//W3C//DTD VOICEXML 2.0//EN" to the physical file "vxml.dtd".

Similarly, we may have a document without a public ID, but with just the system ID, like this:

Adding a second entry to our catalog could also remap that:

Registering Catalogs in a Project

Now, how do we do this in Stylus Studio®? Create a project, and add both our XML file and our catalog file to the project. Then, right click on the catalog file in the project and select "Use Document as Catalog." Now, whenever an XML file in that project tries to resolve a public or system identifier, that catalog will be searched first.

We can have any number of catalogs present in our project, and they will be searched in the order they are listed. This way we can use the catalogs in a modular way.

After we do that, the icon next to the catalog will change, like this:

Using the DOCTYPE Syntax Sense:X Aid

One feature that is unique to Stylus Studio® is that we can connect between <public> and <system> entries that point to the same URI.

So we can begin typing <!DOCTYPE vxml PUBLIC ", and as soon as we hit that opening quote, Stylus will present us with a list of public identifiers—chosen from all of the catalogs registered, directly or through catalog references or chaining, in this project. And if we select one, the appropriate system identifier will be filled in. (If there is no corresponding <system> entry, then whatever value the <public> "uri" attribute points to will be used as the system ID.)

Navigating Catalogs

Once one or more catalogs are registered in the project, they can be navigated with the File|Open command just as if they were actually part of the file system. Any nested catalogs—whether through explicit nextCatalog directives or through delegation—are treated just like subdirectories. Public ID (), System ID (), and URI () directives each have distinguishing icons so they can be viewed. Selecting one will open the indicated physical file, even if it is nested down through several catalogs' worth of indirection.

In other words, if you have a project that looks like the one above, but the catalog.xml in it file points in turn to other catalogs, like this...

...then you can expect to see File|Open show the docbook.xml and schemas.xml catalogs as virtual folders when you use the Profile File view.

1. To illustrate, File|Open here shows our catalog as a folder.
2. Opening catalog.xml shows the catalog entries in it, with special icons indicating the various entries, and two more items for the catalogs that catalog.xml itself contains pointers to.
3. Opening one of those lets us navigate to and open the files that it in turn references, even if the containing catalog or its items are on completely different file systems.

Building Composite Catalogs

Since the introduction of OASIS Catalog support in Stylus Studio® some years ago, we have built a vast array of catalogs that point to schemas across the internet. The File|Document Wizards|Create User-defined Catalog tool allows the building of a custom catalog that contains references to any of these component catalogs. We've saved you the considerable work of tracking down the various components and bundling them together.

Converting TR9401 Catalogs to OASIS XML Catalogs

Another wizard that might be helpful is the Text Catalog to XML Catalog wizard, which converts the TR9401 catalogs that were used with SGML into the newer XML catalogs. Note that Stylus Studio® will transparently convert a text-mode catalog on the fly if you happen to reference it in your project or through another catalog, so this is primarily a convenience tool for you.

For More Information

In addition to the other links above to the OASIS Catalog standard (cached copy), some other useful references include:

• Catalog Support Video Demonstration
• Caching in with Resolvers
• Caching is Not Enough
• The Apache Cocoon Project—Entity resolution with catalogs
• Apache Commons XML Entity and URI Resolvers

Download a 15 Day Free Trial Now >

See What's New in Stylus Studio® X16 XML >

Buy Stylus Studio Now >

Stylus Most Wanted