WSDL Tales From the Trenches, Part 3
by Johan Peeters
|
Pages: 1, 2
Namespaces
Namespaces were discussed briefly in the previous installment. There we asked the question, what goes into the WSD's target namespace. Here I address the question what goes into a W3C XML Schema namespace. The rules were briefly reviewed in the previous article, but here we go into more detail with the aid of some examples.
Elements, types and attributes that belong to a namespace are said to be qualified. The declaration of a target namespace is a necessary, but not sufficient condition for elements, types and attributes to be qualified. So when are they qualified and when unqualified?
Let us deal with types first, they are easy: globally defined types, both simple and complex, are always qualified. Locally defined types are anonymous and so there is no way of referencing them; the question to which namespace they belong is purely academic.
Global element declarations are also easy: globally declared elements are qualified.
To illustrate what we know so far, this
instance document is validated by this
schema. We see indeed that the 2 globally defined elements
Element and Response are part of the target
namespace; the locally defined Collection element is not.
Whether or not attributes and locally defined elements are qualified is
governed by the form attribute. The attribute can take 2
values: qualified and unqualified. Therefore,
in order to qualify the Collection element in our previous
example, it can be reworked as so.
You will find that it validates this
document.
form is not a required attribute, neither when declaring
attributes nor local elements. form is assigned a value
implicitly, either by respectively the value of the
elementAttributeDefault and attributeFormDefault
attribute on the schema element, or by the default value of
these attributes; the default value is unqualified in each
case. So here
is another schema that validates the
document.
Note that the Russian doll and Venetian blinds example schemas must stipulate that elements are qualified by default in order to validate the same instance document as the salami slice example.
WSDL 1.1 recommends setting the elementFormDefault to
qualified and keeping the default for
attributeFormDefault. This should minimize the use of
explicit namespace qualifiers if you judiciously set the schema's target
namespace as the default namespace in your messages.
We have only skimmed the surface here; W3C XML Schema (see Resources for a full reference) devotes a complete chapter to controlling namespaces. However, the questions that you will most likely encounter are covered.
Compositors
W3C XML Schema has 3 compositor elements that construct
complex data types from simpler ones: sequence,
choice and all. Particles are nested
inside compositor elements.
A sequence defines a compound structure in which the particles
occur in order. The particles within a choice are mutually
exclusive. However, there may be multiple occurrences of the chosen
particle. all defines an unordered group. For all three
compositors, the number of legal occurrences of the particles within them
is governed by the maxOccurs and minOccurs
attributes on those particles. These attributes are not required and
their default value is 1.
The simplest particle is an element.
sequence and choice can both act as particles
too. all cannot.
The sequence compositor is the one that is most often
encountered in WSDs. This seems a good choice; even if, conceptually,
particles could occur in any order, nailing down the order will make
parsing of messages that bit easier. However, implementations often do
not observe the order constraints. This can be shown by invoking a web
service with elements in a different order from the one laid down by a
sequence: it often does not seem to matter. That is not such a bad thing.
After all, if the server is more liberal in what it accepts than it
strictly needs to be, this does not harm well-behaved clients and it
offers some margin for error on more sloppily implemented clients. In
other words, a server that did this can hardly be accused of being in
breach of contract. Not so if the server cannot guarantee the order of
the particles that are being sent back. Faced with such a server
implementation, I spent a good deal of time working through the
ramifications of this once upon a time.
The first reflex is to replace sequence with
all compositors. However, be aware that the remedy is not
without its problems since the expressiveness of this compositor has been
severely curtailed in the WXS spec. A detailed account of why this is so
and what the precise constraints are, is beyond the current scope.
However, the main limitation has already been pointed out:
all cannot be used as a particle. Since derivation by
extension in effect uses the compositor of the base type as a particle in
the subtype, opportunities for reuse of types defined with
all are limited. Derivation is covered in further detail in
a dedicated section.
Schema versions
The current WXS Recommendation is 1.0 and its namespace is
http://www.w3.org/2001/XMLSchema. However, some
implementations still being used today follow the specifications of
previous working drafts, e.g.
http://www.w3.org/1999/XMLSchema. This is unfortunate and
the perpetrators should be encouraged to migrate to the released standard,
but if you should come across such implementations, here are two of the
common pitfalls. Firstly, there is a WXS data type in common use that has
changed from the 1999 to the 2001 version: 1999's timeInstant
became 2001's dateTime. Make sure that the data type you use
fits the version of WXS. Secondly, derivations also changed significantly
between 1999 and 2001. These will be covered in the following
section.
Derivations
Derivation is a technique to define subtypes of a given base type. There are two kinds of derivation in WXS: extension and restriction. The former adds components at the end of the content model of the base type, the latter constrains the base type. Hence valid instances of a subtype derived by extension are not necessarily valid instances of the base type. Valid instances of a subtype derived by restriction, on the other hand, are always valid instances of the base type.
A subtype may be used anywhere where its base type is used, unless
otherwise specified. This may have the following impact on message
definitions: assume that a message definition declares a part with type
Foo, and Bar is derived by extension from
Foo. A party may send an element of type Bar in
such message. The recipient may be unable to validate this message.
Fortunately, it is possible to turn off the ability to substitute subtypes
for base types by using the block attribute on the base type
or on an element declared to be of a given base type.
Beware of derivation by extension, that is the message of this section so far. But what with derivation by restriction? From the discussion so far, it seems reasonable enough. However, using it may seem less attractive if the need is realized to list each particle of the content model of the subtype explicitly. This makes for very verbose definitions. It also does not bring the modularity benefits that an inheritance hierarchy in an OO programming language might bring: common features are not factored out, but must be repeated in each subtype. This is a change w.r.t. W3C XML Schema 1999 that caused a good deal of confusion.
Arrays
Defining an array is one of the most confusing issues in WSDL. It has also caused a great deal of interoperability problems. Proceed with caution; a common approach is to extend the Array type defined in the SOAP encoding schema. In fact, this is mandated by WSDL 1.1 (see section 2.2). I was therefore surprised to see that the rules 2110 through to 2112 of the WS-I Basic Profile Working Group overrules this. On the other hand, I understand their position: WSDL 1.1 makes a pig's ear of array specifications. The basic profile's approach, on the other hand, is simple.
When I originally planned this article, it was my intention to write a good deal about SOAP arrays, how to use them in WSDs that are as near correct as is possible given the flaws in WSDL 1.1. However, given the basic profile's recommendation, the sensible thing is to avoid them altogether.
Conclusions
The purpose of this article was to flag some of the issues that require attention when modeling data. You should be underestimate neither the importance of defining data nor the complexity of the task. It is important because the data passed across the web service interface largely determine the quality of the interface. It is complex because data modeling is inherently complex. Nonetheless, I cannot help feeling that XML W3C Schema 1.0 does not mitigate this complexity adequately. I look forward to tools better suited to data modeling for web services.
Resources
The W3C has published two normative documents on the XML Schema: XML Schema Part 1: Structures and XML Schema Part 2: Datatypes. There is also a non-normative primer.
XML Schema by Eric van der Vlist, published by O'Reilly, 2002, proved to be an invaluable companion in my encounters with W3C XML Schema. Warmly recommended to anyone who is serious about data modeling with WXS.
xFront has an item on global versus local element and type declarations in its excellent best practices section. While you are browsing the xFront, do have a look at what they have to say about web services as well, which is controversial and thought-provoking.
Share your WSDL experiences in our forum.
(* You must be a member of XML.com to use this feature.)
Comment on this Article
