Using XML Catalogs for Offline Builds

XML catalogs enable offline build tools to achieve fully deterministic and reproducible builds by intercepting remote URI requests for external resources—such as Document Type Definitions (DTDs) and XML Schema Definitions (XSDs)—and resolving them to local file paths. Without internet access, standard XML parsers fail when attempting to fetch remote schemas declared in XML headers. By supplying a pre-configured, local mapping file adhering to the OASIS XML Catalog standard, build tools ensure that parsing, schema validation, and XSLT transformations execute identically across any environment without querying external networks.

The Problem of Network-Dependent XML Parsing

When an XML processor encounters an external entity reference, such as a DTD declaration:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

its default behavior is to fetch the resource from the specified HTTP/HTTPS URL. In an isolated, air-gapped, or offline continuous integration (CI) pipeline, these outgoing network requests fail, halting the build. Even with network access, relying on remote endpoints introduces latency, transient network failures, and potential non-determinism if the remote server modifies the schema or becomes unavailable.

How XML Catalogs Resolve External Entities Locally

An XML catalog is a standard XML document that defines mapping rules between external identifiers and local storage paths. Catalogs primarily resolve two types of identifiers:

  1. Public Identifiers (PUBLIC): Formal Uniform Resource Names (URNs) that uniquely name a resource regardless of location.
  2. System Identifiers (SYSTEM): Direct URIs typically pointing to remote network locations.

A standard catalog.xml file uses mapping directives such as <public> and <system>:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <public 
    publicId="-//OASIS//DTD DocBook XML V4.5//EN" 
    uri="schemas/docbook-4.5/docbookx.dtd"/>
  <system 
    systemId="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
    uri="schemas/docbook-4.5/docbookx.dtd"/>
  <rewriteURI 
    uriStartString="http://www.w3.org/2001/" 
    rewritePrefix="schemas/w3c/"/>
</catalog>

When an XML parser is configured to use this catalog, it evaluates public and system IDs against the mapping table before issuing any I/O requests. If a match is found, the parser immediately substitutes the remote URI with the designated local file path.

Integrating Catalogs into Offline Build Workflows

Offline build engines (such as Maven, Gradle, Ant, or native command-line tools like xsltproc and xmllint) utilize XML catalogs through specific configuration steps:

  1. Vendoring Schemas: All required DTD, XSD, and XSLT files are packaged directly into the source control repository or provided as a hermetic, pre-downloaded dependency archive.

  2. Configuring the Entity Resolver: Build plugins configure the underlying XML parser (e.g., Apache Xerces, Saxon, or libxml2) to use an OASIS-compliant EntityResolver or URIResolver.

  3. Setting Environment Variables or CLI Flags: Command-line processors are explicitly pointed to the catalog. For example, libxml2-based tools leverage the XML_CATALOG_FILES environment variable:

    export XML_CATALOG_FILES="/path/to/project/catalog.xml"
xsltproc --nonet stylesheet.xsl document.xml

    The --nonet flag enforces strict offline execution by causing the build to fail explicitly if any unmapped resource attempts a network connection.

Core Benefits for Determinism and Reliability