Working with XML Catalogs

An XML Catalog maps a system ID or a 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 (such as referenced schemas and stylesheets), the use of an XML Catalog becomes a necessity when Internet access is not available or the Internet connection is slow.

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

  1. OASIS XML Catalogs Committee Specification v1.1.
  2. 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, 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 catalog elements systemSuffix and uriSuffix.

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

Table 1. Catalog Mappings
Document Referenced 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):
  1. resolve the schema using URI catalog mappings.
  2. 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).

  3. resolve the root namespace using URI catalog mappings.
Relax NG
Schematron
NVDL
XSL XSL/ANY URI
CSS CSS URI
XML Schema XML Schema
The following strategy is used (if one step fails to provide a resource, the next is applied):
  1. resolve schema reference using URI catalog mappings.
  2. 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).

  3. 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

Creating an XML Catalog with a Template

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

<?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>

How Oxygen XML Editor Determines which Catalog to Use

An XML catalog is used to resolve references for document validation and transformations and it maps such references to the built-in local copies of the schemas of the Oxygen XML Editor frameworks (DocBook, DITA, TEI, XHTML, SVG, etc.)

Oxygen XML Editor includes a built-in catalog set as default, but you can also create your own and Oxygen XML Editor looks for catalogs in the following order:

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 this:

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