Extending WSDL to Support Features and Bindings

Status

An interest group composed of the following persons contributed to the content of this document:

Glen Daniels (Macromedia)
Youenn Fablet (Canon)
Christopher Ferris (IBM)
Amelia Lewis (TIBCO)
Jean-Jacques Moreau (Canon)
Don Mullen (TIBCO)

The interest group has not achieved general consensus on the content of the document, and discussions seem to lead in several possible directions. The TIBCO participants want to see this published, since it seems likely to add to the general discussion of features. Note, though, that this document is not generally agreed upon by participants; the following issues are known to be important to at least one of the above-mentioned participants.

Abstract features: Should portType or portType/operation be able to require that a binding support a given feature? This proposal does not address the question; it only addresses binding. Participants have stated that the resolution should handle both issues.
Composability: Participants have objected to the idea of allowing featureBindings to be composed with protocolBindings, preferring to see a new protocolBinding when such combinations need to happen.
featureBinding independence: Participants have suggested that featureBinding, especially if associated with a SOAP module, should be independent of protocolBinding, a sibling of protocolBinding, rather than a direct child. This proposal instead attempts to reduce the number of places that feature and protocol binding information may be attached, and to require all such to be (somehow) related.
Separation of data binding from protocol binding: A proposal was made to replace wsdl:binding with wsdl:messageBinding (where information about the format of the message, such as the SOAP message construct, would be specified) and wsdl:protocolBinding (where protocol-specific information would be specified). An alternative might be to use this sort of separation, using the existing wsdl:binding and wsdl:service components, but extending them as suggested. This is a rather dramatic change, so is not included in this proposal.
Location of new elements: This proposal restricts the location of new elements: one new element child of wsdl:binding is proposed, and all other proposed new elements appear therein. Participants have suggested that protocolBinding, featureBinding, and propertyConstraint all might appear in other locations (within binding, and within the proposed messageBinding/protocolBinding trees), including operation, input, output, and fault.

The short version: the interest group could not come to complete agreement on a proposal. Nevertheless, some in the group feel that the discussion ought to take place over the list as a whole, not merely inside the group.

Introduction

It is asserted that binding protocols and features in WSDL is a general problem, not unique to support of the SOAP 1.2 extensibility mechanism, but driven thereby. It is further asserted that a common syntax for such bindings (that is, a syntax in the namespace and thus under the control of the WSDL working group) is preferred to a relatively inconsistent collection of similar, but not necessarily compatible per-protocol and per-feature extension elements.

Therefore, a common mechanism for asserting the protocol binding in use, and the feature extension bindings used with that protocol, is described here. The scope of these new element and attribute information items is strongly circumscribed, to encourage maximum comprehension on the part of WSDL authors.

Protocol and Feature Binding

This proposal suggests that a single new element information item, in the WSDL namespace, be a required child of wsdl:binding.

The required element, wsdl:protocolBinding, describes the network technology used by this service, or its protocol binding. This description is not contained in the WSDL; it is instead an identifier that allows clients or other users of the service to recognize whether they support the technologies that are required for interaction with the service. External protocol binding and feature binding specifications would specify properties, their names (as URIs), their types, and possibly restrictions on their value range.

Current extension elements used for the same, or similar purposes would be removed, including soap:binding and http:binding. Where these supply additional information, it is suggested that extension attributes (or possibly child extension elements) be provided instead.

protocolBinding element information item

The XML representation of a protocolBinding element is an element information item with the following infoset properties:

a [local name] of protocolBinding
a [namespace name] of "http://www.w3.org/@@@@/@@/wsdl"
a mandatory uri attribute information item among its [attributes]
Zero or more element information items among its [children], in order as follows:
- An optional documentation element information item
- Zero or more featureBinding element information items
- Zero or more propertyConstraint element information items

The uri attribute information item indicates, by reference, the protocol binding used by this service implementation. A service implements it. A client (or other user of the service) MUST recognize the content of the attribute as a supported binding, or MUST NOT use the service.

featureBinding element information item

Additional, compatible features (customized for use with the already-specified protocol) may also be bound, by supplying featureBinding element children.

The XML representation of a featureBinding element is an element information item with the following infoset properties:

a [local name] of featureBinding
a [namespace name] of "http://www.w3.org/@@@@/@@/wsdl"
a mandatory uri attribute information item among its [attributes]
Zero or more element information items among its [children], in order as follows:
- An optional documentation element information item
- Zero or more propertyConstraint element information items

The uri attribute information item indicates, by reference, the feature binding extension specification which governs this feature as it extends the protocol (as specified by its parent). A service implementing it always understands it. A client or other user of the service MUST recognize the content of the attribute as a supported feature extension binding, or MUST NOT use the service.

propertyConstraint element information item

Feature and protocol binding specifications bind the abstract properties exposed by implemented features in a protocol-specific fashion. Services may also need to constrain the value range of certain properties (because a service only supports a certain subset of the range of algorithms defined by a specification, for instance).

A propertyConstraint SHOULD appear in its parent featureBinding, or its parent protocolBinding if the protocol requires implementation of the feature that defines the property. It is not an error, however, to place all the propertyConstraint element information items as direct children of protocolBinding.

The XML representation of a propertyConstraint element is an element information item with the following infoset properties:

a [local name] of propertyConstraint
a [namespace name] of "http://www.w3.org/@@@@/@@/wsdl"
a mandatory name attribute information item among its [attributes]
an optional type attribute information item among its [attributes]
an optional string representation of the single permitted value that this service constrains the property to contain as the value of its [text].

The name attribute information item contains the URI identifying this property. A processor that does not recognize the property URI is probably in error, or the WSDL is; all properties that may be constrained SHOULD be indicated by the containing protocolBinding or featureBinding elements. If the property indicated does not refer to a known property associated with the protocol or feature binding, the processor MUST generate an error.

The type attribute information item may be used, if the text content is left empty, to indicate the additional constraints on the property's permissible values, through reference to a known type. If the type name cannot be resolved, the processor MUST generate an error. If both type and text value exist, the processor SHOULD generate an error.

Informal Schema Fragment

To summarize, this proposal suggests that the wsdl:binding subtree would look approximately as follows, using the informal schema description notation of WSDL 1.1. This includes some sample extension attributes from the soap namespace, to illustrate the ease of extending in this fashion.

<wsdl:binding name="NCName" implements="list of QName">
  <wsdl:protocolBinding uri="anyURI" soap:style="document|rpc"?>
    <wsdl:featureBinding uri="anyURI" soap:module="anyURI"? />*
      <wsdl:propertyConstraint name="anyURI" type="QName"?>value?</wsdl:propertyConstraint>*
    </wsdl:featureBinding>
    <wsdl:propertyConstraint name="anyURI" type="QName"?>value?</wsdl:propertyConstraint>*
  </wsdl:protocolBinding>
  <wsdl:operation>+
    <!-- as at present -->
  </wsdl:operation>
</wsdl:binding>

Example

This example uses existing features and bindings defined by SOAP 1.2. It is quite simple; it attempts to show how little intrusion the proposed syntax is for the common case, even with the ability to specify support for an optional feature.

<wsdl:binding name="insuranceBinding" implements="insuranceType">
  <wsdl:protocolBinding uri="http://www.w3.org/2002/06/soap/bindings/HTTP/" soap:style="document">
    <wsdl:featureBinding uri="http://www.tibco.com/xmlns/soap/features/attachment" />
  </wsdl:protocolBinding>
</wsdl:binding>

Notes: the feature binding URI is not the same as the feature URI. The feature URI for the SOAP 1.2 Attachment feature is http://www.w3.org/2002/06/soap/features/attachment". The example presumes a particular HTTP binding of the feature (probably using MIME, MHTML) has been published, associated with the URI specified for the binding. The URI for the protocol binding specifies a particular binding document, for SOAP over HTTP.

soap:module extension attribute

Using the featureBinding syntax, the external schema for a SOAP module may be easily specified by using the soap:module="anyURI" attribute. The URI specified in its value indicates the schema of the header to be produced for the module. This provides an easy example of how particular protocol or feature bindings may extend the provided containers to customize behavior (in this case, indicating that the feature is implemented via a module, and indicating the schema to be used for the instances (headers)).

Here's a more complex example, showing a soap module binding and a constraint.

<wsdl:binding name="listBinding" implements="listType">
  <wsdl:protocolBinding uri="http://www.tibco.com/xmlns/soap/bindings/email/" soap:style="document">
    <wsdl:featureBinding uri="http://www.tibco.com/xmlns/soap/features/compression/email-binding/">
      <wsdl:propertyConstraint name="http://www.tibco.com/xmlns/soap/features/compression/algorithm"
        type="myns:supportedCompressionEnum" />
    </wsdl:featureBinding>
    <wsdl:propertyConstraint 
      name="http://www.tibco.com/xmlns/soap/features/mime-content/content-type">application/xml</wsdl:propertyConstraint>
    <wsdl:featureBinding uri="http://www.example.org/xmlns/soap/feature/body-signature/"
      soap:style="document" soap:module="http://www.example.org/xmlns/soap/feature/body-signature/module" />
  </wsdl:protocolBinding>
</wsdl:binding>

Notes: the example shows a binding to the proposed alternative email binding. It includes a feature binding for a compression feature, which was not included in the protocol binding. It further constrains one property of that feature to include only the values specified in the schema (not shown). The mime-content feature, which is bound by the protocol binding specification document, also has a constrained property. In this case, the constraint is intended to insure that only simple messages may be transferred. Finally, a module is also supplied so that messages may carry digital signatures (these are not real URIs, but the example should be clear enough).

Note that even the complex example isn't, very.

Abstract Features

Note that the URI used in a feature binding is not the same as the URI of an abstract feature. protocolBinding and featureBinding are concrete and implementation specific. This proposal does not address the question of requiring features in the abstract (typically by referencing the feature URI in the portType).

Amelia A Lewis

Last modified: Wed Nov 20 11:06:58 EST 2002