1. xml
  2. /web services
  3. /wsdl

WSDL - Web Services Description Language

WSDL (Web Services Description Language) is an XML-based interface description language that provides a machine-readable description of web services. It describes the functionality offered by a web service, including the operations available, the input and output message formats, and the protocol bindings.

WSDL serves as a contract between the service provider and service consumer, enabling automatic code generation and service discovery.

WSDL Structure and Components

A WSDL document consists of several key elements organized in a hierarchical structure:

Root Element and Namespaces

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://example.com/calculator"
             targetNamespace="http://example.com/calculator">
  <!-- WSDL content -->
</definitions>

Types Section

The <types> section defines the data types used in the web service, typically using XML Schema:

<types>
  <schema xmlns="http://www.w3.org/2001/XMLSchema"
          targetNamespace="http://example.com/calculator">
    <element name="AddRequest">
      <complexType>
        <sequence>
          <element name="a" type="int"/>
          <element name="b" type="int"/>
        </sequence>
      </complexType>
    </element>
    <element name="AddResponse">
      <complexType>
        <sequence>
          <element name="result" type="int"/>
        </sequence>
      </complexType>
    </element>
  </schema>
</types>

Message Section

Messages define the data elements for each operation:

<message name="AddRequest">
  <part name="parameters" element="tns:AddRequest"/>
</message>

<message name="AddResponse">
  <part name="parameters" element="tns:AddResponse"/>
</message>

Port Type Section

Port types define the operations supported by the web service:

<portType name="CalculatorPortType">
  <operation name="Add">
    <input message="tns:AddRequest"/>
    <output message="tns:AddResponse"/>
  </operation>
</portType>

Binding Section

Bindings specify the protocol and data format for each port type:

<binding name="CalculatorBinding" type="tns:CalculatorPortType">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="Add">
    <soap:operation soapAction="http://example.com/calculator/Add"/>
    <input>
      <soap:body use="literal"/>
    </input>
    <output>
      <soap:body use="literal"/>
    </output>
  </operation>
</binding>

Service Section

The service section defines the endpoints where the web service is available:

<service name="CalculatorService">
  <port name="CalculatorPort" binding="tns:CalculatorBinding">
    <soap:address location="http://example.com/calculator"/>
  </port>
</service>

WSDL Versions

WSDL 1.1

WSDL 1.1 is the most widely adopted version, featuring:

  • Simpler structure
  • Direct support for SOAP bindings
  • Widely supported by tools and frameworks

WSDL 2.0

WSDL 2.0 (also known as WSDL 2.0) introduced:

  • More flexible binding mechanisms
  • Support for RESTful services
  • Improved extensibility
  • Better type system integration
<description xmlns="http://www.w3.org/ns/wsdl"
             targetNamespace="http://example.com/calculator">
  
  <types>
    <!-- Schema definitions -->
  </types>
  
  <interface name="CalculatorInterface">
    <operation name="Add">
      <input messageLabel="In" element="tns:AddRequest"/>
      <output messageLabel="Out" element="tns:AddResponse"/>
    </operation>
  </interface>
  
  <binding name="CalculatorSOAPBinding" 
           interface="tns:CalculatorInterface">
    <!-- Binding details -->
  </binding>
  
  <service name="CalculatorService"
           interface="tns:CalculatorInterface">
    <endpoint name="CalculatorEndpoint"
              binding="tns:CalculatorSOAPBinding"
              address="http://example.com/calculator"/>
  </service>
  
</description>

Working with WSDL

Generating Client Code

Most development platforms provide tools to generate client code from WSDL:

Java (wsimport):

wsimport -keep -verbose http://example.com/calculator?wsdl

C# (svcutil):

svcutil http://example.com/calculator?wsdl

Python (zeep):

from zeep import Client

client = Client('http://example.com/calculator?wsdl')
result = client.service.Add(a=5, b=3)

WSDL Best Practices

  1. Use Meaningful Names: Choose descriptive names for operations, messages, and types
  2. Version Your Services: Include version information in namespaces
  3. Document Everything: Use <documentation> elements extensively
  4. Keep It Simple: Avoid overly complex type hierarchies
  5. Validate Your WSDL: Use tools to ensure WSDL validity

Complete WSDL Example

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://example.com/calculator"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             targetNamespace="http://example.com/calculator">

  <types>
    <xsd:schema targetNamespace="http://example.com/calculator">
      <xsd:element name="AddRequest">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="a" type="xsd:int"/>
            <xsd:element name="b" type="xsd:int"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="AddResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="result" type="xsd:int"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>

  <message name="AddRequest">
    <part name="parameters" element="tns:AddRequest"/>
  </message>
  <message name="AddResponse">
    <part name="parameters" element="tns:AddResponse"/>
  </message>

  <portType name="CalculatorPortType">
    <operation name="Add">
      <documentation>Adds two integers</documentation>
      <input message="tns:AddRequest"/>
      <output message="tns:AddResponse"/>
    </operation>
  </portType>

  <binding name="CalculatorBinding" type="tns:CalculatorPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="Add">
      <soap:operation soapAction="http://example.com/calculator/Add"/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="CalculatorService">
    <documentation>Simple calculator web service</documentation>
    <port name="CalculatorPort" binding="tns:CalculatorBinding">
      <soap:address location="http://example.com/calculator"/>
    </port>
  </service>

</definitions>

Tools and Utilities

WSDL Generation Tools

  • Apache Axis2: Java-based web services framework
  • Apache CXF: Open-source services framework
  • Microsoft WCF: .NET web services framework
  • PHP SOAP: Built-in PHP SOAP extension

WSDL Validation Tools

  • SoapUI: Comprehensive web services testing tool
  • XMLSpy: XML editor with WSDL validation
  • Online WSDL validators: Web-based validation tools

Common Issues and Troubleshooting

Import and Include Problems

  • Ensure proper namespace declarations
  • Verify schema import locations
  • Check for circular references

Binding Issues

  • Validate SOAP binding configurations
  • Ensure proper operation mappings
  • Check transport protocols

Interoperability Concerns

  • Test with multiple client platforms
  • Follow WS-I Basic Profile guidelines
  • Avoid platform-specific extensions

Additional Resources

W3C WSDL 2.0 Specification

WSDL 1.1 Specification

WS-I Basic Profile