Understanding XML catalogs: what they are, why they are used, andwhere

["Costello, Roger L." <costello@mitre.org>]

Hi Folks,

I am just learning to use XML catalogs. Below is what I've learned. Are there any errors in the below description?  /Roger

----------------------------------------------------------------
        WHY USE CATALOGS?
----------------------------------------------------------------
Here's an example which motivates the need for catalogs.

This XML document has an XSLT processing instruction (PI) that references a stylesheet at a URL:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="http://www.xfront.com/catalog-test/bookstore.xsl";?>
<bookstore>
    ...
</bookstore>

If you are not connected to the Internet then the XSLT PI will fail. Catalogs enable you to specify:

   Hey XSLT processor, instead of using the XSLT document at
   the URL specified in the XSLT PI, use this _____ local copy.

XML catalogs provide a convenient way to identify where resources--such as XSLT stylesheets--are located. No more hardcoded links.

Norm Walsh has a good description of the value of catalogs:

http://xml.apache.org/commons/components/resolver/resolver-article.html


----------------------------------------------------------------
        WHAT ARE CATALOGS?
----------------------------------------------------------------
A catalog is an XML document. OASIS has defined the format of catalogs:

http://www.oasis-open.org/committees/download.php/14810/xml-catalogs.pdf

Here's an example of a catalog:

<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

    <system systemId="http://www.xfront.com/catalog-test/bookstore.xsl"; 
            uri="bookstore.xsl"/>

</catalog>

The <system> element says, 

    Map the entity with the system ID:

        http://www.xfront.com/catalog-test/bookstore.xsl

    to the URL:

       bookstore.xsl

In other words, this instructs the XSLT processor to use the local copy of bookstore.xsl, rather than the remote copy.


----------------------------------------------------------------
        HOW ARE CATALOGS USED?
----------------------------------------------------------------
Create an external entity and then use that entity rather than hardcoding the URL:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookstore [
    <!ENTITY xslt-file SYSTEM "http://www.xfront.com/catalog-test/bookstore.xsl";>
]>
<?xml-stylesheet type="text/xsl" href="&xslt-file;"?>
<bookstore>
    ...
</bookstore>

Notice that I created an external entity, xslt-file, and associated it with the URL, http://www.xfront.com/catalog-test/bookstore.xsl 

    <!ENTITY xslt-file SYSTEM "http://www.xfront.com/catalog-test/bookstore.xsl";>

Then, in the XSLT processing instruction I used the entity:

    href="&xslt-file;"


----------------------------------------------------------------
        WHERE ARE CATALOGS USED?
----------------------------------------------------------------
Wherever links are used, you can use catalogs. Above we saw that catalogs can be used with stylesheet PIs.

Within an XSLT document you may have <include> and <import> elements. They use links. You can use catalogs with them:

<?xml version="1.0"?>
<!DOCTYPE bookstore [
    <!ENTITY include-file SYSTEM "http://www.xfront.com/catalog-test/toUpperCase.xsl";>
    <!ENTITY import-file SYSTEM "http://www.xfront.com/catalog-test/toLowerCase.xsl";>
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
                version="2.0">

    <xsl:include href="&include-file;"/>
    <xsl:import href="&import-file;"/>"/>

    ...
</xsl:stylsheet>

Notice that in the <include> and <import> elements I used entity references, rather than hardcoding a URL. Now I can use a catalog to map the URL to a local copy of the XSLT documents, if I desire.

There are other places within an XSLT document where catalogs can be used, such as with the document() and doc() functions:

<?xml version="1.0"?>
<!DOCTYPE bookstore [
    <!ENTITY doc-file SYSTEM "http://www.xfront.com/catalog-test/FitnessCenter2.xml";>
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
                version="2.0">
    ...
    <xsl:variable name="FitnessCenter" select="doc('&doc-file;')" />
    ...
</xsl:stylsheet>

Notice that in the doc() function I used an entity reference, rather than hardcoding a URL. 

An XML file that references an XML Schema using schemaLocation is another place where catalogs can be used:

<?xml version="1.0"?>
<!DOCTYPE bookstore [
    <!ENTITY xsd-file SYSTEM "http://www.xfront.com/catalog-test/BookStore.xsd";>
]>
<BookStore xmlns="http://www.books.org";
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
           xsi:schemaLocation=
                          "http://www.books.org
                           &xsd-file;">
        ...
</BookStore>

Notice that in the schemaLocation attribute I used an entity reference, rather than hardcoding a URL.

Note: not all XSLT processors and not all XML Schema validators support catalogs.


----------------------------------------------------------------
        HOW ARE CATALOGS USED WITH SAXON?
----------------------------------------------------------------
The SAXON Wiki has a good description of how to use catalogs with SAXON:

http://sourceforge.net/apps/mediawiki/saxon/index.php?title=XML_Catalogs