XML Catalog rewriteURI for Local Schema Redirection

An XML Catalog provides a standardized mapping mechanism between external entity references and local resources. The rewriteURI element within an OASIS XML Catalog intercepts URI prefixes—such as remote HTTP/HTTPS endpoints referenced in XML schemas—and replaces them with local file paths. This enables XML processors to validate and parse documents using local schema files without modifying source XML files or relying on an active internet connection.

What is the rewriteURI Element?

The rewriteURI element is defined in the OASIS XML Catalog standard. It functions as a prefix-matching rule for Uniform Resource Identifiers (URIs). Unlike elements that match exact, single URIs (such as <uri>), rewriteURI operates on URI prefixes, making it possible to redirect an entire directory or namespace of remote schema files using a single entry.

The element uses two core attributes:

• uriStartString: The prefix of the URI to match (e.g., the remote base URL).
• rewritePrefix: The replacement prefix (e.g., a local file system path or relative directory).

How rewriteURI Redirects Remote Schemas

When an XML parser processes an XML document containing references such as xsi:schemaLocation, <xs:import>, or <xs:include>, the redirection process works as follows:

1. URI Interception: The parser encounters a remote schema location, such as https://www.example.com/schemas/2024/core.xsd.
2. Catalog Lookup: Instead of immediately initiating a network request, an entity resolver checks the configured XML Catalog.
3. Prefix Matching: The resolver evaluates catalog entries to see if the beginning of the requested URI matches a uriStartString. If multiple entries match, the longest matching prefix takes precedence.
4. Path Rewriting: The parser removes the matched uriStartString from the target URI and prepends the rewritePrefix.
5. Local Resolution: The remaining suffix (core.xsd) is appended to the local prefix, directing the parser to the local file (e.g., file:///etc/xml/schemas/2024/core.xsd or a relative path ./schemas/2024/core.xsd).

Example Configuration

Given the following XML catalog file (catalog.xml):

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <rewriteURI 
        uriStartString="https://www.example.com/schemas/" 
        rewritePrefix="file:///var/schemas/local/" />
</catalog>

If an XML schema contains an import statement:

<xs:import 
    namespace="http://www.example.com/ns/users" 
    schemaLocation="https://www.example.com/schemas/users/user.xsd" />

The catalog resolver matches https://www.example.com/schemas/ and rewrites the target URI to:

file:///var/schemas/local/users/user.xsd

Benefits of Using rewriteURI

• Offline Validation: Builds and parsing operations run reliably in air-gapped environments or without internet access.
• Performance: Loading schemas directly from disk eliminates network latency and HTTP request overhead.
• Build Reproducibility and Stability: Applications are shielded from remote server downtime, network timeouts, or unversioned upstream schema changes.
• Scalability: A single catalog entry handles multiple nested or imported schemas residing under the same base URI hierarchy.