Web Service Contract Versioning Fundamentals Part I: Versioning and Compatibility

<xsd:element name="LineItem" type="LineItemType"/>
<xsd:complexType name="LineItemType">
  <xsd:sequence>
    <xsd:element name="productID" type="xsd:string"/>
    <xsd:element name="productName" type="xsd:string"/>
    <xsd:any minOccurs="0" maxOccurs="unbounded"
      namespace="##any" processContents="lax"/>
  </xsd:sequence>
  <xsd:anyAttribute namespace="##any"/>
</xsd:complexType>

Example 1: A complexType construct containing fine and coarse-grained constraints.

As indicated by the bolded text, there are elements with specific names and data types that represent parts of the message definition with a fine level of constraint granularity. All of the message instances (the actual XML documents that will be created based on this structure) must conform to the these constraints in order to be considered valid (which is why these are considered the absolute “minimum” constraints).

The red text shows the element and attribute wildcards also contained by this complex type. These represent parts of the message definition with an extremely coarse level of constraint granularity in that messages do not need to comply to these parts of the message definition at all.

The use of the terms “fine-grained” and “coarse-grained” is highly subjective. What may be a fine-grained constraint in one contract may not be in another. The point is to understand how these terms can be applied when comparing parts of a message definition or when comparing different message definitions with each other.



Versioning and Compatibility

The number one concern when developing and deploying a new version of a service contract is the impact it will have on other parts of the enterprise that have formed or will form dependencies on it. This measure of impact is directly related to how compatible the new contract version is with the old version and its surroundings in general.

This section establishes the fundamental types of compatibility that relate to the content and design of new contract versions and also tie into the goals and limitations of different versioning strategies that we be introduce at the end of this chapter.

Backwards Compatibility

A new version of a Web service contract that continues to support consumer programs designed to work with the old version, is considered backwards-compatible. From a design perspective, this means that the new contract has not changed in such a way that it can impact existing consumer programs that are already using the contract.

A simple example of a backwards-compatible change is the addition of a new operation to an existing WSDL definition:

<definitions name=”Purchase Order” targetNamespace=
  "http://actioncon.com/contract/po"  
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:tns="http://actioncon.com/contract/po"
  xmlns:po="http://actioncon.com/schema/po">
  ...
  <portType name="ptPurchaseOrder">
    <operation name="opSubmitOrder">
      <input message="tns:msgSubmitOrderRequest"/>
      <output message="tns:msgSubmitOrderResponse"/>
    </operation>
    <operation name="opCheckOrderStatus">
      <input message="tns:msgCheckOrderRequest"/>
      <output message="tns:msgCheckOrderResponse"/>
    </operation>
    <operation name="opChangeOrder">
      <input message="tns:msgChangeOrderRequest"/>
      <output message="tns:msgChangeOrderResponse"/>
    </operation>
    <operation name="opCancelOrder">
      <input message="tns:msgCancelOrderRequest"/>
      <output message="tns:msgCancelOrderResponse"/>
    </operation>
    <operation name="opGetOrder">
      <input message="tns:msgGetOrderRequest"/>
      <output message="tns:msgGetOrderResponse"/>
    </operation>
  </portType>
</definitions>

Example 2: The addition of a new operation represents a common backwards-compatible change.

In this example we’re borrowing the abstract description of the Purchase Order service that was initially built at the end of Chapter 7. By adding a brand new operation, we are creating a new version of the contract, but this change is backwards-compatible and will not impact any existing consumers.

An example of a change made to a schema for a message definition that is backwards compatible is the addition of an optional element:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://actioncon.com/schema/po"
  xmlns="http://actioncon.com/schema/po">
  <xsd:element name="LineItem" type="LineItemType"/>
  <xsd:complexType name=“LineItemType”>
    <xsd:sequence>
      <xsd:element name=“productID” type=“xsd:string”/>
      <xsd:element name=“productName” type="xsd:string"/>
      <xsd:element name=“available” type="xsd:boolean"
        minOccurs=”0”/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Example 3: In an XML Schema definition, the addition of an optional element is also considered backwards compatible.

Here we are using a simplified version of the XML Schema definition for the Purchase Order service. The optional available element is added to the LineItemType complex type. This has no impact on existing consumers because they are not required to provide this element in their messages. New consumers or consumer programs redesigned to work with this schema can optionally provide the available element.

Changing any of the existing elements in the previous example from required to optional (by adding the minOccurs=”0” setting) would also be considered a backwards-compatible change. When we have control over how we choose to design the next version of a Web service contract, backwards compatibility is generally attainable. However, mandatory changes (such as those imposed by laws or regulatations) can often force us to break backwards compatibility.

Note that both the Flexible and Loose versioning strategies explained in Part II of this article series support backwards compatibility.

Forwards Compatibility

When a Web service contract is designed in such a manner so that it can support a range of future consumer programs, it is considered to have an extent of forwards compatibility. This means that the contract can essentially accommodate how consumer programs will evolve over time. The most common means by which forwards compatibility is attempted in message definitions is through the use of wildcards:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://actioncon.com/schema/po"
  xmlns="http://actioncon.com/schema/po">
  <xsd:element name="LineItem" type="LineItemType"/>
  <xsd:complexType name=“LineItemType”>
    <xsd:sequence>
      <xsd:element name=“productID” type=“xsd:string”/>
      <xsd:element name=“productName” type="xsd:string"/>
      <xsd:any namespace="##any" processContents="lax"
        minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:anyAttribute namespace="##any"/>
  </xsd:complexType>
</xsd:schema>

Example 4: To support forwards compatibility within a message definition generally requires the use of XML Schema wildcards.

In this example, the xsd:any and xsd:anyAttribute elements are added to allow for a range of unknown elements and data to be accepted by the Web service contract. In other words, the schema is being designed in advance to accommodate unforeseen changes in the future. Chapter 22 explains in detail how wildcards can be used in support of forwards compatibility.

There are limited options in support of forwards compatibility when it comes to WSDL definitions. These are discussed at the end of Chapter 21.

It is important to understand that forwards compatibility is by no means an exact science. A service with a forwards-compatible contract will often not be able to process all message content. It’s contract is simply designed to accept a broader range of data unknown at the time of its design.

Note: Forwards compatibility forms the basis of the Loose versioning strategy that is explained at the end of this chapter.

Compatible Changes

When we make a change to a Web service contract that does not negatively affect its existing consumers, then the change itself is considered a compatible change.

Note that in this book, the term “compatible change” refers to backwards compatibility by default. When used in reference to forwards compatibility it is further qualified as a forwards-compatible change.

A simple example of a compatible change is when we set the minOccurs attribute of an element from “1” to “0”, effectively turning a required element into an optional one, as shown here:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://actioncon.com/schema/po"
 xmlns="http://actioncon.com/schema/po">
  <xsd:element name="LineItem" type="LineItemType"/>
  <xsd:complexType name=“LineItemType”>
    <xsd:sequence>
      <xsd:element name=“productID” type=“xsd:string”/>
      <xsd:element name=“productName” type="xsd:string"
        minOccurs=”0”/>
      <xsd:element name=“available” type="xsd:boolean"
        minOccurs=”0”/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Example 5: The default value of the minOccurs attribute is “1”. Therefore because this attribute was previously absent from the productName element declaration, it was considered a required element. Adding the minOccurs=”0” setting turns it into an optional element, resulting in a compatible change.

This type of change will not impact existing consumer programs that are used to sending the element value to the Web service, nor will it affect future consumers that can be designed to optionally send that element.

Another example of a compatible change was provided earlier in Example 3, when we first added the optional available element declaration. Even though we extended the type with a whole new element, because it is optional it is considered a compatible change.

Here is a list of common compatible changes that we will be discussing in the upcoming chapters:

We will also be exploring techniques whereby changes that are not normally compatible can still be implemented as compatible changes.

Incompatible Changes

If after a change a contract is no longer compatible with consumers, then it is considered to have received an incompatible change. These are the types of changes that can break an existing contract and therefore impose the most challenges when it comes to versioning.

Note that as with the term “compatible change,” this term also indicates backwards compatibility by default. When referring to incompatible changes that affect forwards compatibility, this term will be qualified as forwards-incompatible change.

Going back to our example, if we set an element’s minOccurs attribute from “0” to any number above zero, then we are introducing an incompatible change:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://actioncon.com/schema/po"
  xmlns="http://actioncon.com/schema/po">
  <xsd:element name="LineItem" type="LineItemType"/>
  <xsd:complexType name=“LineItemType”>
    <xsd:sequence>
      <xsd:element name=“productID” type=“xsd:string”/>
      <xsd:element name=“productName” type="xsd:string"
        minOccurs=”3”/>
      <xsd:element name=“available” type="xsd:boolean"
        minOccurs=”3”/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Example 6: Incrementing the minOccurs attribute value of any established element declaration is automatically an incompatible change.

What was formerly an optional element is now required. This will certainly affect existing consumers that are not designed to comply with this new constraint, because adding a new required element introduces a mandatory constraint upon the contract.

Common incompatible changes that are explained in the next set of chapters include: