Understanding WSDL

Have you ever cracked open a WSDL file in a text editor and taken a look at it? Did you understand the elements you saw?

Most times when we are created SOAP Web services, we start with a bottom-up approach; i.e. we start with the implementation code in Java, C# or whatever our language of choice is and then we use the tooling within our chosen IDE to generate the web service artifacts which includes the WSDL file. But what if you wanted to or were required to use a top down approach; i.e. start with a WSDL and use it to generate your web service implementation code. While this happens rarely, certain products such as IBM Websphere Message Broker require this approach to expose a web service interface into a broker application.

WSDL stands for Web Services Description Language. Understanding WSDL is very beneficial as it gives you the ability to be able to peer into a WSDL file in a text editor and know what services are offered, what methods are available as well as their arguments and return values, how to interact with the service and at what end points, etc. A WSDL is an XML document which means that by nature it should be self descriptive (up to a point). So let's dive into the parts / sections of the WSDL document.

This article focuses on WSDL 1.1 and not WSDL 2.0. While WSDL 2.0 is the latest version of the specification and is a W3C recommendation, WSDL 1.1 is more widely used and is well supported by tools, while WSDL 2.0 has little or buggy support from tools. To learn about the differences between 1.1 and 2.0, see the Wikipedia page at the bottom of this blog post.

A WSDL 1.1 document is typically arranged in an bottom-up manner by first defining base elements and then defining elements that make use of the base elements afterwards.  Below is an example of a WSDL file:

<?xml version="1.0"?>
<definitions name="StockQuote"

targetNamespace="http://example.com/stockquote.wsdl"
          xmlns:tns="http://example.com/stockquote.wsdl"
          xmlns:xsd1="http://example.com/stockquote.xsd"
          xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
          xmlns="http://schemas.xmlsoap.org/wsdl/">

    <types>
       <schema targetNamespace="http://example.com/stockquote.xsd"
              xmlns="http://www.w3.org/2000/10/XMLSchema">
           <element name="TradePriceRequest">
              <complexType>
                  <all>
                      <element name="tickerSymbol" type="string"/>
                  </all>
              </complexType>
           </element>
           <element name="TradePrice">
              <complexType>
                  <all>
                      <element name="price" type="float"/>
                  </all>
              </complexType>
           </element>
       </schema>
    </types>

    <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>

    <message name="GetLastTradePriceOutput">
        <part name="body" element="xsd1:TradePrice"/>
    </message>

    <portType name="StockQuotePortType">
        <operation name="GetLastTradePrice">
           <input message="tns:GetLastTradePriceInput"/>
           <output message="tns:GetLastTradePriceOutput"/>
        </operation>
    </portType>

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

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

</definitions>

The root element of a WSDL document is the definitions element. Within the definitions element, some namespace declarations are made as attributes of the XML document.

Within the document itself, the first element is the types element. The types element is a container for data type definitions used by the web service. In the example above, 2 data types are defined in the XML Schema Definition (XSD) format. The first is the TradePriceRequest data type which has a single member / property tickerSymbol which is a String. The second is the TradePrice data type which has a float property / member called price. Once these types are defined they can now be used in the WSDL document.

The second element of the document is the message element. The message element defines the data being communicated. In our example 2 messages are described; an input message, the request to the web service which takes in a parameter of type TradePriceRequest, and an output message, the return from the web service which has a data type of TradePrice.

The third element of the document is the portType element. The port type element defines an abstract set of operations supported by one or more endpoints. Operations are the web service methods. In our example the method is the GetLastTradePrice method, which takes in and returns the input and output messages previously defined. The portType element can be compared to a class or a library of functions in a traditional programming language.

The binding element comes next and specifies the protocol and data format for a port type. The binding element has two attributes - name and type.
The name attribute defines the name of the binding, and the type attribute points to the port type for the binding, in our example this the StockQuotePortType. The binding element typically contains a soap:binding element which has two attributes - style and transport. The style attribute can be either set to "rpc" or "document". Most of the time the "document" style is used. The transport attribute defines the SOAP protocol to use. In this example we are using HTTP. The binding element must also contain the operation element which lists each operation that the portType exposes and specifies a concrete grammar for the input, output and fault messages.

The final element in a WSDL is the service element. The service element defines the collection of ports / endpoints that compose this web service. The service has a name attribute and exposes the binding. The service element completes the WSDL definition. You could now take this definition and easily generate code that implements the complete interface in your language of choice.

There are a few tools that help you create a WSDL, if you would rather not use a simple text editor. Altova's XMLSpy and the Eclipse IDE both have WSDL editors.

Thanks for reading.


For more information about WSDLs checkout:

• W3C WSDL page
• Understanding WSDL MSDN Article
• Wikipedia WSDL entry