DRAFT Proposal : WSDL Description of SOAP 1.2 Features

Glen Daniels, Macromedia
September 4, 2002

0 Summary

This is a brief proposal which demonstrates one way SOAP features, properties and modules could be directly described by WSDL, giving WSDL processors useful metadata about the semantics available to or required by SOAP services.

1 Background : SOAP Features

The SOAP 1.2 specification defines extensibility in terms of "features" [1]. Features are abstractly defined pieces of functionality which generally extend the basic SOAP processing model with semantics such as "security", "correlation", or "routing" among others.

Features are typically described by an abstract "distributed state machine" which operates on XML-like "properties" which act as virtual inputs and outputs to whatever processing occurs (see [2]). These properties and descriptions are bound to specific "on the wire" syntax and semantics in the specifications for SOAP modules and bindings, the pieces of SOAP processors which concretely implement features.

2 What needs to be described?

The reader of a WSDL document may want, or need, to know:

  1. That a given feature is available for use - for instance, "I understand Joe-Bob's correlation module, so using it will likely get you good results "
  2. That a given feature is required for a particular service or operation - for instance "you had better be using WS-Routing when you talk to me"
  3. The values for properties associated with particular features - for instance "the MEP should be set to request-response"

3 Describing abstract Features/Properties

Features and properties come into concrete usage in bindings and modules. However, it may often be useful to describe a service/operation in terms of the abstract features/properties it uses or requires, without regard for how they will be expressed when bound. This is very similar to the way WSDL already provides PortTypes for abstract description of operations, which are then bound to particular protocols. As such, here is a proposed syntax for describing features/properties in the abstract service description portion of a WSDL document:

<portType name="MyService">
  <!-- Correlation feature is used by the whole portType -->
  <soap:feature uri="http://correlation.com/Correlation"/>
  <operation name="GetStockQuote">
    <!-- These properties are in effect for the GetStockQuote operation -->
    <soap:properties>
      <webmeth:method xmlns:webmeth="http://www.w3.org/2002/06/soap/features/web-method/">
        GET
      </webmeth:method>
    </soap:properties>
  </operation>
</portType>

We see two extensions here, <soap:feature>, which indicates that a given feature is used by a portType or operation, and <soap:properties>, which contains property definitions for the portType/operation.

The <soap:feature> element is simply indicative that a given feature is used by or understood by a portType or individual operation. By adding the "wsdl:required" attribute, we can indicate that usage of the feature is mandatory for any clients accessing the portType/operation.

The general pattern inside <soap:properties> is to indicate property values as XML elements - since each property is named by a QName as per [2], we simply use an element with that QName to hold the value (which is typed with XML Schema as per the SOAP spec).

Note : in this first cut at a proposal, I have only spec'ed static values for properties described in WSDL. We may also want to support something like XPath expressions for tying property values to dynamic message data.

Note that it is not necessary to describe an abstract feature in the WSDL in all cases. Typically this is most useful when the abstract feature is required in a PortType/Operation, and the actual expression of the feature is left up to bindings which exist in separate WSDL documents.

4 Features/Properties and Transport Bindings

One way abstract features may be realized is through SOAP transport bindings, as described in [3]. Transport bindings may specify particular features which are supported, and may also specify a set of properties which may be used by an implementation to control various aspects of the binding's behavior. we propose WSDL syntax such as the following for expressing these properties: 
<binding>
  <soap:binding transport="http://www.w3.org/2002/06/soap/bindings/HTTP/"/>
  <operation name="GetStockQuote">
    <soap:properties>
      <soap:mep>http://www.w3.org/2002/06/soap/mep/soap-response/</soap:mep>
      <webmeth:method 
       xmlns:webmeth="http://www.w3.org/2002/06/soap/features/web-method/">
        GET
      </webmeth:method>
    </soap:properties>
  </operation>
</binding>

This example is a "GetStockQuote" operation which uses the SOAP HTTP binding. Inside the <soap:properties> element, we specify first the MEP (Message Exchange Pattern, a type of SOAP feature described in [4]), and then the value for the "webmeth:method" property.

5 Features/Properties and SOAP Modules

Another way to achieve the functionality of SOAP Features is to engage SOAP Modules, which will typically utilize SOAP header blocks to pass relevant data from node to node, implementing the feature that way.

6 Another Example

<portType>
  <operation name="GetBankAccountBalance">
    <soap:feature uri="http://security.com/soap/secure-channel" wsdl:required="true"/>
    ...
  </operation>
</portType>
<binding>
  <soap:binding transport="http://example.com/MySecureTransport"/>
  <soap:module uri="http://security.com/soap/EncryptionModule"/>
  <soap:module uri="http://correlation.com/Correlation" wsdl:required="true"/>
  ...
</binding>

In this case, we see an operation, GetBankAccountBalance, which requires a secure channel feature to be engaged. The WSDL indicates a SOAP binding is in use, over the "http://example.com/MySecureTransport" transport. We can imagine two scenarios for this example - first, let us assume that the "MySecureTransport" specification indicates that the transport binding supplies the secure-channel feature natively. If that is the case, the WSDL processor should be able to figure this out, and know that the requirement is satisfied.

In the second scenario, we posit that the "MySecureTransport" transport does not in fact implement the secure-channel feature. In this case, we need some other way of satisfying the feature requirement, typically with a SOAP Module. At this point, the WSDL processor may look in a "library" of available modules and determine whether it has the ability to satisfy the secure-channel feature or not. The <soap:module> tags in the binding are a "hint" for the processor to make it aware that the service provider is prepared to accept the appropriate headers for the "http://security.com/soap/EncryptionModule" and "http://correlation.com/Correlation" Modules. The WSDL author is not required to specify all available Modules, and the sender is of course free to attempt to send any headers it likes regardless of what appears in the WSDL.

The "Correlation" module in the SOAP binding is marked as required, which means that for any and all operations on the described service, the rules of the module specification must be followed.

References

[1] SOAP Extensibility Model, http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#extensibility

[2] A Convention for Describing Features and Bindings, http://www.w3.org/TR/2002/WD-soap12-part2-20020626/#soapfeatspec

[3] SOAP Protocol Binding Framework, http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#transpbindframew

[4] SOAP-Supplied Message Exchange Patterns and Features, http://www.w3.org/TR/2002/WD-soap12-part2-20020626/#soapsupmep