A Simple Guide to WSDL (with an Example)

Learn about Web Services Description Language (WSDL) and see a working example.

WSDL has been around for a long time, but this old granddaddy of web services ain’t disappearing, just yet. One day you might be lucky enough to work with WSDL. And if that’s you right now, you’ll appreciate this simple guide to working with WSDL.

At first glance, WSDL files can look a bit quirky and be difficult to understand.

So in this guide we’re going to cover:

  • What WSDL is

  • The structure of a WSDL file (how to understand all the elements in it)

  • A proper, valid example WSDL you can use

WSDL Basics

What is a WSDL file?

Web Services Description Language (WSDL) is a standard for describing web services. It’s an XML format, which defines the operations in a web service, its the messages used by each operation, and their XML elements, or data types.

WSDL isn’t often chosen for new web services anymore, but many legacy systems still use it.

A valid WSDL file contains all the information you need to send a request to a web service.

WSDL doesn’t bind you up

WSDL doesn’t insist that a service must have a certain message format, or must be accessed using a certain network protocol.

Instead, in WSDL you choose a binding. This is where you give a concrete definition of how the service will be accessed, and what data format it will use.

The WSDL spec describes these bindings:

  • SOAP binding (perhaps the most common)

  • HTTP GET and POST binding

  • MIME binding

You’ve probably seen the term WSDL alongside SOAP. So how are the two terms related?

SOAP is a standard for exchanging messages with a server, or making a remote procedure call (RPC). SOAP sits on top of an existing transport, like HTTP.

WSDL allows us to define:

  • The operations you can call on a service

  • The messages that you can exchange with a service

But SOAP defines:

  • The messages themselves – an Envelope containing a Header and a Body

  • A way to return fault or error messages from the service

  • A way to enhance messages with other features, like encryption

So WSDL defines the operations and messages for a web service, and SOAP defines the concrete format for sending those messages to a server.

Structure of a WSDL file

A WSDL document is written in XML and contains the following elements:

Element What it does
<types> Defines the data types (XML elements) that are used by the web service.
<message> Defines the messages that can be exchanged with the web service. Each <message> contains a <part>.
<portType> Defines each operation in the web service, and the messages associated with each operation.
<binding> Defines exactly how each operation will take place over the network (we use SOAP, in the example below).
<service> Defines the physical location of the service (e.g. its endpoint).

How do you use a WSDL file?

A WSDL file is designed for computers to understand. It’s a contract, which can be understood by machines.

It’s basically a manual or recipe that describes a web service.

You can use the information in a WSDL file to:

  • Call the remote web service which the WSDL describes – either by writing some code or using a testing tool

  • Write your own web service, which implements the definitions in the WSDL

  • Create sample request or response messages for the service

Using a WSDL in your code

You can use a WSDL to create code that calls a web service.

But usually, you don’t write code yourself to read and parse a WSDL file.

Instead, you use a library for your programming language, like one of these:

  • In Java, you can use any library which implements the JAX-WS standard, like Apache CXF. CXF can read WSDL files and interact with SOAP services.

    If you don’t want to configure CXF yourself, you can use an integration framework like Apache Camel, which indirectly uses CXF.

  • In Python, you can use Zeep, which is a library that can parse a WSDL file, and generate code so you can call the remote web service.

Using a WSDL in a testing tool

You can also use a desktop program to parse a WSDL and interact with the web service it describes.

You can use use one of these tools:

  • soapUI, an open source desktop application for testing web services

  • Postman, another desktop application for testing web services

  • Boomerang, an extension for Google Chrome for testing SOAP services

Next, let’s take a look at an example WSDL file.

Example WSDL file

Here is an example WSDL file which describes an imaginary web service called BookService.

The service exposes three synchronous (input/output) operations:

  • GetBook - gets information about a single book from the collection

  • AddBook - adds a book to the collection

  • GetAllBooks - retrieves all books from the collection

A note on binding styles

There are several different ways to bind a WSDL to a SOAP message.

This example uses the “document-literal wrapped” binding pattern.

‘Document-literal wrapped’ is the most widely accepted format, although it is a little complex to write from scratch, which is why some people find it helpful to see a finished example.

What is a 'document-literal wrapped' style WSDL?

‘Document-literal wrapped’ describes a WSDL where the request and response parameters for an operation are “wrapped” inside all-encompassing request and response elements, which are defined in the WSDL’s types section. 1

Additionally, in document-literal wrapped style, the request element has the same name as the SOAP operation. For example, an operation GetBook will be invoked using an element called GetBook.

The example: BookService.wsdl

Feel free to use this example WSDL file in your own learning or testing, but it comes without any warranty or licence.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://www.cleverbuilder.com/BookService/"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  name="BookService"
                  targetNamespace="http://www.cleverbuilder.com/BookService/">
  <wsdl:documentation>Definition for a web service called BookService,
    which can be used to add or retrieve books from a collection.
  </wsdl:documentation>

  <!--
      The `types` element defines the data types (XML elements)
      that are used by the web service.
   -->
  <wsdl:types>
    <xsd:schema targetNamespace="http://www.cleverbuilder.com/BookService/">
      <xsd:element name="Book">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ID" type="xsd:string" minOccurs="0"/>
            <xsd:element name="Title" type="xsd:string"/>
            <xsd:element name="Author" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="Books">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="unbounded"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      <xsd:element name="GetBook">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="ID" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="GetBookResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>

      <xsd:element name="AddBook">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="1" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="AddBookResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="1"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="GetAllBooks">
        <xsd:complexType/>
      </xsd:element>
      <xsd:element name="GetAllBooksResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element ref="tns:Book" minOccurs="0" maxOccurs="unbounded"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>


  <!--
      A wsdl `message` element is used to define a message
      exchanged between a web service, consisting of zero
      or more `part`s.
   -->

  <wsdl:message name="GetBookRequest">
    <wsdl:part element="tns:GetBook" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="GetBookResponse">
    <wsdl:part element="tns:GetBookResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="AddBookRequest">
    <wsdl:part name="parameters" element="tns:AddBook"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="AddBookResponse">
    <wsdl:part name="parameters" element="tns:AddBookResponse"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="GetAllBooksRequest">
    <wsdl:part name="parameters" element="tns:GetAllBooks"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="GetAllBooksResponse">
    <wsdl:part name="parameters" element="tns:GetAllBooksResponse"></wsdl:part>
  </wsdl:message>

  <!--
      A WSDL `portType` is used to combine multiple `message`s
      (e.g. input, output) into a single operation.

      Here we define three synchronous (input/output) operations
      and the `message`s that must be used for each.
   -->
  <wsdl:portType name="BookService">
    <wsdl:operation name="GetBook">
      <wsdl:input message="tns:GetBookRequest"/>
      <wsdl:output message="tns:GetBookResponse"/>
    </wsdl:operation>
    <wsdl:operation name="AddBook">
      <wsdl:input message="tns:AddBookRequest"></wsdl:input>
      <wsdl:output message="tns:AddBookResponse"></wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="GetAllBooks">
      <wsdl:input message="tns:GetAllBooksRequest"></wsdl:input>
      <wsdl:output message="tns:GetAllBooksResponse"></wsdl:output>
    </wsdl:operation>
  </wsdl:portType>

  <!--
      The `binding` element defines exactly how each
      `operation` will take place over the network.
      In this case, we are using SOAP.
   -->
  <wsdl:binding name="BookServiceSOAP" type="tns:BookService">
    <soap:binding style="document"
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="GetBook">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/GetBook"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="AddBook">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/AddBook"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="GetAllBooks">
      <soap:operation
              soapAction="http://www.cleverbuilder.com/BookService/GetAllBooks"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <!--
      The `service` element finally says where the service
      can be accessed from - in other words, its endpoint.
   -->
  <wsdl:service name="BookService">
    <wsdl:port binding="tns:BookServiceSOAP" name="BookServiceSOAP">
      <soap:address location="http://www.example.org/BookService"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

See this example in action

If you want to see this WSDL used in an Apache Camel (Java) application, then check out the file here:

See this example in a Camel app on GitHub

Wrapping up

We’ve learned about WSDL files and how they’re related to SOAP.

WSDL is a language for describing web or network services. SOAP is a message format for exchanging messages with a server.

Try using the example WSDL file above in your own learning projects, or plug it into a testing tool like soapUI.

Good luck!

  1. Akram, Asif, Rob Allan, and David Meredith. “Best practices in web service style, data binding and validation for use in data-centric scientific applications.” e-Science All Hands Meeting. 2006. https://epubs.stfc.ac.uk/manifestation/1133/621.pdf 

Join the discussion

Got some thoughts on what you've just read? Want to know what other people think? Or is there anything technically wrong with the article? (We'd love to know so that we can correct it!) Join the conversation and leave a comment.

Comments are moderated.