XML Catalog rewriteSystem precedence when multiple catalogs share the same systemIdStartString

Answer

The OASIS XML Catalogs 1.1 specification does not define a normative ordering for rewriteSystem entries that appear in different catalogs with identical systemIdStartString values. Matching rules are defined only within a single catalog (longest‑prefix match), so when catalogs are combined via catalogs, delegate or processor‑specific chains, the precedence of duplicate prefixes is implementation‑defined.

Behavior of common processors

• Apache XmlResolver processes the catalog list in the order it is supplied and uses the first matching rewriteSystem entry it encounters (first‑match). This order is documented in the XmlResolver Javadoc for CatalogResolver.
• Xerces‑XMLCatalog (the Xerces‑specific resolver) also walks the catalog chain in the order given, but it selects the last matching entry when duplicates exist (last‑match). This behavior is noted in the Xerces‑J release notes for the XMLCatalog component.
• Saxon’s catalog resolver follows the same first‑match approach as XmlResolver when using the standard net.sf.saxon.lib.URIResolver with a catalog, but Saxon‑HE/P/E allow a custom CatalogResolver implementation that can change the order; the default Saxon distribution therefore behaves like first‑match.

Because these rules are not mandated by the specification, they may change between minor releases, and the exact behavior should be verified for the versions in use.

Ensuring deterministic resolution

1. Make every systemIdStartString value unique across the entire catalog chain. This is the only processor‑agnostic guarantee.
2. If duplication cannot be avoided, isolate the conflicting mappings in a single authoritative catalog and ensure that catalog is consulted first (or last, depending on the processor) by ordering the catalogs elements or chaining CatalogResolver instances explicitly.
3. Validate the resolution with a minimal test: create two catalogs that define the same prefix with different rewritePrefix values, load them in the exact order used by your build, and confirm the resolved URI with each processor. Enable catalog tracing (e.g., XmlResolver’s setDebug(true), Xerces’ -Dxml.debug.catalog=true, or Saxon’s -T) to see which catalog supplied the match.

Requesting the exact processor versions and catalog‑chaining method would only change the recommendation if you needed to rely on a specific implementation’s order; otherwise, the safe pattern is to avoid duplicate prefixes or test the order per processor.