Proposal for Binding Changes in WSDL 1.2

Fracisco Curbera and Sanjiva Weerawarana
July 24, 2002.

1. Introduction

The WSDL 1.1 <service> element aggregates type, endpoint address and binding details information about a deployed service. This document proposes set of modifications to be included into WSDL 1.2 which will address the following issues:

• Adapting the WSDL <service> and <binding> concepts to support service types.
• Adapting the binding mechanism to enable the modularization of orthogonal binding details definitions.

2. Structure of a WSDL 1.1 Bindings

The WSDL 1.1 binding element allows one to indicate binding details for a given portType. Binding details can be specified at the portType level (i.e., applicable to all operations of the portType), on a per-operation level, or at the input, output, fault message level of an operation. The grammar for a binding is as follows:

 1 <binding name="ncname" type="qname">
 2   <!-- binding details -->
 3   <operation name="ncname"> *
 4     <!-- binding details -->
 5     <input name="ncname"?> ?
 6       <!-- binding details -->
 7     </input>
 8     <output name="ncname"? > ?
 9       <!-- binding details -->
10     </output>
11     <fault name="ncname"> *
12       <!-- binding details -->
13     </fault>
14   </operation>
16 </binding>

Binding details (in the form of elements from other namespaces) can be specified at the places indicated in bold-face. Those on line 2 are applicable to all operations of the portType identified in line 1. Those on line 4 are applicable to the operation identified in line 3. Those on lines 6, 9 an 12 are only applicable to the immediately enclosing input, output or fault messages, respectively.

In addition to the <binding> element, the <port> element allows one to add additional bindings as a portType is being bound. The grammar for a service is as follows:

1 <service name="ncname">
2   <port name="ncname" binding="qname"> *
3     <!-- binding details --> 
4   </port>
6 </service> 

WSDL 1.1 requires that the binding details on line 3 only indicate address information for the port. Note that WSDL 1.1 is ambiguous about whether binding details can be specified outside of <port> elements but within the <service> element: While section 2.1 (document structure) allows it, neither section 2.7 (services) nor the schema in Appendix 4.1 allow it.

3. Bindings in WSDL 1.2

The summary of the proposed solution is as follows:

• Modify the <binding> element to:
  1. Allow the definition of bindings for service types as well as for port types.
  2. Allow the definition of reusable bindings not necessarily constrained to a specific serviceType, porType etc..
• Modify the <service> element to:
  1. Introduce "address" as a first-class concept for services and ports.
  2. Allow one to specify a service-wide address.
  3. Optionally, allow one to specify port-specific addresses. If no service-wide address is given then of course port-specific addresses must be given.
  4. Allow a service or port definition to apply multiple binding property definitions (instead of just one).

3.1 Defining collections of binding properties

The proposed WSDL 1.2 <binding> element may contain any collection of binding properties. A <binding> may be restricted to a certain serviceType/portType/operation combination or applicable in any setting.

The proposed syntax is as follows:

 1 <binding name="ncname">
 2   <serviceType name="qname"?>
 3     <!-- binding details -->
 4     <portType name="qname"?>*
 5       <!-- binding details -->
 6       <operation name="ncname"?>*
 7         <!-- binding details -->
 8         <input>
 9           <!-- binding details -->
10         </input>
11         <output>
12           <!-- binding details -->
13         </output>
14         <fault name="qname"?>
15           <!-- binding details -->
16         </fault>
17       </operation>
18     </portType> 
19   </serviceType>
20 </binding>

Line 1 declares a binding with the given name. If a serviceType is named on line 2 then all bindings contained within that element only apply for that serviceType. If not they apply for any serviceType. If a portType is named on line 4, then bindings within that element apply only for that portType (within the serviceType named on line 2, if any). If not they apply for all portTypes (within the serviceType named on line 2, if any). Similarly for bindings on lines 7 (applies for the operation named on line 6, or for all operations if the name is absent), 9, 12 and 15. Thus, the applicability of a binding property is indicated by the position within the abstraction hierarchy that that binding property is placed at.

3.2 Defining services

A WSDL service is an implementation of a serviceType. That is, it's a serviceType with all the additional information needed to actually contact the service, to format the data and to communicate any other information.

Thus, a service is just a serviceType plus some collection of applied binding properties. The binding properties must come from previously defined bindings property bags (see previous section). Each service has an "address" property, where the contents of that address are only defined for specific transport/message bindings of a service. In addition to binding the entire serviceType, one can also specify applicable binding properties and an address property on a per-portType basis using the nested <port> element.

The proposed syntax is as follows:

1 <service name="ncname" serviceType="qname" bindings="list-of-qnames"?>
2   <address> <!-- URI --> </address>?
3   <port name="ncname" portType="qname" bindings="list-of-qnames"?>*
4     <address> <!-- URI --> </address>?
5   </port>
6 </service>

The value of the bindings attribute above allows one to refer to previously defined bindings and apply them at either the service level or the port level. It must of course be the case that those bindings do in fact contain bindings for the same serviceType and portType(s).

4. Examples

4.1 Bindings at Different Levels

The following binding may be used for any serviceType:

<binding name="SOAP-HTTP-DOCUMENT">
  <serviceType>
    <soap:binding transport="http" style="document"/>
  </serviceType>
</binding>

The following binding indicates that when used in serviceType st1, portType pt1 uses a document style binding while pt2 uses an rpc style binding:

<binding name="eg2">
  <serviceType name="st1">
    <portType name="pt1">
      <soap:body transport="http" style="document"/>
    </portType>
    <portType name="pt2">
      <soap:body transport="http" style="rpc"/>
    </portType>
  </serviceType>
</binding>

4.2 A Complete Example

Let us consider the following typical WSDL 1.1 description of a stock quote service (from http://services.xmethods.net/soap/urn:xmethods-delayed-quotes.wsdl):

<?xml version="1.0" encoding="UTF-8" ?> 

<definitions name="net.xmethods.services.stockquote.StockQuote" 
             targetNamespace="http://www.themindelectric.com/wsdl/net.xmethods.services.stockquote.StockQuote/" 
             xmlns:tns="http://www.themindelectric.com/wsdl/net.xmethods.services.stockquote.StockQuote/" 
             xmlns:electric="http://www.themindelectric.com/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
             xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">

  <message name="getQuoteResponse1">
    <part name="Result" type="xsd:float" /> 
  </message>

  <message name="getQuoteRequest1">
    <part name="symbol" type="xsd:string" /> 
  </message>
 
  <portType name="net.xmethods.services.stockquote.StockQuotePortType">
    <operation name="getQuote" parameterOrder="symbol">
      <input message="tns:getQuoteRequest1" /> 
      <output message="tns:getQuoteResponse1" /> 
    </operation>
  </portType>

  <binding name="net.xmethods.services.stockquote.StockQuoteBinding" 
           type="tns:net.xmethods.services.stockquote.StockQuotePortType">
    <soap:binding style="rpc" 
                  transport="http://schemas.xmlsoap.org/soap/http" /> 
    <operation name="getQuote">
      <soap:operation soapAction="urn:xmethods-delayed-quotes#getQuote"/> 
      <input>
        <soap:body use="encoded"
                   namespace="urn:xmethods-delayed-quotes" 
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
      </input>
      <output>
        <soap:body use="encoded" 
                   namespace="urn:xmethods-delayed-quotes" 
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> 
      </output>
    </operation>
  </binding>

  <service name="net.xmethods.services.stockquote.StockQuoteService">
    <documentation>net.xmethods.services.stockquote.StockQuote web service</documentation> 
    <port name="net.xmethods.services.stockquote.StockQuotePort"
          binding="tns:net.xmethods.services.stockquote.StockQuoteBinding">
      <soap:address location="http://66.28.98.121:9090/soap" /> 
    </port>
  </service>
</definitions>

Here is the same service described using the new syntax:

<?xml version="1.0" encoding="UTF-8" ?> 

<definitions name="net.xmethods.services.stockquote.StockQuote" 
             targetNamespace="http://www.themindelectric.com/wsdl/net.xmethods.services.stockquote.StockQuote/" 
             xmlns:tns="http://www.themindelectric.com/wsdl/net.xmethods.services.stockquote.StockQuote/" 
             xmlns:electric="http://www.themindelectric.com/"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
             xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">

  <message name="getQuoteResponse1">
    <part name="Result" type="xsd:float" /> 
  </message>

  <message name="getQuoteRequest1">
    <part name="symbol" type="xsd:string" /> 
  </message>
 
  <portType name="net.xmethods.services.stockquote.StockQuotePortType">
    <operation name="getQuote" parameterOrder="symbol">
      <input message="tns:getQuoteRequest1" /> 
      <output message="tns:getQuoteResponse1" /> 
    </operation>
  </portType>

  <serviceType name="SQST">
    <portType name="net.xmethods.services.stockquote.StockQuotePortType"/>
  </serviceType>

  <binding name="net.xmethods.services.stockquote.StockQuoteBinding">
    <serviceType name="SQST">
      <soap:binding style="rpc" 
                    transport="http://schemas.xmlsoap.org/soap/http"/> 
      <portType name="net.xmethods.services.stockquote.StockQuotePortType">
        <soap:body use="encoded"
                   namespace="urn:xmethods-delayed-quotes" 
                   encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
        <operation name="getQuote">
          <soap:operation soapAction="urn:xmethods-delayed-quotes#getQuote"/>
        </operation>
      </portType>
    </serviceType>
  </binding>

  <service name="net.xmethods.services.stockquote.StockQuoteService"
           serviceType="SQST"
           bindings="tns:net.xmethods.services.stockquote.StockQuoteBinding">
    <documentation>net.xmethods.services.stockquote.StockQuote web service</documentation> 
    <address>http://66.28.98.121:9090/soap</address>
  </service>
</definitions>

5. Conclusion

The proposed binding changes makes WSDL 1.2 bindings support serviceTypes and also simplifies bindings. It further clarifies the use of address bindings in <service> and <port> elements and makes address a first-class concept of services (and, optionally, ports). By allowing bindings to be independent of any given serviceType, it enables the separation of binding concerns (allows one to define data marshalling binding properties separately from transport properties, for example). The structure of the proposed <binding> element supports convenient defaulting mechanisms to deal with common cases, but is yet flexible enough to deal with the complex cases.