Internet Systems and Programming

Web Services Description Language (WSDL)

WSDL provides a model and XML format for describing network services.  The service is viewed as a set of endpoints (or ports) operating on messages that may be either document oriented or procedure-oriented.

The operations and procedures are described abstractly and then bound to specific network protocols and message formats.

The WSDL 1.1 Note, March 2001, illustrates binding to SOAP 1.1, HTTP, and MIME.  This note was contributed to the W3C by Ariba, IBM, and Microsoft and consolidates concepts in earlier proprietary work.  WSDL Version 2.0 is being developed, with Working Draft 3, August 2004.  WSDL Version 2.0 Bindings contains bindings for SOAP 1.2 and HTTP/1.1.

WSDL Elements

WSDL documents use the following elements to define Web services:

  1. Types - a container for datatype definitions (e.g., using XSD)
  2. Message - abstract definition of data
  3. Operation - description of an action of the service
  4. Port Type - abstract set of operations supported by endpoint(s)
  5. Binding - concrete network protocol and data format for a port type
  6. Port - a single endpoint or port with binding and network address
  7. Service - a collection of related endpoints
WSDL uses a set of definitions.  Inside the top-level definitions element are:
    an optional import element,
    an optional wsdl:documentation element,
    an optional wsdl:types element (with one or more xsd:schema),
    0 or more wsdl:message elements (each with 0 or more part),
    0 or more wsdl:portType elements (each with 0 or more operation),
    0 or more wsdl:binding elements  (each with 0 or more operation),
    0 or more wsdl:service elements (each with 0 or more port).
Here is the WSDL document structure and schema.

WSDL Example

The Note has an example illustrating the general structure with a fixed XML format.

This is an example from the Note with SOAP binding of a call-response RPC using HTTP:

              <?xml version="1.0"?>
              <definitions name="StockQuote"
                        targetNamespace="http://example.com/stockquote.wsdl"
                        xmlns:tns="http://example.com/stockquote.wsdl"
                        xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
                        xmlns:xsd1="http://example.com/stockquote.xsd"
                        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                        xmlns="http://schemas.xmlsoap.org/wsdl/">

                  <message name="GetTradePriceInput">
                      <part name="tickerSymbol" element="xsd:string"/>
                      <part name="time" element="xsd:timeInstant"/>
                  </message>

                  <message name="GetTradePriceOutput">
                      <part name="result" type="xsd:float"/>
                  </message>

                  <portType name="StockQuotePortType">
                      <operation name="GetTradePrice">
                         <input message="tns:GetTradePriceInput"/>
                         <output message="tns:GetTradePriceOutput"/>
                      </operation>
                  </portType>

                  <binding name="StockQuoteSoapBinding"
                                  type="tns:StockQuotePortType">
                      <soap:binding style="rpc"
                                  transport="http://schemas.xmlsoap.org/soap/http"/>
                      <operation name="GetTradePrice">
                         <soap:operation
                             soapAction="http://example.com/GetTradePrice"/>
                         <input>
                             <soap:body use="encoded"
                                    namespace="http://example.com/stockquote"
                encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
                         </input>
                         <output>
                             <soap:body use="encoded" namespace="http://example.com/stockquote"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
                         </output>
                      </operation>>
                  </binding>

                  <service name="StockQuoteService">
                      <documentation>My first service</documentation>
                      <port name="StockQuotePort" binding="tns:StockQuoteBinding">
                         <soap:address location="http://example.com/stockquote"/>
                      </port>
                  </service>
              </definitions>

WSDL Implementation

This example WSDL implementation is from Professional XML .  The application provides for four distributed clients submitting invoices to the server.  The server replies with a status message confirming submittal or returning an error.  SOAP is used for the messages and HTTP is used for communication.

The server is implemented in MS VB.  There are four example clients implemented in Java (with Apache SOAP), MS VB, Perl (with SOAP::Lite), and MS WSH.  Here is the Perl client, implemented just as a stub with hardcoded values:

#perl
use SOAP::Lite;

# HTTP headers may be needed depending on environment
print "HTTP/1.0 201 Ok \n";
print "Content-type:text/html\n\n";

# Set parametar variables
$idInvoiceID = "1";
$idCustomerID = "3";
$dtInvoiceDate = "2001-02-08T00:00:00";
$strNotes = "This is an invoice submitted via the PERL client";
$strDeliveryAddress = "1234 PERL Street, Some City, AZ 00000";
$strPaymentTerms = "Net 15 days";
$strPaymentReceived = "N";
$strWSDL = "http://localhost/soap/InvoiceSubmit.wsdl";
$strEndPoint = "http://localhost/soap/InvoiceSubmit.asp";

# Print the introductory text
print "<html><body>";
print "<html><head><title>SOAP Client Using PERL";
print "</title></head><body><h3>SOAP Client Using PERL</h3>";
print "<h4>Invoice Submitted to Microsoft SOAP Server.<br><br>";
print "Reply from Microsoft SOAP Server:</h4>";

# Call the Microsoft SOAP server and print the result
print SOAP::Lite
        -> service($strWSDL)
        -> proxy($strEndPoint)
        -> InvoiceAdd($idInvoiceID, $idCustomerID, $dtInvoiceDate, $strNotes,
                $strDeliveryAddress, $strPaymentTerms, $strPaymentReceived);

print "</body></html>  ";

The call to SOAP::Lite makes the operation very simple.  The program just provides the service description (the WSDL file in InvoiceSubmit.wsdl), the location of the service endpoint (the URI of the ASP program), and the method being called (InvoiceAdd) with parameters.