WSDL Reading, a Beginner's Guide

By: Thomas Bayer
Date: 08/24/2009

This article explains how to read a WSDL document by analyzing the Web Services description of a public sample Service. During the article a tree diagram is developed from the content of the WSDL document. The tree illustrates the structure of WSDL. The reader will get an understanding of the WSDL elements and their relationships.

The root element of a WSDL document is definitions. So we start the WSDL tree with a definitions node as root. See figure 1: Definition and Service

Figure1: Definition and Service

To analyse a WSDL document it is recommended to read it from the buttom upwards. At the bottom of the BLZService's WSDL we find a child element of definitions named service.

<wsdl:service name="BLZService">
  <wsdl:port name="BLZServiceSOAP11port_http" binding="tns:BLZServiceSOAP11Binding">
    <soap:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
  <wsdl:port name="BLZServiceSOAP12port_http" binding="tns:BLZServiceSOAP12Binding">
    <soap12:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
  <wsdl:port name="BLZServiceHttpport" binding="tns:BLZServiceHttpBinding">
    <http:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
</wsdl:service>

Listing 1: Service Element

The name of the service is BLZService. A service can have multiple ports marked in figure 2 with a * character. Each port describes a way to access the service. In our BLZService example there are three ports. One for SOAP 1.1, one for SOAP 1.2 and one for the HTTP binding.

Figure2: Ports of a Service

Let's have a look at the first port in listing 2.

  <wsdl:port name="BLZServiceSOAP11port_http" binding="tns:BLZServiceSOAP11Binding">
    <soap:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>

Listing 2: Port describing a SOAP 1.1 Endpoint

It's child element address has a different XML prefix than the other elements. The prefix soap is bound to the SOAP 1.1 binding in this document. Instead of the SOAP binding other bindings for JMS or a file transport can be used. The address element has one attribute named location pointing to an endpoint address of the service.

Figure3: Endpoint Address

To move on, we have to look at the binding attribute of the port.
The value "tns:BLZServiceSOAP11Binding" points to a binding further up in the document. Each port is pointing to a different binding in this example. As a consequence the BLZService WSDL has three bindings.

Figure4: A Port references a Binding

A binding provides details about a specific transport. The binding in figure 5 has two different types of children.

Figure5: SOAP Binding

First we have a look at the soap:binding element in listing 3. The value of the transport attribute is an URI that indicates that SOAP messages should be send over HTTP. The value "document" of the style attribute gives us a clue about the message style together with the use attribute of the soap:body elements. In our example we have a Document/Literal message style.
A binding can specify different transport options for each method of a service.

  <wsdl:binding name="BLZServiceSOAP11Binding" type="tns:BLZServicePortType">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <wsdl:operation name="getBank">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

Listing 3: SOAP 1.1 Binding

Let's have a look at listing 4. There you can find transport options for the getBank operation.
Inside the wsdl:operation element there is a soap:operation element at line 2 defining details for the SOAP protocol and its transport. The soapAction is a reminiscent from the past. The Basic Profile of the Web Services Interoperability Organization stipulates that the soapAction should be used with a fixed value of an empty string.

  <wsdl:operation name="getBank">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>

Listing 4: Binding Operation

Because Web Services set the focus on messages not parameters, information about the transport of these messages can be found in the wsdl:input and wsdl:output element. A service may specify one or several faults as an alternative for the output.

Figure6: Binding Operation

The soap:body and soap:header elements can describe a message further. In the example the style is always literal.

Figure7: soap:body Elements

It is time again to move up in the WSDL. Now we follow the value of the type attribute of the binding. It points to a portType with the same name further up in the document.

Figure8: Binding referencing a PortType

Now we have crossed the border from the concrete details about the transport and location of a service to its pure abstract description of its interface. PortType is in WSDL 1.1 similar to the interface of the Web Service. In WSDL 2.0 the term portType is substituted with the term interface.
An interface can have several operations. An operation corresponds to a function in procedural programming.
The WSDL of the BLZService has only one portType. All of the three bindings refer to the one portType named BLZServicePortType.

Figure9: Operations of a portType

Inside a portType we find operation elements as in the binding. But this time the input and output describe the structure of the messages not transport specific options.

Figure10: Input and Output of an Operation

The message attribute of the input refers again up in the WSDL document. It refers to a message named tns:getBank. Further up in the document we find a corresponding message with this name.

  <wsdl:portType name="BLZServicePortType">
    <wsdl:operation name="getBank">
      <wsdl:input message="tns:getBank"/>
      <wsdl:output message="tns:getBankResponse" wsaw:Action="http://thomas-bayer.com/blz/BLZService/getBankResponse"/>
    </wsdl:operation>
  </wsdl:portType>

Listing 5: The Interface Description of the Service

Figure11: Message

The message getBank has one part element as child. A WSDL specialist will recognize the value of the attribute name, "parameters" indicates the wrapper substyle of the document/literal style.

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

Listing 6: getBank Message

The attribute element at line 2 points again further up. It refers to an element named tns:getBank. We will find this element in a XML Schema.

Figure12: A Message and its Parts

The next child of the definitions element is types.

Figure13: The Types Section

The types element can have multiple XML schemas as children.

Figure14: Schemas used in a WSDL

Listing 7 shows the types element and an embedded schema.

  <wsdl:types>
    <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://thomas-bayer.com/blz/">
      <xsd:element name="getBank" type="tns:getBankType"/>
      <xsd:element name="getBankResponse" type="tns:getBankResponseType"/>
      <xsd:complexType name="getBankType">
        <xsd:sequence>
          <xsd:element name="blz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:complexType name="getBankResponseType">
        <xsd:sequence>
          <xsd:element name="details" type="tns:detailsType"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:complexType name="detailsType">
        <xsd:sequence>
          <xsd:element minOccurs="0" name="bezeichnung" type="xsd:string"/>
          <xsd:element minOccurs="0" name="bic" type="xsd:string"/>
          <xsd:element minOccurs="0" name="ort" type="xsd:string"/>
          <xsd:element minOccurs="0" name="plz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>

Listing 7: Embedded XML Schema

In a schema we can find the definition of:

complexTypes
simpleTypes

and the decleration of:

elements

The XML Schema inside BLZService is a typical schema used for Web Services that has only complexTypes and elements as toplevel schema components.
In document/literal style all the parts point to elements.

Figure15: A Part can reference an Element

Listing 8 shows the declaration of the getBank element.

  <xsd:element name="getBank" type="tns:getBankType"/>

Listing 8: Declaration of the Element getBank

The type of this element is a complexType named getBankType definded somewhere else in the schema.

Figure16: An Element references its Type

The getBankType has a sequence as modulgroup containing one element named blz of the build-in schema type string.

Figure17: A ComplexType with a Sequence as Content

Listing 9 shows the definition of the getBankType.

  <xsd:complexType name="getBankType">
        <xsd:sequence>
          <xsd:element name="blz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>

Listing 9: The ComplexType getBankType

A sequence can consist of several elements that describe the order of elements in a SOAP message.

Figure18: The entire Structure of a WSDL Document

Finally we are through the entire WSDL description of the sample service.

All WSDL documents have the same structure as the BLZService. To understand a WSDL start reading at the bottom and work your way up by following the right attributes as shown in this article.

I hope this article was helpful to learn how to read a WSDL document.

Thomas Bayer
bayer@predic8.com

WSDL Reading, a Beginner's Guide

References

Share