The simple guide to WSDL (with an example)

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

Updated: 03 April 2024

If you’re a developer who’s working with web services, you might one day be asked to integrate using something called WSDL. What is it, and how do you use it? Here’s what you need to know about WSDL web services and SOAP.

In this guide we’re going to cover:

What is WSDL, really?
What is the structure of a WSDL file, and what do the elements mean?
A proper, valid example WSDL you can use

What is a WSDL file?

Let’s start with the basics! What is WSDL?

Web Services Description Language (WSDL) is an XML-based language for describing web services.

A WSDL file is written in XML.

It defines the operations in a web service, the messages used by each operation, and what each message should look like.

What does a WSDL file describe? - Infographic — A WSDL file describes a web service’s operations, data types, protocols and endpoints

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

You can think of a WSDL file as an instruction manual for interacting with a web service.

It defines the rules and format for the communication between your application and the web service you’re trying to talk to.

A WSDL file is usually given to consumers of a web service, either directly as a download from the service itself, or distributed separately.

WSDL works with different types of web services

The WSDL language doesn’t enforce any particular way of accessing a web service.

Instead, when you describe a web service in WSDL, you define one or more bindings.

A binding specifies the details of how the web service will be accessed, and how the messages will be exchanged between the service provider and its consumers.

Bindings

The WSDL specification describes these 3 bindings:

SOAP binding (this is undeniably the most common way to use WSDL)
HTTP GET and POST binding
MIME binding

But it’s not for REST services

Although WSDL can describe web services with various different bindings, it was never designed to work with REST services.

REST is a very different architectural style of web services, and it isn’t really compatible with WSDL.

Is WSDL still used anymore? 🤠

Where did WSDL go? Why it still around?

People were really excited about WSDL in the early 2000s, when companies began to use web services to connect their internal systems.

But, just like most technologies, it got superseded by new technologies.

Lightweight alternatives like REST or JSON-based services arrived. Many teams eventually said goodbye to XML-based web services.

These days, people don’t often choose WSDL for new systems, but many legacy systems still depend on it, so you’ll see it in use inside many huge companies.

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, which is designed to work like calling a method or procedure in a computer program (except it takes place over a network). SOAP sits on top of an existing transport, like HTTP.

The SOAP standard defines things that are common to lots of services:

The structure of messages – 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 message encryption

By contrast, WSDL is a language that allows us to define:

The operations you can call on a service
The messages that you can exchange with a service

So while WSDL defines the operations and messages for a particular web service (e.g. “GetBook”, “SaveCustomer”), SOAP defines the concrete format for exchanging those messages with a server.

WSDL is most commonly seen to describe SOAP web services.

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 to read and parse a WSDL file yourself. Instead, you use a library for your programming language, like one of these libraries:

In Java, you can use any library which implements Java’s JAX-WS standard, such as Apache CXF. CXF can read WSDL files and interact with SOAP services. Or, 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. ¹

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

This WSDL is just for learning purposes. It doesn’t point to a “real” web service. If you want to use this WSDL in an application, you can import it into soapUI and create a mock service.

              <?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!

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 ↩