Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท WSDL and Contracts

WSDL Structure: Types, Messages, PortTypes, Bindings, Services

Read a WSDL 1.1 file with confidence: definitions, types, message, portType, binding and service elements, how they connect, and how to list operations from a WSDL with code.

If SOAP is the envelope, WSDL (Web Services Description Language, pronounced "whiz-dull") is the instruction manual written for machines. A WSDL file is an XML document that describes what a service offers, how to talk to it and where it lives. Tools read it to generate client code, test tools read it to build sample requests, and humans read it when something breaks. Most SOAP services you meet use WSDL 1.1, so that is the version we study; WSDL 2.0 is covered briefly at the end.

The six building blocks

A WSDL 1.1 file has a root definitions element with six kinds of children. They answer three questions: what, how, where.

flowchart TD
    subgraph WHAT["WHAT: the abstract interface"]
      T["types<br/>XML Schema for the data"]
      M["message<br/>input and output messages"]
      P["portType<br/>operations = input + output + faults"]
    end
    subgraph HOW["HOW: the concrete protocol"]
      B["binding<br/>SOAP, style, use, soapAction"]
    end
    subgraph WHERE["WHERE: the address"]
      S["service<br/>port = binding + URL"]
    end
    T --> M --> P --> B --> S

Each part refers to the one before it by name.

Element Purpose
types XML Schema definitions of the data types and elements used in messages.
message An abstract message made of parts; each part names a type or an element.
portType A named set of operations; each operation lists its input, output and fault messages. This is the abstract interface.
binding Attaches a protocol (SOAP), a style (document/rpc) and a use (literal/encoded) to a portType.
service A collection of ports; each port is a binding plus a network address.
import Pulls in another WSDL or schema file (to split big contracts).

The split between abstract (types, message, portType) and concrete (binding, service) is intentional: the same interface can be exposed over SOAP/HTTP, over JMS and at two different addresses without rewriting the abstract part.

A complete small WSDL

Here is a calculator contract for the service we used earlier. Read it top to bottom and follow the names: tns:Add in the message points to the Add element in types; the portType points to the messages; the binding points to the portType; the port points to the binding.

XML
<definitions name="CalcService" targetNamespace="urn:calc"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:calc"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

  <types>
    <xsd:schema targetNamespace="urn:calc" elementFormDefault="qualified">
      <xsd:element name="Add">
        <xsd:complexType><xsd:sequence>
          <xsd:element name="a" type="xsd:int"/>
          <xsd:element name="b" type="xsd:int"/>
        </xsd:sequence></xsd:complexType>
      </xsd:element>
      <xsd:element name="AddResponse">
        <xsd:complexType><xsd:sequence>
          <xsd:element name="result" type="xsd:int"/>
        </xsd:sequence></xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>

  <message name="AddIn"><part name="parameters" element="tns:Add"/></message>
  <message name="AddOut"><part name="parameters" element="tns:AddResponse"/></message>

  <portType name="CalcPortType">
    <operation name="Add">
      <input message="tns:AddIn"/>
      <output message="tns:AddOut"/>
    </operation>
  </portType>

  <binding name="CalcBinding" type="tns:CalcPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="Add">
      <soap:operation soapAction="urn:calc/Add"/>
      <input><soap:body use="literal"/></input>
      <output><soap:body use="literal"/></output>
    </operation>
  </binding>

  <service name="CalcService">
    <port name="CalcPort" binding="tns:CalcBinding">
      <soap:address location="http://localhost:8080/calc"/>
    </port>
  </service>
</definitions>

Two details worth remembering. The part uses element= (document/literal style) rather than type= (rpc style), which is what makes the wrapper Add element appear in the Body. And soapAction is exactly the value a client must send in the SOAPAction header.

Reading a WSDL with code

Because a WSDL is XML, a program can read it. This reads the calculator contract and prints a summary: the service, its address, the operations with their soapAction and the input fields taken from the schema. It is the first half of what code generators do.

Node.js Summarize a WSDL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Generating a client from the contract

The payoff of a machine-readable contract is that a client can be built from it automatically. The second program reads a deliberately simplified contract (an invented stand-in, not real WSDL syntax), discovers the operations and parameter names, and builds a JavaScript object whose methods send real SOAP requests to a local server. This is a miniature version of what wsimport, svcutil and Zeep do.

Node.js A client generated from a WSDL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The generated calc.Add({ a: 20, b: 22 }) hides all XML, exactly like a stub produced by a real toolkit.

WSDL 2.0 in one paragraph

WSDL 2.0 (W3C Recommendation, 2007) simplified the model: message elements disappeared (the schema element is referenced directly), portType was renamed interface, port became endpoint, and it can describe REST services too. Adoption was low. Almost every real SOAP service still publishes WSDL 1.1, so learn 1.1 first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which WSDL 1.1 element lists the operations of a service in an abstract way?

    portType is the abstract interface: operations with their input, output and fault messages.
  2. 2. Where does a WSDL state the network address of the service?

    A service contains ports; each port combines a binding with a location URL.
  3. 3. What does the soapAction attribute in the binding provide?

    The client sends that string in the SOAPAction header (SOAP 1.1) so the server can route the request.
  4. 4. Why separate abstract and concrete parts of a WSDL?

    The abstract interface can be bound to SOAP/HTTP, JMS or other transports and published at several URLs.

Summary

  • WSDL describes what a service offers (types, messages, portType), how to reach it (binding) and where (service/port).
  • Elements refer to each other by qualified name, so you can follow a request from the port down to the schema.
  • soapAction, style and use in the binding fix the wire format.
  • Tools read WSDL to generate clients, servers and tests.
  • WSDL 1.1 dominates real services; WSDL 2.0 renamed things but is rare.

Next: XML Schema Types for WSDL