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

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.


Categories: XML | XML Web Services
Tracked by:
"More on Contract-First Web Service Design" (Dare Obasanjo aka Carnage4Life) [Trackback]
"Conversations about Contract-First Design" (Girish Bharadwaj) [Trackback]
http://www.google.com/search?q=mduwjtus [Pingback]
http://weblogs.asp.net/cibrax/archive/2007/01/25/services-in-net-part-i.aspx [Pingback]
http://host230.hostmonster.com/~betavisa/sitemap1.html [Pingback]
http://fwmwly7.net/arizona/sitemap1.html [Pingback]
http://vy3i7wz.net/windows/index.html [Pingback]
http://tb9wlm3.net/00/index.html [Pingback]
http://lvxjtu6.net/photo/sitemap1.html [Pingback]
http://node22.myserverhosts.com/~boosters/ [Pingback]
http://hrtfjhk.net/sitemap1.html [Pingback]
http://kiva.startlogic.com/sitemap1.html [Pingback]
http://host239.hostmonster.com/~blogford/sitemap2.html [Pingback]
http://fastblog.sc101.info/dental/sitemap1.html [Pingback]
http://umatutman.com/storage/sitemap1.html [Pingback]
http://blogfordummies.org/sitemap1.html [Pingback]
"how to sell a home fast" (how to sell a home fast) [Trackback]
http://pnge0ap.net/sitemap1.html [Pingback]
http://box432.bluehost.com/~zbloginf/sitemap1.html [Pingback]
http://gator442.hostgator.com/~hockteam/ebay/sitemap1.html [Pingback]

Friday, April 22, 2005 4:33:28 PM (GMT Daylight Time, UTC+01:00)
Mmm, I kind of agree with you. Starting with WSDL and hoping that the toolkits Gods (all of them) smile on you as they fumble their way back to objects isn't the current way to go for interoperability.

I would add a Captain Obvious style statement though, in that it depends on what your objects are up to. For every bad WSDL I've seen, I've seen at least as many chatty, coupled, look-you-are-just-next-door-aren't-you? object facades thrown on with equally bad results.

So the lesser of two evils of inappropriate web services/XML calls on a granular object model vs how 'impedance encouraging' the contract-first toolkits are?

- David
Friday, April 22, 2005 4:33:49 PM (GMT Daylight Time, UTC+01:00)
Dare, I read your XML Schema guidelines on XML.com where you advocate the "careful use" of substitution groups. At the same time, I've also read your MSDN article on how the .NET XmlSerializer does not support Substitution groups.

In my environment, I have to work with existing schemas that do have substitution groups, which leaves me in a bit of a pickle if I am using .NET.

Is there any guidance available on how Substituion groups can be used with .NET 1.1?
Anil John
Friday, April 22, 2005 5:49:24 PM (GMT Daylight Time, UTC+01:00)
What do you think of skewing the Contract First approach to mean Message First? This way the focus is on passing messages, and not serialized object graphs, which should greatly reduce the XML/Object impedance mismatch issues.
Friday, April 22, 2005 6:01:44 PM (GMT Daylight Time, UTC+01:00)
But even if you go the message first route, some consumer down the road is going to want to serialize it to objects because they're just learning this web services thing and its the easiest route for them. You'll want to restrict the messages to something they can deal with.

Trust me, not every client is going to have "XML" in their name Don. ;) I'm dealing with a client who has to expose their system as a web service to us and this is the first time they've ever done this. I just want to get in there and write it for them. ;)
Saturday, April 23, 2005 12:23:35 AM (GMT Daylight Time, UTC+01:00)
Dare, I have always read your posts with a lot of interest, and this one, all the more so. I am one of those people who have done a fair amount of integration and interop work when it comes to Web Services and I do see merits in both approaches. However, I have a comment wrt to your statement here:

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

You are assuming that both ends run on the same engine here, correct ? Because, hypothetically speaking, if my platformA toolkit is gonna generate (code-first) some XSD gunk that is not supported (yet...) by platformB's toolkit, arent we back to Square One ?

There is also another key principle. As a WSDL client, I consume the WSDL first to create the helpers that will help me generate what the message will look like on the wire. Why cant this be applied on the service side ? I would be very interested in gathering your thoughts and expertise on this issue.

Another type of XML service project I have come across is those with a "Service-2-Service" genre type where you get 4 pointy-haired bosses of equal ranking but from different companies (and diff platforms) sitting down on the same table thrashing out what the final exchanged message will look like on the wire amongst all four. Remember there is no central dictator that says - "Here is my schema. Use it or lose my business. Period". Since they are all of different 'cultures and diversity', there is ONLY ONE object model to speak of - WSDL / XSD. After all 4 of them agrees to a certain schema, they will send it back to the kitchen to cook up the brew that throws exactly what the wire wants to see. If one of them companies should realize later (in ultimate shock) that their platform cannot handle certain WSDL / XSD constructs, it is always deemed to be the toolkit's fault. Remedy: Upgrade the toolkit or Hack it. Changing the engine would be deemed too drastic a move. The approach of having all four pointy-haired people sitting down on the same table thrasing out and finally deciding on the actual schema right beforehand is NEVER questioned. Your thoughts on this as well ?

If you can email me your thoughts as well on the above, I would really appreciate it.

I think Aaron's article is quite clear in terms of prescriptive guidelines. Use contract-first when interop is at stake; Use code-first when productivity is key.
Saturday, April 23, 2005 12:59:19 AM (GMT Daylight Time, UTC+01:00)
Both 'code first' and 'contract first' approaches have interoperability issues due to the impedance mismatch between XSD and objects. My post is basically challenging the assumption that 'contract first' is better for interop than 'code first'. Both of them suck, but 'contract first' often leads to hairier interoperability problems than 'code first'. There is enough linked information from my blog post that shows why this is the case.

Aaron's guidelines do not encourage interoperability as the linked post on XML-DEV points out.
Saturday, April 23, 2005 3:17:03 PM (GMT Daylight Time, UTC+01:00)

Are trackbacks supported here? I'm a blogging newbie, and can't figure out how. Here's a low-tech trackback:

Tuesday, April 26, 2005 10:44:14 PM (GMT Daylight Time, UTC+01:00)
I write my applications in IL, interfaces in IDL, orchistrations in BPEL, WS-contracts in WSDL and documents in WML.
It gives me control.
Friday, June 17, 2005 11:38:44 AM (GMT Daylight Time, UTC+01:00)
You got a point ;-)
But in general code first means a way of hacking the approach (most people do not want to deal with dirty schemas...). What about the plain old example of using a dataset in your web method. This does not make sense when it comes to interoperability. But can someone create interoperable service in code first approach? Absolutely 'yes' as long as they are *aware* about it.

IMO, this level awareness applies to the contract first design too.

However designing the contracts first, makes it much easier to think in terms of schema you are going to share with others (i.e. data types you use in your contract). Whether it's code first or contract first, ultimately you are going to share this schema. So doesn't it sound more appropriate to define your contracts by yourself rather than letting a generator to generate it according to your programming constructs? In fact code base approach is more prone to use the unique features available in the *programming language* resulting non-interoperable contracts. So it sounds more appropriate to use the features in *XSD* as it's the common thing to everyone.

So I’m with Aaron :-)
Monday, August 15, 2005 11:07:41 PM (GMT Daylight Time, UTC+01:00)
As per Aaron's article of creating the schema, wsdl first and then using it to generate classes would work better, But why should I switch to this time-consuming approach when current code-first approach is working just fine for me.

As a developer, I am having hard time in understanding the benefit of contract-first approach over code-first development (with interface based parameters exchange design ) Unless I have to conform to an already given contract or schema.

is it just a standard way of coding that we are trying to promote to bring uniformity?

If we define the public interfaces (I mean C# keyword Interface) in VS.Net; Do the code-first development using those interfaces for message exchange and let framework create the schema for it; Why would we not get the flexibility of a well defined contract (given that schema is generated by the dot-net framework).

Any comments.
Comments are closed.