XML.com: XML From the Inside Out
oreilly.comSafari Bookshelf.Conferences.


WSDL Tales From the Trenches, Part 3

August 05, 2003

Defining Data

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 in the types element of a WSDL document. Such types and elements are for use in the abstract messages, the message 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 brings.

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.

stockquote.wsdl uses wsdl:import to import another WSDL document that only contains data definitions. In other words, the only top level element is types.

The 2nd variant does not import a WSDL document but a schema. In order to do so, it must use xsd:import as a child element of schema, which, in turn is a child of types.

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 definitions".

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 namespace, xsd:include or xsd:redefine should be used.

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 type attribute. 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 types 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.

Example 1, 2 and 3 illustrate the respective styles. All three have this instance document among their productions.

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

Next Pagearrow