WSDL Tales From the Trenches, Part 3
This article is the third and final part of the WSDL Tales from the
Trenches series, and in it I concentrate on the data in web services.
More specifically, I examine the type definitions and element declarations
types element of a WSDL document. Such types and
elements are for use in the abstract messages, the
elements in a WSD.
WSDL does not constrain data definitions to W3C XML Schema (WXS). However, alternatives to WXS are not covered in this article: the goal of the series is to provide help and guidance with current real-world problems, and I have not seen any of the alternatives to WXS being used for web services on a significant scale to date. This may change in the future: while only the WXS implementation is discussed in the WSDL 1.1 spec, it was always the intention of the WSDL designers to provide several options. The WSDL 1.2 draft's appendix on Relax NG brings this closer to realization.
Data modeling with WXS is not for the faint-hearted. It presents a lot of pitfalls. This article will point some of these out and helps you avoid them. At the very least, it should caution you to tread carefully. I will not attempt to explain WXS. There is a wealth of good texts that do so; this article focuses on how to do basic data modeling for web services. Many of the more advanced topics are avoided.
Importing data definitions
Data may be defined directly in the
types element of a
document containing abstract messages. The recommended practice, however,
is to import a separate document; the previous installment discussed the
increased readability, extendibility and opportunities for reuse this
This can be done by using WSDL's
import element or by
using WXS's. Although they have the same name, they are different
elements as they reside in different namespaces. In order to distinguish
them, I will refer to WSDL's element as
wsdl:import and use
xsd:import to denote that of WXS. I will explain the
difference between them with examples of both mechanisms.
wsdl:import to import another
WSDL document that only contains data definitions. In other words,
the only top level element is
Note that the WSDL 1.1
specification's example 2, a stockquote service, does not do either of
these: it uses
wsdl:import to import a schema at top level.
However, WS-I (draft) basic profile clarifies the import mechanism in rules
2001 to 2004 and castigates the W3C Note for "... incorrectly
show[ing] the WSDL import statement being used to import WXS
The above examples are in essence the same as those the WS-I basic
profile offers as a correction to WSDL 1.1's, except that in the basic
profile examples the imported and importing element have the same target
namespace. In the case of
xsd:import, this is wrong; the WXS
spec does not allow it. In the case of
wsdl:import, it is
unfortunate; as pointed out in the previous installment, this is bad style
and should have been disallowed.
If it takes several documents to define a schema with a single
xsd:redefine should be
Schema Design Styles
This section is about what data definitions should be exposed and which should be hidden. The trade off is between the potential for reuse and a narrow interface.
Rule 2203 of the basic profile stipulates that abstract message parts,
bound to a concrete message transporting an RPC invocation, should be
defined using the
Rule 2204 states that abstract message parts used in document-style
invocation should have an
element attribute. If you are
using SOAP, it is a good idea to try to stick to these rules, even though
it makes a mockery of the "abstract message" doctrine. Therefore, there
must be an exposed type definition for data passed as a parameter to an
RPC invocation and an exposed element declaration for a document-style
invocation. In the latter case, this means that the
element may well end up with mainly element declarations and little or no
type declarations. It looks confusing but, as Roald Dahl's BFG said,
"what I mean and what I say are entirely different things."
The Russian doll design style defines root elements globally. Elements that cannot be a document's root are defined as the need arises and so are attributes and types; these definitions are nested in the definitions that use them. Such definitions nested inside another definition are said to be local and cannot be reused in other definitions, neither by other components in the same schema nor by external components. Moreover, type definitions are anonymous and cannot be referenced.
A salami slice, on the other hand, declares all elements globally. A third design style is referred to as Venetian blinds. Venetian blinds define all types globally but only expose the elements that can be used as root element of a document.
Clearly, none of these styles is optimal with respect to the trade off
presented. However, it is instructive to contrast the three styles with
respect to the set criteria. In a web services context, the equivalent of
appearing as a root element of a document is to occur as the value of the
element attribute on an abstract message
part. Since neither Russian doll nor salami slice exposes
types, they cannot be used if you want to do RPC style invocation.
Venetian blinds, on the other hand, works with both RPC and document style
invocation. Venetian blinds encourage the reuse of types since it defines
them all globally. However, some types may not be intended for reuse
while their global definition makes the interface less narrow.
For a document style web service, Russian doll could not be improved upon if the only objective were a narrow interface. It does not score well on the reuse front though. Salami slice sits at the other end of this spectrum with a high score for reuse and a low one for narrowness.
Pages: 1, 2