Contract-First XML Web Service Design is No Panacea

Every once in a while I see articles like Aaron Skonnard`s Contract-First Service Development which make me shake my head in sorrow. His intentions are good but quite often advising people to design their XML Web services starting from an XSD/WSDL file instead of a more restricted model leads to more problems than what some have labelled the "code-first" approach.

For example, take this recent post to the XML-DEV mailing list entitled incompatible uses of XML Schema

I just got a call from a bespoke client (the XML guru in a large bank)
asking whether I knew of any XML Schema refactoring tools.

His problem is that one of their systems (from a big company)
does not handle recursive elements. Another one of their
systems (from another big company) does not handle substitution
groups (or, at least, dynamic use of xsi:type.) Another of their
systems (from a third big company) does not handle wildcards.
(Some departments also used another tool that generated ambiguous
schemas.)

This is causing them a major headache: they are having to
refactor 7,000 element schemas by hand to munge them into
forms suited for each system.

Their schema-centricism has basically stuffed up the ready
interoperability they thought they were buying into with XML,
on a practical level. This is obviously a trap: moving to a
services-oriented architecture means that the providers can
say "we provide XML with a schema" and the pointy-headed bosses
can say "you service-user: this tool accepts XML with a schema
so you must use that!" and the service-user has little recourse.

This is one of the problems of contract first development that many of the consultants, vendors and pundits who are extolling its virtues fail to mention. A core fact of building XML Web services that use WSDL/XSD as the contract is that most people will use object<->XML mapping technologies to either create or consume the web services. However there are fundamental impedance mismatches between the W3C XML Schema Definition (XSD) Language and objects in a traditional object oriented programming language that ensure that these mappings will be problematic. I have written about these impedance mismatches several times over the past few years including posts such as The Impedence Mismatch between W3C XML Schema and the CLR.

Every XML Web Service toolkit that consumes WSDL/XSD and generates objects has different parts of the XSD spec that they either fail to handle or handle inadequately. Many of the folks encouraging contract first development are refusing to acknowledge that if developers build schemas by hand for use in XML Web Services, it is likely they will end up using capabilities of XSD that are not supported by one or more of their consuming applications. The post from XML-DEV is just one example of this happening. When I was the program manager for XML Schema technologies in the .NET Framework I regularly had to help customers who had to deal with the interoperability problems they encountered because they`d read some article extolling the virtues of schema first design which failed to acknowledge the realities of the XML Web Service landscape.

From my experience "contract first" design is actually more likely to lead to interoperability problems than "code first" design. The only time this isn`t the case is when the schema designer actually pays attention to use a minimal subset of XSD as opposed to using its full capabilities. This is one of the reasons I have tried to provide some guidance on what XSD features to avoid in my XML Schema Design guidelines series on XML.com.

However it is far easier to avoid these missteps if one starts from objects instead of XSD/WSDL since the expressiveness of objects is less than that of XSD which automatically means the web service contracts are less complicated. I remember getting this insight from Don Box and Doug Purdy a couple of months ago and rejecting it at the time since it seemed anti-XML but now I realize that it is actually the most practical thing to do.