Configuring XML Catalogs

You can add catalog files to your Document Type Association using the Catalogs tab from the Document Type dialog.

Important

<oXygen/> XML Editor collects all the catalog files listed in the installed frameworks. No matter what the Document Type Association matches the edited file, all the catalog mappings are considered when resolving external references.

Important

The catalog files settings are available for all editing modes, not only for the Author mode.

In the XML sample file for SDF you did not used a xsi:schemaLocation attribute, but instead you let the editor use the schema from the association. However there are cases in which you must refer for instance the location of a schema file from a remote web location. In such cases the catalog may be used to map the web location to a local file system entry.

In the following section it will be presented an use-case for the XML catalogs, by modifying our sdf.xsd XML Schema file from the Example Files Listings.

The sdf.xml file refers the other file abs.xsd through an import element:

<xs:import namespace=
 "http://www.oxygenxml.com/sample/documentation/abstracts" 
 schemaLocation="abs.xsd"/>

The schemaLocation attribute references the abs.xsd file located in the same directory. What if the file was on the web, at the http://www.oxygenxml.com/SDF/abs.xsd location for instance? In this case the attribute value will be:

<xs:import namespace=
 "http://www.oxygenxml.com/sample/documentation/abstracts" 
 schemaLocation="http://www.oxygenxml.com/SDF/abs.xsd"/>

There is a problem with this approach. What happens if an Internet connection is not available? How will you check the document for errors if a part of the schema is not available? The answer is to create a catalog file that will help the parser locate the missing piece containing the mapping:

http://www.oxygenxml.com/SDF/abs.xsd -> ../local_path/abs.xsd

To do this create a new XML file called catalog.xml and save it into the {oXygen_installation_directory}/frameworks/sdf directory. The content of the file should be:

<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <system 
      systemId="http://www.oxygenxml.com/SDF/abs.xsd" 
      uri="schema/abs.xsd"/>
    <uri name="http://www.oxygenxml.com/SDF/abs.xsd" uri="schema/abs.xsd"/>
</catalog>

This means that all the references to http://www.oxygenxml.com/SDF/abs.xsd must be resolved to the abs.xsd file located in the schema directory. The uri element is used by URI resolvers, for example for resolving a URI reference used in an XSLT stylesheet.

Note

The references in the XML catalog files are relative to the directory that contains the catalog.

Save the catalog file and modify the sdf.xsd file by changing its import element, then add the catalog to the Document Type association. You can do this in the Catalogs tab by pressing the New button. Enter ${frameworks}/sdf/catalog.xml in the displayed dialog.

To test the catalog settings, restart <oXygen/> and try to validate a new sample Simple Documentation Framework document. There should be no errors.