Staying sane in an XML Web Services World

Thoughts about identities, versions, XML Schema and WSDL
Clemens Vasters (clemensv@newtelligence.com), 2002-07-23

Revised 2002-07-23 21:33 CET: Added rule 3(b)

"If I would rewrite this sentence in a different way, the new sentence would likely have the about the same semantics, but it would be a different one."

The above sentence is an interface; a public interface, expressed in a certain sequence of English words that provides you with access to my thoughts. If the sentence changes, that interface changes. It's very logical.

The above sentence provides you with an insight into what I think. What the sentence expresses are semantics. The following sentence is semantically equivalent to the above sentence:

"It would be a different sentence, would I rewrite this sentence differently, but the new sentence would likely have the same semantics."

There is little room for debate whether the interface, the public representation of these semantics, has changed. There may be some minmal variations of semantics arising from the order, grammar and word choice and therefore special emphasis of expressions, but what I want to say is properly and comprehensively expressed in both variants.

Sentences don't know versions. If you change a sentence, that is a certain grammatically and semantically meaningful sequence of words, everyone will perceive this as a new and different sentence - maybe one that flows better and can be better understood. Would Grisham, Clancy, Crichton and King describe the very same rainy day with low hanging clouds and chilly cold wind gusts from the east - they may all be creating about the same image in your head, but they would sure have entirely different ways to express it.

Semantics do know versions. If I would rewrite these paragraphs in a different way and add or remove information, I would be saying about the same and everyone would perceive this as a revision of what I wrote before. Noone would perceive this as entirely new and noone would possibly pay as much attentions as when reading it for the first time. The semantics may become poorer or richer but they will be perceived as variants of my previous writing.

In XML, the interface is XML Schema. No, it's a way to help expressing semantics. XML Schema by itself does express syntax, not semantics. However, the namespace identifier does associate this syntax with ownership and intent. Actually it's a tool to create templates for "sentences of XML" that express full semantics (which is data). The actual interface instance that you are using is an XML Infoset, which is created based on a grammar expressed in XML Schema. There are many ways to say the same thing, even in XML. XML Schema provides a strict rule set for one way to say a thing. XML Schema doesn't know versions; the requirements that serve to create XML Schema do know versions.

Using XML, we express semantics in a well defined way. We use a well defined way to allow others understand what we say so that they can create software components that automatically understand what we say. There are many ways to say the same thing, even in XML. If a software components understands one way we say a thing (a certain XML Schema), nothing stops the author of the software component from making it understand the same thing expressed in a second, third and fourth way (other XML Schemas). Increasingly, the software component becomes smart enough to distinguish different ways to  say the same thing, just as much as we learn different ways to express and understand the same thing when we learn a new language. Such knowledge and capability to understand and express different ways for saying the same thing does indeed know versions; it evolves.  Evolution is the concept behind versioning. A sentence does never evolve, a story does.

Software knows versions, interfaces don't. Endpoints for XML processing know versions, XML doesn't.

WSDL employs XML Schema. It contains one or more Schemas expressing messages, which are grouped into message exchanges (operations), that are grouped into ports (interfaces) and then bound to transports. WSDL describes how things expressed in XML Schema can flow. WSDL is immutable and cannot change and can't have versions, because XML Schema can't have versions. Changing XML Schema means creating a new Schema and when propagating this change into WSDL, you pull out the old and insert the new Schema. Without any doubt, you are therefore creating a whole new, incompatible WSDL.

Derived rules for Staying sane in an XML Web Services world:

1. XML Schema is immutable. It never changes. If you change a Schema, it becomes a new Schema with its own identity (namespace-URI) #
2. XML Schema does not know versions, they know derivations. If you want to extend a Schema, create a new one, import or reference the old one and restrict or extend the existing types. #
3. (a) XML Schema doesn't know upwards or downwards compatibility, software components understanding multiple Schemas know such a thing. #
3. (b) XML Schema knows extensibility, however. Carefully consider providing extensibility points in your messages through the use of xsd:any. #
4. XML Schema is based on semantics. If the underlying semantics change so that they are largely incompatible with the previous semantics, the Schema changes and becomes a new one, even if it would be technically sufficient to express the new semantics. (Note: This is the somewhat gray area; dramatic example: A customer of a bank's credit department is not semantically equivalent to that same customer later chased by their financial collections dept.; it starts with the bank liking that customer a lot less at that later time.) #

5. WSDL is immutable. It never changes. If you change a WSDL description, it becomes a new WSDL description with its own identity (namespace-URI) #
6. WSDL doesn't know versions and it doesn't know derivations. #
7. WSDL doesn't know upwards or downwards compatibility. Web Services providing endpoints understanding message exchanges compliant to multiple different WSDL descriptions know such a thing. #

8. The identity of a WSDL description is dependent on any of the XML Schemas it is using. Not everyone may be as smart as you are and never ever change a Schema and not changing the Schema identity at the same time. If you import (reference) foreign Schema into your WSDL, you must rely on that Schema never changing. If the Schema ever changes (see 1.), you have a problem you can't solve. To make this easier for everyone, educate everyone you know to follow rule #1 #

If you *ever* update WSDL or XML Schema without assigning a wholly new namespace-URI, you are one of the founding fathers or mothers of a huge, distributed, uncoordinated, disfunctional and unmanageable mess of inconsistencies that will make "DLL Hell" and COM's "Interface Hell" look like a great thing to go back to and feel good about. Just don't be one of them.

For ASP.NET Web Services this means, consequently: 

1. Use the [WebService(Namespace="http://myserver/myservice/myInterface/2002/07/23")] attribute on your WebService class. Always.  #
2. If you add, remove a [WebMethod] or change any of your [WebMethod]s signatures or any of the types used directly or indirectly in any of those signatures, change the namespace! #
3. If you happen to return or accept typed .NET DataSets and the DataSet schema changes, change the DataSet namespace and for the Web Service change the namespace! #
4. If you wonder how you can support "legacy clients" with all these namespace changes and all the resulting incompatible WSDLs, you may just have found a good reason why people say that the backend implementation doesn't belong into the web method, but into a backend component. Like XML Schema and WSDL, Web Service implementations don't know versions, backend components do.  #
5. Every time you change the namespace, you must create a new Web Service endpoint (.asmx) for the new namespace, if you at all worry about backwards compatibility for the clients that could still talk to you yesterday. #

Last update: 8/2/2002; 10:19:57 PM.