This paper was submitted for XML 2004 in August 2004. It is provided for archival purposes.

WSDL 2.0: What's new?

Hugo Haas

Web Services Activity Lead
World Wide Web Consortium (W3C) (http://www.w3.org/)


  Paris
  France
  

Abstract

Web services provide a standard means of interoperating between different software applications, running on a variety of platforms and/or frameworks. In order to do so, Web services agents exchange XML messages across the World Wide Web, using a variety of protocols (HTTP/1.1, SOAP Version 1.2, …).

Key to the interoperability of Web services agent is to have an interface described in a machine-processable format. Designed at the World Wide Web Consortium (W3C), the Web Services Description Language (WSDL) 2.0 provides a description of the messages being exchanged by the provider agent, along with protocol and location information. This document introduces the major concept of WSDL 2.0.


Table of Contents

Abstract description of a Web service interface
Interface and interface operation
Message exchange patterns
Operation style
Interface inheritance
Safeness
Application data
Binding and endpoint specification
SOAP Version 1.2 binding
SOAP Version 1.1 binding
HTTP binding
Extensibility
Open content-model
Features and properties
Status
References

WSDL 2.0 describes Web services with three different aspects:

To help our understanding, we will be taking the example of a weather service which provides a Web service for both getting the current temperature (for users) and setting the temperature (for sensors) of certain locations.

Abstract description of a Web service interface

[WSDL Version 2.0: Core] defines the core WSDL 2.0 language, and how to describe a Web service. It defines a component model which is used to logically describe endpoints.

This component model enables one to separate the description of a service's abstract functionality from concrete details of how and where that functionality is offered.

Interface and interface operation

Messages are typically described using XML Schema [XML Schema], though other schema languages are permitted, as well as non-XML Infoset-based type systems.

For our example, we would define the following three messages:

Example 1. Message definition with XML Schema

<xs:schema targetNamespace="http://accurateweather.example/msgs"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns="http://accurateweather.example/msgs"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified">
  <simpleType name="FahrenheitDegree">
    <xs:restriction base="xs:decimal"/>
  </simpleType>
  <xs:element name="location">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="country" type="xs:string"/>
        <xs:element name="state" type="xs:string"/>
        <xs:element name="city" type="xs:string"/>
      </xs:sequence> 
    </xs:complexType>
  </xs:element>
  <xs:element name="temperature">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="location"/>
        <xs:element name="date" type="xs:dateTime"/>
        <xs:element name="value" type="FahrenheitDegree"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="temperatureOk">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="valid" type="xs:boolean"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

An interface describes the set of messages that a service agent sends and receives. Related message are logically grouped in interface operations.

An operation is an interaction with the service consisting of a set messages exchanged between the service and the other roles involved in the interaction, in particular the service requester. There exists two types of messages: ordinary messages, and fault messages that may be generated as a result of an event occurring during the execution of a message exchange that disrupts the normal flow of messages.

Example 2. Definition of the weather service interface

We are using here the message definitions from Example 1, “Message definition with XML Schema”. CompleteInterface extends GetTemperature (see the section called “Interface inheritance”).

<interface name="GetTemperature">
  <operation name="location" safe="true"
             pattern="http://www.w3.org/2004/08/wsdl/in-out"
             style="http://www.w3.org/2004/08/wsdl/style/uri-style">
    <input messageLabel="In" element="s:location"/>
    <output messageLabel="Out" element="s:temperature"/>
  </operation>
</interface>
<interface name="CompleteInterface" extends="m:GetTemperature">
  <operation name="set" pattern="http://www.w3.org/2004/08/wsdl/in-out">
    <input messageLabel="In" element="s:temperature"/>
    <output messageLabel="Out" element="s:temperatureOk"/>
  </operation>
</interface>

Message exchange patterns

WSDL 2.0 describe a service from the point of view of the service itself. Messages are going in (input messages) and out (output messages). The sequence and cardinality of abstract messages listed in an operation is called a message exchange pattern (MEP). Unlike WSDL 1.1, [WSDL Version 2.0: Predefined Extensions] carefully describe the sequence, direction (in or out) and cardinality of the messages that are involved in the exchange, as well as identifying the parties involved. The eight following MEPs are defined in [WSDL Version 2.0: Predefined Extensions]:

  • In-Only. This pattern consists of exactly one message received by a service from some other node. No fault may be generated.

  • Robust In-Only. This pattern can be considered as a variation of In-Only. It also consists of exactly one message received by a service, but in this case faults can be triggered by the message received.

  • In-Out. This pattern consists of exactly two messages: a message received by a service from some other node, followed by a message sent to the other node. The second message may be replaced by a fault.

  • In-Optional-Out. This patten consists of one or two messages: a message received by a service from some other node, optionally followed by a message sent to the other node from the service. Each message may trigger a fault in response.

  • Out-Only. This pattern consists of exactly one message sent to some other node from a service. No fault maybe generated.

  • Robust Out-Only. This pattern can be considered as a variation of Out-only. It also consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message.

  • Out-in. This pattern consists of exactly two messages: a message sent to some other node from a service, followed by a message received by the service from the other node. The second message may be replaced by a fault.

  • Out-Optional-In. This pattern consists of one or two messages: a message sent to some other node from a service, optionally followed by a message received by the service from the other node. Each message may trigger a fault in response.

Other MEPs may be defined and used by an interface operation.

Operation style

WSDL 2.0 includes the concept of operation style in order to apply restrictions to an operation. An operation style asserts that message schemas in a particular operation conform to certain rules.

[WSDL Version 2.0: Core] defines an RPC style for such interactions. [WSDL Version 2.0: Bindings] defines URI and Multipart styles in order to specify constraints to be able to express messages in a request URL or as a POSTed form when using HTTP/1.1.

Interface inheritance

WSDL 2.0 allows an interface to extend one or more other interfaces. In such cases, the interface contains the interface operations of the interfaces it extends, along with any additional operations it defines.

An interface can reuse the definitions of operations from other interfaces using the derivation mechanism, but operation overloading is not allowed.

Safeness

WSDL 2.0 allows one to specify that an operation is safe, i.e. that the requester agent does incur any obligation beyond the interaction or not (see Example 2, “Definition of the weather service interface”).

This is useful as hints to the bindings: for example, an safe operation may be bound to an HTTP GET request (see Example 5, “HTTP binding of the GetTemperature interface”). One can also foresee optimizations such as caching, pre-fetching and re-fetching of information, etc.

Application data

[WSDL Version 2.0: Predefined Extensions] defines the Application Data Feature (see also the section called “Features and properties”) to enable the description of application-defined additional data declarations outside of the normal data channel (e.g. the SOAP body).

This allows to express additional information in SOAP 1.2 or HTTP headers. Bindings to other protocols may be defined.

Binding and endpoint specification

The concrete part of a WSDL description of a Web service is the binding of an interface definition to a concrete protocol.

[WSDL Version 2.0: Core] defines the binding and endpoint components to that effect. However, the details and features of each protocol bindings need to be defined in an additional binding specification.

[WSDL Version 2.0: Bindings] defines two such specifications: one for SOAP Version 1.2, and the other one for HTTP.

SOAP Version 1.2 binding

The WSDL 2.0 specification provides a binding for the SOAP Version 1.2 Recommendation [SOAP Version 1.2], which did not exist in WSDL 1.1. The use of SOAP Version 1.2 modules can be specified, and the new fault description format provided by SOAP 1.2 is supported.

SOAP messages being transferable by a variety of underlying protocols, the WSDL SOAP 1.2 binding allows one to specify which underlying protocol should be used. The binding specification in [WSDL Version 2.0: Bindings] also defines the use of HTTP as an underlying protocol, reusing some properties of the new HTTP binding (see the section called “HTTP binding”).

Below is an example of the use of the SOAP 1.2 binding.

Example 3. SOAP over HTTP binding of the CompleteInterface interface

We are using here the interface definition from Example 2, “Definition of the weather service interface”. The SOAP binding makes use of a security extension, the http://accurateweather.example/mySecurityExtension SOAP module.

<binding name="SoapBinding" interface="m:CompleteInterface"
	 type="http://www.w3.org/2004/08/wsdl/soap12"
         wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"/>
  <operation ref="m:location"/>
  <operation ref="m:set">
    <input messageLabel="In">
      <wsoap:module uri="http://accurateweather.example/mySecurityExtension"/>
    </input>
    <output messageLabel="Out"/>
  </operation>
</binding>
<service>
  <endpoint name="SoapEndpoint" binding="m:SoapBinding"
            address="http://ws.accurateweather.example/set"/>
</service>

Example 4. Example interaction using the SOAP binding

Using the SOAP binding defined in Example 3, “SOAP over HTTP binding of the CompleteInterface interface”, an interaction described by the set operation would look as follows.

The following input message:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
  <env:Header>
    <m:sec xmlns:m="http://accurateweather.example/mySecurityExtension/h">
      <proofOfId>eotnhu934bmubutnadp32hdpugeaoduhue</proofOfId>
    </m:sec>
  </env:Header>
  <env:Body>
    <temperature xmlns='http://accurateweather.example/msgs'>
      <location>
        <country>USA</country>
        <state>MA</state>
        <city>Cambridge</city>
      </location>
      <date>2004-08-06T19:37:37Z</date>
      <value xsi:type='FahrenheitDegree'>70</value>
    </temperature>
  </env:Body>
</env:Envelope>

may give the following output message:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
  <env:Body>
    <temperatureOk xmlns='http://accurateweather.example/msgs'>
      <valid>true</valid>
    </temperature>
  </env:Body>
</env:Envelope>

SOAP Version 1.1 binding

For backwards compatibility purposes, the Working Group will be providing a SOAP 1.1 over HTTP binding. This specification is still under development.

HTTP binding

The HTTP binding has been completely reworked in WSDL 2.0.

All HTTP methods are supported (GET, POST, PUT, DELETE, …). One can specify the input and output serialization, describe available transfer codings, and authentication requirements from [IETF RFC 2616], as well as whether HTTP cookies [IETF RFC 2965] are required.

The HTTP binding also provide a URL replacement syntax to serialize a message in the request URL, as illustrated in Example 5, “HTTP binding of the GetTemperature interface” and Example 6, “Example interaction using the HTTP binding”.

Example 5. HTTP binding of the GetTemperature interface

We are using here the interface definition from Example 2, “Definition of the weather service interface”.

<binding name="HttpBinding" interface="m:GetTemperature">
  <operation ref="m:location" whttp:method="GET"
             whttp:location="{country}/{state}/{city}"/>
</binding>
<service>
  <endpoint name="HttpEndpoint" binding="m:HttpBinding"
            address="http://ws.accurateweather.example/"/>
</service>

Example 6. Example interaction using the HTTP binding

Using the HTTP binding defined in Example 5, “HTTP binding of the GetTemperature interface”, an interaction would look as follows.

The following input message, which would be serialized in the Request URI of the HTTP GET request:

http://ws.accurateweather.example/USA/MA/Cambridge

may give the following output message:

<temperature xmlns='http://accurateweather.example/msgs'>
  <location>
    <country>USA</country>
    <state>MA</state>
    <city>Cambridge</city>
  </location>
  <date>2004-08-06T19:37:37Z</date>
  <value xsi:type='FahrenheitDegree'>70</value>
</temperature>

Extensibility

WSDL 2.0 has been designed in an extensible way. Additional operation styles (see the section called “Operation style”) and message exchange patterns (see the section called “Message exchange patterns”) may be defined, a variety of message definition language may be used in addition to XML Schema, messages can be bound to any protocol for which a binding specification has been written, etc.

In addition, [WSDL Version 2.0: Core] has an open-content model and extensibility provided by features and properties.

Open content-model

WSDL 2.0 uses an open-content model which allows both elements and attributes from other namespaces to be used in a WSDL 2.0 document. This will result in additional properties appearing in the component model.

Extension elements can be marked as mandatory by annotating them with a wsdl:required attribute. The meaning an an element containing a mandatory extension is governed by the meaning of that extension.

Features and properties

Features and properties are the generalization of the SOAP features defined by [SOAP Version 1.2].

A feature component describes an abstract piece of functionality typically associated with the exchange of messages between communicating parties. A "property" in the Features and Properties architecture represents a named runtime value which affects the behavior of some aspect of a Web service interaction.

WSDL 2.0 allows the specification of features and properties in each of the component of the model.

Status

The Web Services Description Language (WSDL) 2.0 is being authored by the Web Services Descriptions Working Group, which is part of W3C's Web Services Activity.

WSDL 2.0 was published as a Last Call Working Draft on 3 August 2004. A Recommendation is expected mid-2005.

References

[IETF RFC 2616] Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt

[IETF RFC 2965] HTTP State Management Mechanism, D. Kristol, L. Montulli, Internet Engineering Task Force, October 2000. Available at http://www.ietf.org/rfc/rfc2965.txt

[SOAP Version 1.2] SOAP Version 1.2 Part 1: Messaging Framework M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, W3C Recommendation. World Wide Web Consortium, 24 June 2003. Latest version available at http://www.w3.org/TR/soap12-part1/

[XML Schema] XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, N. Mendelsohn, W3C Recommendation. World Wide Web Consortium, 2 May 2001. Latest version available at http://www.w3.org/TR/xmlschema-1/

[WSDL Version 2.0: Core] Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, R. Chinnici, M. Gudgin, J-J. Moreau, J. Schlimmer, S. Weerawarana, W3C Working Draft. World Wide Web Consortium, 3 August 2004. Latest version available at http://www.w3.org/TR/wsdl20

[WSDL Version 2.0: Bindings] Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings, H. Haas, P. Le Hégaret, J-J. Moreau, D. Orchard, J. Schlimmer, W3C Working Draft. World Wide Web Consortium, 3 August 2004. Latest version available at http://www.w3.org/TR/wsdl20-bindings

[WSDL Version 2.0: Predefined Extensions] Web Services Description Language (WSDL) Version 2.0 Part 2: Predefined Extensions, M. Gudgin, A. Lewis, J. Schlimmer, W3C Working Draft. World Wide Web Consortium, 3 August 2004. Latest version available at http://www.w3.org/TR/wsdl20-extensions