Edit online

Working with XML Catalogs

Oxygen XML Author uses XML Catalogs to resolve references for validations and transformations and they are especially helpful for resolving external resources when internet access is not available or your connection is slow.

Oxygen XML Author 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 Author uses different catalog mappings.

Table 1. Catalog Mappings
Doc Type 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 selected (it is by default).
  3. Resolve the root namespace using URI catalog mappings.
Relax NG
Schematron
NVDL
XSL XSL/ANY URI
CSS CSS URI
JSON JSON URI
XPROC XPROC 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 selected (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 selected (it is not by default).
Relax NG Relax NG

Creating an XML Catalog with a Template

An XML Catalog file can be easily created in Oxygen XML Author starting from the document template called OASIS XML Catalog. It is available when creating new document templates.

How Oxygen XML Author Determines which Catalog to Use

Oxygen XML Author uses XML Catalogs to resolve references for validations and transformations and it maps such references to the built-in local copies of the schemas associated with the various frameworks (DocBook, DITA, TEI, XHTML, SVG, etc.)

Oxygen XML Author includes default global catalogs and default catalogs for each of the built-in frameworks, and you can also create your own.

Oxygen XML Author looks for catalogs in the following order:

Example: Using an XML Catalog to map an Absolute XML Schema Reference to an XML Schema Located Relative to the XML Catalog

An XML Catalog can be used to map an XML Schema specified with a 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 an XML catalog entry like this:
<uri name="urn:oasis:names:tc:dita:xsd:topic.xsd:1.1"
    uri="topic.xsd"/>

Example: Using an XML Catalog to map an Imported XML Schema Reference to an XML Schema Located Relative to the XML Catalog

An XML Catalog can be used to map an xs:import or xs:include XML Schema reference to a local copy of the schema.

Considering the following xs:include inside an XML Schema:
<xs:include schemaLocation="someFolder/common.xsd"/>
The reference can be resolved to a local schema file with an XML catalog entry like this:
<uriSuffix uriSuffix="someFolder/common.xsd" uri="relative/path/to/common.xsd"/>