XML Entity Resolvers and OASIS XML Catalogs

An XML entity resolver is an abstraction layer that intercepts parser requests for external resources, such as Document Type Definitions (DTDs) or external entities, preventing unwanted network calls and ensuring reliable parsing. By integrating with the OASIS XML Catalog standard, entity resolvers map standard public identifiers and remote system URIs to local files, enhancing performance, security, and offline availability.

What is an XML Entity Resolver?

When an XML parser processes a document containing an external resource—such as a DOCTYPE declaration referencing a DTD—it looks for both a System Identifier (a URI) and optionally a Public Identifier (a standardized name). By default, many XML parsers attempt to fetch the resource directly from the specified URI over the network.

An entity resolver is an interface (such as org.xml.sax.EntityResolver in Java or similar hooks in libxml2) that allows developers to intercept these requests. When the parser encounters an external entity, it delegates the resolution to the entity resolver before attempting any network access. The resolver can redirect the request, provide an in-memory stream, or load a local copy of the resource, preventing network latency, server downtime dependencies, and certain XML External Entity (XXE) vulnerabilities.

The Role of OASIS XML Catalogs

The OASIS XML Catalogs standard defines a vendor-neutral XML format for managing mappings between external entity references and local resources. Instead of hardcoding paths inside application code or relying on live URLs inside XML documents, a catalog file maintains an external dictionary of entity mappings.

XML declarations typically define entities with a Public Identifier and a System Identifier:

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

Here, PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" is the Formal Public Identifier (FPI), and the URL is the System Identifier.

How Catalogs Resolve Public Identifiers Locally

OASIS XML Catalogs resolve public identifiers through explicit mapping rules defined in a catalog file (commonly named catalog.xml).

  1. Mapping Configuration: An entry in the catalog maps a specific Public Identifier to a local file URI using the <public> element:

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

  2. Parser Interception: When the XML parser encounters the DOCTYPE declaration, it extracts the publicId and passes it to the catalog-enabled entity resolver.

  3. Catalog Lookup: The resolver queries the loaded OASIS catalog. If a matching publicId attribute is found, the resolver retrieves the corresponding local uri.

  4. Local Resource Delivery: The resolver opens the local file specified by the catalog and returns it as an input stream to the parser.

  5. Fallback Mechanism: If no matching public identifier is found, the catalog can fall back to mapping system identifiers via <system> or <rewriteSystem> entries, or delegate to sub-catalogs using <nextCatalog>. If all lookups fail, control returns to the parser to handle the external fetch or raise an error.

Through this mechanism, OASIS XML Catalogs decouple XML documents from physical network locations, allowing systems to validate and parse XML files efficiently without external network dependencies.