Using Element Trees to Parse WSDL Files

July 17, 2002 | Updated July 27, 2002 | Fredrik Lundh

The Web Services Description Language (WSDL) is an XML sublangage used to describe network services.

WSDL lets you describe services provided via SOAP 1.1, HTTP GET/POST, and MIME messages.

This note briefly describes the WSDL file format, and the ElementWSDL module included in the xmltoys library.

Parsing WSDL Files

WSDL files are ordinary XML files; you can use the standard ElementTree XML parser right away:

from xmltoys import ElementTree

bookmarks = ElementTree.parse("google.wsdl")

However, some WSDL attributes needs special treatment by the parser. We’ll get back to that later, once we’ve looked at what’s inside the WSDL file.

Understanding WSDL Files

Concepts

In WSDL, a web service is a network endpoint that provides one or more operations. The endpoint can be implemented as a Python class, with methods for the various implementations, or it can be a set of Javascript handlers, a C++ program, or anything else that talks the right protocol.

A service can provide one or more bindings, which are ways to talk to the service. For example, a service may provide both a SOAP and a traditional HTTP interface. The binding lists the operations it supports, and what protocol to use to perform that operation.

Closely related to the binding is the port type, which defines what messages an operation consists of. The binding tells you what protocol to use, while the port type tells you what messages to send using that protocol.

The messages themselves are defined separately. This allows you to reuse the same message descriptor for several operations. Each message consists of a number of parameters, or parts. Each part is a single object, converted to XML according to the type given in the message.

Document Layout

The WSDL document is of a definitions root element, which contain elements corresponding to the concepts describe above. The root element can contain any number of the following five different subelements:

wsdl:service: The service element describes an individual service. This element provides a name for the service, and points to one or more bindings which provide more information about the operations.
wsdl:binding: This element defines what operations this service provides, and what protocol to use to access them.
wsdl:portType: This element is similar to the binding element, but defines what messages to use for a given operation.
wsdl:message: This element defines the parts make up an individual message. The message element contains part subelements, each specifying the name and type for an individual parameters. Note that under the WSDL model, a normal RPC-style exchange consists of two messages, one for the request and one for the response. For an RPC request, the parts are what arguments to use. For an RPC response, the parts are the return values.
wsdl:types: Finally, the types element is used to define custom types used by this service. By default, WSDL uses the XML Schema type system, and you can use any simple XML Schema type, such as strings, integers, and dates, without having to declare it first.

All elements mentioned this far lives in the http://schemas.xmlsoap.org/wsdl/ namespace. In this article, I will refer to this namespace using the wsdl: prefix.

The WSDL Service Element

The service element provides one or more ports where this service is available.

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://spam.effbot.org/SpamService.wsdl"

<wsdl:service name="SpamService">
  <wsdl:documentation>
  wsdl file for the effbot.org spam service
  </wsdl:documentation>
  <wsdl:port binding="tns:SpamBinding" name="SpamPort">
    ...
  </wsdl:port>
</wsdl:service>

Things to notice

Toplevel elements have name attributes. The service element has a name attribute which provides a unique identifier for this element. Other toplevel elements can also have name attributes.

To refer to a named attribute, WSDL uses qualified names as attribute values. To refer to elements in the WSDL document itself, the uri part of the attribute value should be set to the same as the targetNamespace attribute of the definitions root element.

In this example, the target namespace is http://spam.effbot.org/SpamService.wsdl.

The service element can contain human-friendly documentation. The optional documentation element can contain a brief description of the service.

The WSDL Binding Element

The binding attribute in the port subelement referred to an binding element named {http://spam.effbot.org/SpamService.wsdl}SpamBinding.

(Check: does all names live in a single namespace, or does WSDL differ between bindings, messages, and so on)

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://spam.effbot.org/SpamService.wsdl"

<wsdl:binding name="SpamBinding" type="tns:SpamPortType">
  ...
  <wsdl:operation name="getspam">
    <wsdl:input>
      ...
    </wsdl:input>
    <wsdl:output>
      ...
    </wsdl:output>
  </wsdl:operation>
</wsdl:binding>

The WSDL PortType Element

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://spam.effbot.org/SpamService.wsdl"

<wsdl:portType name="SpamPortType">
  <wsdl:operation name="getspam">
    <wsdl:input message="tns:getspamrequest" />
    <wsdl:output message="tns:getspamresponse" />
  </wsdl:operation>
</wsdl:portType>

The WSDL Message Element

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"

<wsdl:message name="getspamrequest">
  <part name="amount" type="xsd:int"/>
</wsdl:message>
<wsdl:message name="getspamresponse">
  <part name="result" type="xsd:string"/>
</wsdl:message>

To be continued…

The WSDL Types Element

The SOAP Bindings

The ElementWSDL Helper Module

Notes:

See Element Trees and QNames.