How XML Catalogs Map Public Identifiers to Local URIs

XML catalog files serve as local lookup tables that map external entity references, such as Public Identifiers, to locally stored Uniform Resource Identifiers (URIs). When an XML parser encounters a reference to a remote Document Type Definition (DTD) or schema, the catalog intercepts the request and resolves it to a local file path. This mechanism eliminates the need to download standard definitions repeatedly over the network, ensuring faster parsing, reduced bandwidth usage, and reliable offline processing.

The Problem with Remote Identifiers

XML documents frequently reference DTDs using both a Formal Public Identifier (FPI) and a System Identifier (typically a URL). A standard XHTML declaration looks like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

Without a catalog, an XML parser attempts to fetch the DTD directly from the W3C server via HTTP. If the server is unreachable, slow, or enforcing rate limits, parsing can fail or stall application workflows.

The OASIS XML Catalog Standard

The standard solution is the OASIS XML Catalog specification. An XML catalog is an XML document (typically using the root element <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">) that defines explicit mappings between identifiers and local files.

To map the public identifier -//W3C//DTD XHTML 1.0 Strict//EN to a local file, a <public> element is added to the catalog:

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <public 
        publicId="-//W3C//DTD XHTML 1.0 Strict//EN" 
        uri="schemas/xhtml1-strict.dtd"/>
</catalog>

Key Attributes of the `<public>` Element:

publicId: The exact string matching the public identifier defined in the XML document’s DOCTYPE declaration.
uri: The local file path or URI pointing to the cached copy of the DTD. Relative URIs resolve against the base URI of the catalog file itself.

The Resolution Process

When an XML processor configured with an entity resolver parses a document, the resolution follows these steps:

Entity Interception: The parser reads the DOCTYPE declaration and extracts the Public Identifier (-//W3C//DTD XHTML 1.0 Strict//EN) and the System Identifier URL.
Catalog Lookup: The catalog resolver normalizes whitespace within the public identifier and checks the loaded catalog for a matching <public> entry.
Redirection: When a match is found, the resolver replaces the remote URL with the uri specified in the catalog (e.g., file:///etc/xml/schemas/xhtml1-strict.dtd).
Local Resource Loading: The parser loads the DTD from the local file system without initiating any network requests.

Fallbacks and Hierarchical Catalogs

If a direct <public> match is not found, catalog resolvers can: * Use <delegatePublic> to forward the lookup to a secondary, specialized catalog based on matching identifier prefixes. * Fall back to matching the System Identifier using <system> or <rewriteSystem> entries. * Retrieve the original remote URL if all catalog entries fail to match and network access is permitted.