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
- Use Meaningful Names: Choose descriptive names for operations, messages, and types
- Version Your Services: Include version information in namespaces
- Document Everything: Use
<documentation>
elements extensively - Keep It Simple: Avoid overly complex type hierarchies
- 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