Working with XML Catalogs

An XML Catalog maps a system ID or an URI reference pointing to a resource (stored either remotely or locally) to a local copy of the same resource. If XML processing relies on external resources (like referred schemas and stylesheets, for example), the use of an XML Catalog becomes a necessity when Internet access is not available or the Internet connection is slow.

Oxygen XML Editor plugin supports any XML Catalog file that conforms to one of:

OASIS XML Catalogs Committee Specification v1.1
OASIS Technical Resolution 9401:1997 including the plain-text flavor described in that resolution

The version 1.1 of the OASIS XML Catalog specification introduces the possibility to map a system ID, a public ID or a URI to a local copy using only a suffix of the ID or URI used in the actual document. This is done using the new catalog elements systemSuffix and uriSuffix.

Depending on the resource type, Oxygen XML Editor plugin uses different catalog mappings.

Table 1. Catalog Mappings
Document	Referred Resource	Mappings
XML	DTD	system or public The Prefer option controls which one of the mappings should be used.
	XML Schema	The following strategy is used (if one step fails to provide a resource, the next is applied): resolve the schema using uri catalog mappings. resolve the schema using system catalog mappings. This happens only if the Resolve schema locations also through system mappings option is enabled (it is by default); resolve the root namespace using uri catalog mappings.
	Relax NG
	Schematron
	NVDL
XSL	XSL/ANY	uri
XML Schema	XML Schema	The following strategy is used (if one step fails to provide a resource, the next is applied): resolve schema reference using uri catalog mappings. resolve schema reference using system catalog mappings. This happens only if the Resolve schema locations also through system mappings option is enabled (it is by default); resolve schema namespace using uri catalog mappings. This happens only if the Process namespaces through URI mappings for XML Schema option is enabled (it is not by default);
Relax NG	Relax NG

An XML Catalog file can be created quickly in Oxygen XML Editor plugin starting from the two XML Catalog document templates called OASIS XML Catalog 1.0 and OASIS XML Catalog 1.1 and available in the document templates dialog.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catalog 
      PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN" 
      "http://www.oasis-open.org/committees/entity/release/1.1/catalog.dtd">

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

    <!-- Use "system" and "public" mappings when resolving DTDs -->
    <system 
          systemId="http://www.docbook.org/xml/4.4/docbookx.dtd" 
          uri="frameworks/docbook/4.4/dtd/docbookx.dtd"/>     
    <!-- The "systemSuffix" matches any system ID ending in a specified string -->
    <systemSuffix 
          systemIdSuffix="docbookx.dtd" 
          uri="frameworks/docbook/dtd/docbookx.dtd"/>

    <!-- Use "uri" for resolving XML Schema and XSLT stylesheets -->
    <uri 
          name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" 
          uri="frameworks/docbook/5.0/rng/docbookxi.rng"/>

    <!-- The "uriSuffix" matches any URI ending in a specified string -->
    <uriSuffix 
          uriSuffix="docbook.xsl" 
          uri="frameworks/docbook/xsl/fo/docbook.xsl"/>

</catalog>

Oxygen XML Editor plugin comes with a built-in catalog set as default, but you can also create your own one. Oxygen XML Editor plugin looks for a catalog in the following order:

user-defined catalog set globally in the XML Catalog preferences page;
user-defined catalog set at document type level, in the Document Type Association preferences pages;
built-in catalogs.

An XML catalog can be used to map a W3C XML Schema specified with an URN in the xsi:noNamespaceSchemaLocation attribute of an XML document to a local copy of the schema.

Considering the following XML document code snippet:

<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1">

The URN can be resolved to a local schema file with a catalog entry like:

<uri name="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
    uri="topic.xsd"/>