WSDL - Using Catalog Files for WSDL Dependency Resolution

When working with WSDL-based web services, a WSDL document often depends on multiple XML Schema (XSD) files or even other WSDL documents. These dependencies are usually referenced using URLs or file paths through the <import> and <include> elements. While this approach works well in connected environments, it can create problems when services are developed, tested, or deployed in environments without internet access or when external resources become unavailable. XML Catalog files provide a reliable solution by allowing developers to map external resource locations to local files without modifying the original WSDL.

What is an XML Catalog?

An XML Catalog is a configuration file that maps external identifiers such as URLs, URIs, or public identifiers to local resources. Instead of downloading schemas or WSDL files from remote locations, XML processors use the catalog to locate the required files on the local system.

For example, if a WSDL imports an XML Schema from:

<xs:import namespace="http://example.com/schema"
           schemaLocation="http://example.com/schema/customer.xsd"/>

An XML Catalog can redirect this reference to a local file:

<uri name="http://example.com/schema/customer.xsd"
     uri="file:///C:/Schemas/customer.xsd"/>

The WSDL remains unchanged, but the XML processor automatically uses the local file.

Why XML Catalogs Are Important

Without XML Catalogs, every imported schema or WSDL must be accessible from its original location. This creates several challenges:

  • Internet connectivity may not always be available.

  • Remote servers may become unavailable.

  • Different environments may require different resource locations.

  • Build processes become dependent on external websites.

  • Service validation becomes slower because resources are downloaded repeatedly.

XML Catalogs eliminate these issues by redirecting all references to trusted local resources.

How XML Catalog Resolution Works

The dependency resolution process follows these steps:

  1. The XML processor reads the WSDL file.

  2. It encounters an imported schema or another WSDL.

  3. Before accessing the specified URL, it checks the XML Catalog.

  4. If a matching entry exists, it loads the local resource.

  5. If no matching entry exists, it attempts to access the original location.

This process is transparent to the application and does not require modifying the WSDL document.

Structure of an XML Catalog

A typical XML Catalog begins with a root element:

<?xml version="1.0" encoding="UTF-8"?>

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

</catalog>

Inside the catalog, developers define mappings using different elements such as:

  • <uri>

  • <system>

  • <public>

  • <rewriteURI>

  • <delegateURI>

Each serves a different purpose depending on how external resources are identified.

URI Mapping

The most commonly used mapping is the URI mapping.

Example:

<uri
    name="http://services.company.com/schema/customer.xsd"
    uri="schemas/customer.xsd"/>

Whenever the processor encounters the specified URL, it loads the local file instead.

System Identifier Mapping

Some XML resources use system identifiers instead of URLs.

Example:

<system
    systemId="customer.xsd"
    uri="local/customer.xsd"/>

This tells the processor to replace the system identifier with the specified local file.

Public Identifier Mapping

Older XML applications often reference resources using public identifiers.

Example:

<public
    publicId="-//Company//Customer Schema//EN"
    uri="schemas/customer.xsd"/>

Although less common today, public mappings are still supported for compatibility.

Rewrite URI Rules

When many imported resources share the same base URL, creating individual mappings becomes difficult. Rewrite rules simplify the process.

Example:

<rewriteURI
    uriStartString="http://services.company.com/schema/"
    rewritePrefix="schemas/"/>

If the WSDL imports:

http://services.company.com/schema/order.xsd

The processor automatically loads:

schemas/order.xsd

This greatly reduces catalog size.

Delegate URI Rules

Large organizations often divide catalog management among different teams.

Example:

<delegateURI
    uriStartString="http://finance.company.com/"
    catalog="finance-catalog.xml"/>

Requests matching the finance namespace are forwarded to another catalog file.

This makes catalog maintenance much easier in enterprise systems.

Benefits During Development

XML Catalogs provide several advantages for developers:

Offline Development

Developers can work without internet access because all required schemas are stored locally.

Faster Builds

Local files load much faster than downloading resources over the network.

Stable Development Environment

External server outages do not interrupt development or testing.

Simplified Team Collaboration

All developers can use the same local schema versions.

Reduced Network Traffic

Repeated downloads of identical schema files are avoided.

Benefits During Testing

Testing SOAP services becomes more reliable because:

  • Validation always uses known schema versions.

  • Automated tests produce consistent results.

  • Test environments remain independent of external services.

  • Continuous Integration servers do not require internet access.

Benefits During Deployment

In production environments, XML Catalogs improve reliability by:

  • Preventing runtime failures caused by unavailable external resources.

  • Ensuring consistent schema resolution across servers.

  • Reducing startup delays.

  • Supporting secure environments where internet access is restricted.

Using XML Catalogs with Popular Tools

Many XML and SOAP development tools support XML Catalogs.

Examples include:

  • Apache CXF

  • Eclipse IDE

  • IntelliJ IDEA

  • Apache XML Resolver

  • Xerces XML Parser

  • XMLSpy

  • Maven XML plugins

  • Gradle XML processing plugins

These tools automatically resolve imported WSDL and XSD files using configured catalog files.

Common Use Cases

XML Catalogs are particularly useful in:

  • Enterprise SOAP applications

  • Banking systems

  • Government web services

  • Healthcare data exchange

  • Large microservice ecosystems using SOAP

  • CI/CD build pipelines

  • Offline software development environments

Best Practices

To effectively manage WSDL dependencies with XML Catalogs:

  • Store catalog files in version control.

  • Use relative paths whenever possible.

  • Organize schemas into meaningful directories.

  • Keep production and development catalogs separate.

  • Use rewrite rules instead of many individual mappings.

  • Validate catalog files regularly.

  • Remove obsolete mappings during maintenance.

  • Document catalog structure for team members.

  • Keep imported schemas synchronized with service versions.

  • Test dependency resolution after every major update.

Common Challenges

Some common issues developers encounter include:

  • Incorrect URI mappings causing missing schema errors.

  • Relative path mistakes after moving project folders.

  • Outdated local schema copies.

  • Multiple catalog files containing conflicting mappings.

  • Missing imported schemas that are not listed in the catalog.

  • Tool-specific configuration differences.

Regular validation and proper organization help prevent these problems.

Conclusion

XML Catalog files are an effective solution for managing WSDL dependencies in SOAP-based applications. By redirecting external schema and WSDL references to local resources, they improve reliability, speed up development and testing, and eliminate dependence on remote servers. They are especially valuable in enterprise environments, CI/CD pipelines, and offline development scenarios where consistent and predictable resource resolution is essential.