A brief note on contracts and XML-OO mapping

I am a supporter of using tools where appropriate and making the development experience as pleasant as possible. There has been lots of discussion on XML-OO mappings (Google is your friend if you want to find more) and this post adds to it.

I don’t have a problem with using object-oriented languages for building contracts. If writing a class in an object-oriented language is your thing, go for it. Tooling makes it very easy. However, sometimes architects/system designers/developers have to consider the cost of tool-automation. Here’s a simple example attempting to illustrate the mismatch (at least with the tooling I am using):

[XmlTypeAttribute(TypeName="Person", Namespace = "urn:savas:person")]

[XmlRootAttribute(ElementName="person", Namespace = "urn:savas:person")]

public partial class Person

{

   private string firstName = null;

   [XmlElement(ElementName="first-name")]

   public string FirstName

   {

      get { return this.firstName; }

      set { this.firstName = value; }

   }

}

This is a very simple class with some C# attributes to help with the object to XML serialisation (.NET tooling support). We compile the class into a library and then we use the xsd.exe tool to generate the schema for this class…

<xs:schema xmlns:tns="urn:savas:person"

   elementFormDefault="qualified"

   targetNamespace="urn:savas:person"

   xmlns:xs="http://www.w3.org/2001/XMLSchema">

   <xs:element name="person" type="tns:Person" />

   <xs:complexType name="Person">

      <xs:sequence>

    
              <xs:element minOccurs="0" maxOccurs="1" name="first-name" type="xs:string" />
    
  

      </xs:sequence>

   </xs:complexType>

</xs:schema>

Does anyone see a problem with this? But hold on. Before we go there, let’s do the reverse. Let’s use the tooling with this schema to generate a class. So, xsd.exe /c <schema filename> and voila… We get a partial (with .NET 2 beta) class that looks very similar to the one we wrote by hand. Cool one may think. Year, fair enough… this is cool. The tooling makes it really easy for us. We don’t even need to understand XML Schema. We just get this schema and give it to someone. Or, if we use Web Services automation, this schema will be automatically included in our WSDL file and so we never have to touch XML. “How cool is that?” one may still think.

Now, let’s replace the highlighted line in our schema with the following line:

<xs:element minOccurs="1" maxOccurs="1" name="first-name" type="xs:string" />

The result, using xsd.exe on this, is a class that is identical to the one produced when minOccurs=”0″. Eh? Surely not! I see two problems with this:

1. If I give the schema with minOccurs=”0″ as part of my contract to someone, I effectively tell them how I expect the information about a person to be structured and that it is ok to omit the first name. However, my application logic may count on the existence of the first name for its processing needs. Yeah, I can check whether the first name is null or not but why should I have to do this? Just because the tooling does not adequately capture the semantics of my contract (with regards to structure and not the contents of the XML documents) must I check for all possible contract violations?
2. I cannot use automation tools to validate received information before the application logic gets it for processing. When we agree on contracts, it is possible to use modelling techniques and automation tools to validate the information exchanged between parties without ever reaching the application logic. Attempts to create XML-OO mappings invalidate such capabilities. Microsoft‘s Web Services Enhancements runtime, for example, processes security policies (part of a service’s contract) in this manner.

Obviously the above is just a very simple example and it is based on a particular tool limitation (I do hope I haven’t missed something obvious :-). I can see how an ‘IsOptional’ property on the XmlElement attribute could solve this problem. In fact, the [DataContract] serialisation mechanism in .NET 2.0 does exactly that. The point, however, still remains: unless we start thinking in terms of contracts and declarative means for building distributed, service-oriented applications the XML-OO mismatch will haunt us for ever. We need to build domain-specific languages and tools to help us with contract authoring and validation (modelling anyone?).SSDL is an experiment in this space albeit the tooling support is not great at the moment 🙂

The Alpine folks get it!