WSDL - Importing and Including External XSD Schemas in WSDL

Introduction

In WSDL-based web services, XML Schema Definition (XSD) is used to define the structure and data types of messages exchanged between clients and services. As web services grow larger and more complex, maintaining all schema definitions inside a single WSDL file becomes difficult. To solve this problem, WSDL allows developers to import or include external XSD schema files.

Using external schemas improves modularity, reusability, maintainability, and organization of service definitions. Large enterprise systems often separate business entities, shared types, and service-specific types into multiple XSD files and then reference them from WSDL documents.

Why External XSD Schemas Are Used

1. Better Organization

Instead of placing hundreds of complex type definitions inside one WSDL file, developers can split them into separate schema files.

Example:

  • customer.xsd

  • order.xsd

  • payment.xsd

Each file contains related definitions.

2. Reusability

The same schema can be reused across multiple services.

For example:

  • Customer details schema may be used by:

    • Billing Service

    • Shipping Service

    • CRM Service

This avoids duplication.

3. Easier Maintenance

When a schema changes, developers only update the XSD file instead of modifying multiple WSDL files.

4. Enterprise Standardization

Organizations often maintain centralized schema repositories containing approved business object definitions.

Understanding XML Schema in WSDL

Inside a WSDL document, schema definitions are usually placed under the <types> section.

Example:

<types>
    <xsd:schema>
        ...
    </xsd:schema>
</types>

Instead of writing everything directly, external XSD files can be referenced.

Difference Between Include and Import

Two important XML Schema mechanisms are used:

Feature xsd:include xsd:import
Purpose Combines schemas References schemas from another namespace
Namespace Same namespace Different namespace
Usage Modular split of same schema Access external schemas
Dependency Internal organization Cross-domain integration

Using xsd:include

Purpose

xsd:include is used when multiple schema files belong to the same target namespace.

Example Scenario

Suppose:

Main schema:

targetNamespace="http://example.com/customer"

Additional schema:

targetNamespace="http://example.com/customer"

Both schemas share the same namespace.

Example of xsd:include

customer-main.xsd

<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://example.com/customer"
    xmlns="http://example.com/customer">

    <xsd:include schemaLocation="customer-types.xsd"/>

</xsd:schema>

customer-types.xsd

<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://example.com/customer"
    xmlns="http://example.com/customer">

    <xsd:complexType name="Customer">
        <xsd:sequence>
            <xsd:element name="id" type="xsd:int"/>
            <xsd:element name="name" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>

</xsd:schema>

How xsd:include Works

The included schema becomes part of the main schema during processing.

It behaves as though all schema definitions were written in a single file.

Using xsd:import

Purpose

xsd:import is used when schemas belong to different namespaces.

This is more common in enterprise systems.

Example Scenario

Suppose:

Customer schema namespace:

http://example.com/customer

Order schema namespace:

http://example.com/order

Since namespaces differ, import must be used.

Example of xsd:import

order.xsd

<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:cust="http://example.com/customer"
    targetNamespace="http://example.com/order"
    xmlns="http://example.com/order">

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

    <xsd:element name="Order">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="customer"
                    type="cust:Customer"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

</xsd:schema>

Explanation of xsd:import Attributes

Attribute Description
namespace Namespace being imported
schemaLocation Path to external schema
type reference Uses namespace prefix

Importing XSD Schemas Inside WSDL

WSDL references schemas under the <types> section.

Example WSDL with Imported Schema

<definitions
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://example.com/service"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://example.com/service">

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

</definitions>

Schema Location Paths

The schemaLocation attribute can contain:

Relative Path

schemaLocation="schemas/customer.xsd"

Absolute URL

schemaLocation="http://example.com/schema/customer.xsd"

Local File Path

schemaLocation="C:/schemas/customer.xsd"

Usually avoided in distributed environments.

Namespace Management

Namespaces prevent naming conflicts between schemas.

Example:

Two schemas may both contain:

<Customer>

Namespaces uniquely identify them.

Namespace Prefix Example

xmlns:cust="http://example.com/customer"
xmlns:ord="http://example.com/order"

Usage:

cust:Customer
ord:Order

Common Problems While Importing Schemas

1. Namespace Mismatch

If namespaces do not match correctly, schema validation fails.

Example:

targetNamespace mismatch

2. Missing Schema File

Incorrect file path causes loading errors.

Example:

schemaLocation not found

3. Circular Imports

Schema A imports Schema B, and Schema B imports Schema A.

This can create dependency issues.

4. Invalid Prefix References

Using undefined namespace prefixes causes parsing errors.

Example:

cust:Customer

without:

xmlns:cust="..."

Best Practices

1. Keep Schemas Modular

Separate schemas logically.

Examples:

  • authentication.xsd

  • employee.xsd

  • invoice.xsd

2. Use Meaningful Namespaces

Namespaces should clearly represent ownership and domain.

Example:

http://company.com/hr

3. Avoid Deep Dependency Chains

Too many imports reduce maintainability.

4. Validate Schemas Regularly

Use XML validation tools during development.

5. Maintain Version Control

Store schemas in repositories like Git.

Real-World Enterprise Usage

Large systems commonly use centralized schema repositories.

Example architecture:

  • Shared business schema repository

  • Multiple WSDL services

  • Shared customer/order/payment schemas

Benefits:

  • Consistency

  • Reduced duplication

  • Easier governance

  • Better interoperability

Tools Supporting XSD Import and Include

Several tools automatically process imported schemas.

Popular Tools

Tool Purpose
Apache CXF SOAP service framework
SoapUI Testing WSDL services
XMLSpy XML/XSD editor
Eclipse WTP WSDL development
JAXB Java XML binding

Validation Process

When a WSDL is processed:

  1. WSDL parser reads definitions

  2. Types section is processed

  3. Imported schemas are loaded

  4. Namespace mappings are resolved

  5. Schema validation occurs

  6. Service proxy classes may be generated

Advantages of External Schema Management

Advantage Description
Reusability Shared across services
Maintainability Easier updates
Scalability Better handling of large systems
Modularity Cleaner architecture
Collaboration Teams work independently

Disadvantages

Disadvantage Description
Complexity More files to manage
Dependency Issues Import chains may break
Deployment Problems Missing files cause failures
Namespace Confusion Incorrect mappings create errors

Conclusion

Importing and including external XSD schemas in WSDL is an essential practice in enterprise web service development. It enables developers to build scalable, modular, and reusable service architectures. The xsd:include mechanism is used for combining schemas within the same namespace, while xsd:import allows integration between schemas from different namespaces.

Proper namespace management, organized schema design, and careful dependency handling are critical for maintaining reliable WSDL services. In modern service-oriented architectures, external schema management plays a major role in ensuring interoperability, maintainability, and standardization across distributed systems.