This document is another attempt to address the issue of supporting the SOAP 1.2 extensibility mechanism (features, MEPs, and protocol bindings) in WSDL 1.2. It attempts to be a minimal solution for binding abstract properties defined in features, MEPs, and protocol bindings, but also generic enough that it could easily be used for property binding of features other than SOAP.
This document is for discussion. It is not the official product of any W3C working group. It is submitted by employees of TIBCO Software, Inc., who participate in and monitor the WSD and XMLP working groups.
Binding Constructed Properties
Glen Daniels (Macromedia) brought this problem to the attention of the WSD working group. The basic question is how best to describe (since WSDL is a description language) the extensibility mechanism introduced in SOAP 1.2. Jean-Jacques Moreau (Canon) and Amy Lewis (TIBCO) contributed to a discussion of what was called "a proposal for SOAP features/properties in WSDL." One of the challenges for this discussion was the fact that, though SOAP 1.2 defines a mechanism, there are few examples of features, MEPs, and protocol bindings, which means less material from which to gather requirements.
TIBCO (the same culprit as is responsible for this document) was producing, at about the same time, a set of proposals, using the extension mechanism, to better define publish/subscribe messaging in SOAP. These materials enlarge the set of examples, and several observations may be drawn from their construction:
From these characteristics, it becomes clear that the major task for a service description is to provide support for the binding of abstract properties to storage locations. It is also clear that each protocol binding may provide slightly different semantics (different possible locations). Working from the existing proposal set, Amy Lewis (TIBCO) attempted to define a WSDL extension for the proposed alternative email binding. The result seemed to indicate that a few new elements might usefully be added to WSDL for generic support of property binding, per-protocol. Thus this document. With generic support, the per-protocol document can become significantly smaller and better focussed.
A variety of syntactic constructs are possible for binding properties. What they all have in common is that they appear as descendants of wsdl:binding. That is (and with the wsdl:module exception shown below), there is no need to place information elsewhere in the WSDL structure; property bindings are associated with wsdl:binding, not portType, nor service, nor anywhere else.
The variety of properties, and preferred locations for them, leads to the creation of either a single wsdl:property element, with content variable on the content of an attribute (a cooccurrence constraint, which is hard to model in grammar-based schema languages), or the creation of wsdl:simpleProperty, wsdl:complexProperty, and wsdl:propertyChoice. The latter variant is proposed here. The names chosen deliberately evoke their models in W3C XML Schema.
This section discusses the content model of wsdl:simpleProperty.
<wsdl:simpleProperty name="QName"? locationType="openEnum" required="boolean">location</wsdl:simpleProperty>
The name attribute is shown here as optional, which is misleading. The name attribute is forbidden when simpleProperty appears as the child of a complexProperty or propertyChoice element, and is required when the simpleProperty appears as the child of a binding, operation, input, output, or fault element.
The locationType attribute uses the Open Value Model described below. Basically, it describes a class of possible storage locations, such as protocol headers, SOAP headers, other properties, and so on. Some of the more common values are described here, but WSDL protocol binding extension specifications are free to add additional types (or to forbid the use of particular types). The examples included below should help to clarify.
The required attribute corresponds to the wsdl:required extension attribute, used on extension elements to indicate that the element must be understood. Since this proposal places the elements in the WSDL namespace, it isn't really appropriate to force the attribute into a named namespace. The attribute is optional; if it is not present, then the property has the required/optional attribute based on the protocol binding extension specification. Normally, when a service overrides this, it is to enforce the use of a particular property (that is, it appears with the value "true"). [[ISSUE: is something like "forbidden" also needed? Or replace the boolean value with an enumeration: required|optional|forbidden?]]
The content of the element is the actual location. For instance, if the locationType is set to "protocolHeader" for an email binding, and the property is address:original-source, the value might be set to From (it might equally reasonably be set to Sender, or even to Return-Path). The protocolHeader enumerated value permits specification of any named header field. Other locationTypes may specify an exact location using other means, such as an offset, or a conventional name (one that appears in the specification for the protocol, but not in individual packets).
[[ISSUE: should a service be able to fix the value of a property? For instance, if there were a content-encoding property in a compression feature (corresponding to the HTTP Content-Encoding header), is it useful to allow a service to specify a value not only for the location (locationType="protocolHeader", text Content-Encoding), but for the value that must appear in the property? (fixedValue attribute?) (per Robin Berjon email)]]
The following values are suggested as part of the base enumeration for locationType:
Other possibilities exist, including: partHeader, protocolOffset, protocolField. The members of the above list are defined here, except for module, which is more completely discussed in Module Definitions.
This element may appear as the child of wsdl:binding, wsdl:binding/wsdl:operation, wsdl:binding/wsdl:operation/wsdl:input, wsdl:binding/wsdl:operation/wsdl:output, or wsdl:binding/wsdl:operation/wsdl:fault. See Binding Scope, below, for a discussion of how storage location is defined.
In some cases, the value of a property does not map well to a single storage location. For those cases, a complexProperty type is provided. It allows the service to specify that the value of a property is to be constructed by manipulating the values of known storage locations in some fashion.
<wsdl:complexProperty name="QName"? required="boolean"?>
<wsdl:algorithm name="string">parameters</wsdl:algorithm>
<choice>
<wsdl:simpleProperty />
<wsdl:complexProperty />
<wsdl:propertyChoice />
</choice>+
</wsdl:complexProperty>
The following example is a binding for the original-source property of the message addressing feature, for a synchronous binding such as HTTP. This example also illustrates the wsdl:simpleProperty binding to a locationType of protocol.
<wsdl:complexProperty name="address:original-source" required="true">
<wsdl:algorithm name="printf-pattern">socket:%1:%2</wsdl:algorithm>
<wsdl:simpleProperty locationType="protocol">IP:Source Address</wsdl:simpleProperty>
<wsdl:simpleProperty locationType="protocol">TCP:Source Port</wsdl:simpleProperty>
</wsdl:complexProperty>
This particular algorithm is simple substitution of the bits into the pattern, printf style, which should be fairly straightforward. Another algorithm type might be simple concatenation (used for the email binding), in which the consituent locations are specified, concatenated together with the character(s) specified in the text node of the algorithm. Other algorithms are possible. One or two, at least, probably ought to be defined here (this is less a definition, and more of an example).
As the template makes clear (hopefully), a complexProperty may contain simpleProperty elements (as in the example), and complexProperty or propertyChoice elements. A nested complexProperty would occur primarily in cases in which different parts of the property value are constructed using different algorithms.
This element may appear as the child of wsdl:binding, wsdl:binding/wsdl:operation, wsdl:binding/wsdl:operation/wsdl:input, wsdl:binding/wsdl:operation/wsdl:output, or wsdl:binding/wsdl:operation/wsdl:fault. See Binding Scope, below, for a discussion of how storage location is defined.
In some cases, it is difficult to assign a single location for property storage, because the locations in use depend upon some processing requirements. propertyChoice specifies a first-non-null algorithm to select from a list of possible storage locations. For instance, a property may be bound, first, to another property (which may be bound, but not contain a value, for instance). It is specified to then fall back to a second property. And failing all that, it may then specify a protocolHeader location.
<wsdl:propertyChoice name="QName"? required="boolean">
<choice>
<wsdl:simpleProperty />
<wsdl:complexProperty />
</choice>+
</wsdl:propertyChoice>
Note that selection may not be nested, since the argument is that it's all the same algorithm, so it's all the same list.
A good example of this might be the failure destination property. It could be bound first to the response-address property, with a fallback to original-source, and possibly a final fallback (in the email binding, perhaps) to the value of the protocol header Return-Path. Thus:
<wsdl:propertyChoice name="faildest:failure-destination">
<wsdl:simpleProperty locationType="propertyReference">address:response-address</wsdl:simpleProperty>
<wsdl:simpleProperty locationType="propertyReference">address:original-source</wsdl:simpleProperty>
<wsdl:simpleProperty locationType="protocolHeader">Return-Path</wsdl:simpleProperty>
</wsdl:propertyChoice>
This element may appear as the child of wsdl:binding, wsdl:binding/wsdl:operation, wsdl:binding/wsdl:operation/wsdl:input, wsdl:binding/wsdl:operation/wsdl:output, or wsdl:binding/wsdl:operation/wsdl:fault. See Binding Scope, below, for a discussion of how storage location is defined.
This specification proposes that the elements defined for binding properties may appear at three different levels of the WSDL document:
<wsdl:binding>
< here! >
<wsdl:operation>
< here! >
<wsdl:input>
< here! >
</wsdl:input>
<wsdl:output>
< here! >
</wsdl:output>
<wsdl:fault>
< here! >
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
This raises the question of scope. The idea behind putting a property binding at the level of a child of the binding is that it is in scope for all operations. Placing it at the level of an operation means that it is in scope for all messages of that operation. Placing it inside a message restricts it to that message only.
When a property binding is redefined in a more restricted scope, it overrides the previous definition. It does not add to the definition, it does not fallback to the previous definition. It overrides it. This can cause interesting loops for careless service describers making use of the propertyReference location type, so it requires care, especially since leaving a required property unbound is considered to be an error.
One of the consequences of the definition using the patterns set forth here is that each WSDL protocol binding extension specification can, potentially, add to the enumeration given above as the type of the locationType attribute (for simpleProperty). In fact, it might also define a new algorithm for the complexProperty. In other words, this document is effectively proposing an open value model for certain attributes, to go with the general open content model of WSDL on the whole.
Because there are any number of potential locationTypes to bind to, and it is unlikely that even the most expert of networking gurus could enumerate them all (and if they did, the confusion between useful and important versus marginal or trivial would be very great), it doesn't make sense to try to specify all the possible ways that the binding can be done. It is part of the responsibility of the SOAP protocol binding extension document to enumerate the sorts of places it expects to find and store properties, and so it is the responsibility of the WSDL protocol binding extension document to specify the keywords that identify these locations.
On the other hand, there are some things that are simply very likely to be encountered, or that are effectively a part of this specification. The propertyReference location type, for instance, is a pointer/reference type, which makes sense only when defined here. The protocol and protocolHeader types are likely to be very common (the HTTP binding could use both). The module binding is also a core piece of soap.
Since a service or client making use of a particular binding must be able to conform to the strictures and constraints of that binding, the WSDL extension specification is a good place to put this information. It might possibly be a good idea, though, not to call it an open enumeration (since the concept doesn't actually exist in any current schema language), but to label it, instead, something like NCName. The permissible NCName values of the attribute would then be specified in the WSDL protocol binding extension specification.
One of the standard means of binding anticipated in SOAP 1.2 is to a SOAP header. In order for this to work nicely, the header needs to be defined in the WSDL. We therefore propose the addition of a wsdl:module element, with characteristics more or less similar to the existing part element.
<wsdl:module name="NCName" uri="anyURI" type="QName"? element="QName" />
The module is defined by reference to a type or element (like part) in a schema (imported or embedded). This definition will define a header, which will be a part of the message. Each property identifies its own location through a modified XPath-y dealie thing, mentioned above.
This is not terribly satisfactory, I'm afraid.