Contract Versioning

Contract Versioning, Compatibility and
Composability
Kjell-Sverre Jerijærvi, Jean-Jacques Dubray

In the recent weeks, many industry analysts have been prompt to point out fears, uncertainties and
doubts about SOA. Gartner, for instance, claims that companies with plans to start SOA initiatives are
falling, while companies which plan no SOA initiatives have increased from 6 to 16% in the last 12
months. These notes and articles often sound as if companies no longer believe in building reusable IT
assets which can be composed in different solutions.

We believe that the explanation for this lower level of interest in SOA is quite different: one of the key
failure of SOA initiatives has been precisely the inability to produce reusable and composable assets. It
seems as if that every new consumer brings enough fresh requirements to mandate a service different
from existing services. Since services are more expensive to design, build and operate when compared
to more traditional solution architectures, SOA cannot realize a large part of its business case when
these services can’t be reused. To our experience, few companies have been able to move beyond
primitive reuse of services to achieve the promised effects of SOA.

If you ever hope to reuse a service, it is imperative to have clear design guidelines for contracts that
express what this service provides and how it can be consumed. You may be able start your SOA
initiative without much SOA Governance, but it would be a mistake not to have contract design
guidelines. Overtime, these design guidelines will of course become a central part of your SOA
Governance design compliance policies. It seems, however, that the industry as a whole has put a heavy
emphasis on SOA Governance processes as a way to successfully build reusable assets, often dismissing
the “Just a Bunch of Web Services” (JaBoWS) approach, but this strategy has yet to prove that it is
enough to accomplish this particular goal.

We argue that SOA Governance is necessary but cannot generally deliver Service Specifications that are
at the level required for reusing assets over long periods of time. SOA Governance is important, and as
much governance as practical should be practiced when identifying, specifying and designing a service.
However, because of limited resources, time and the inability to predict the future well beyond a 3-6
month horizon, Governance alone cannot create reusable assets. Inevitably, new and unforeseen service
consumers will come with new requirements that will require an evolution of existing services. Without
a proper versioning strategy, new versions of a service will result in a new service altogether, creating
the need for similar, yet separate registry entries, code bases and lifecycles. Organizations without a
proper versioning strategy often deploy, operate and maintain several “versions” of the same service in

1

production drastically limiting SOA’s benefits and Return-On-Investment fueling comments from some
analysts who have been prompt to claim that “reuse” should not be expected as part of a SOA initiative.

In this article, we provide a series of recommended practices for establishing a Service Contract
Versioning strategy geared towards service reuse, composability and compatibility with prior consumers
(or providers). We claim that such versioning strategy is essential to achieve satisfactory levels of service
reuse and in turn generate higher (and expected) ROI from SOA initiatives.

Elements of a contract
“A contract is the most important metadata in SOA”, says Ron Schmelzer, analyst at ZapThink. There are
many parts to a contract between a service provider and a service consumer. Some of these elements
can be made machine readable, and even for some enforceable at runtime, using technologies such as
XML Schema, WSDL and WS-Policy specifications for instance, while other elements will remain mostly
for human consumption only.

The goal of this paper is not necessarily to look at every possible elements of a contract from the format
and sequence of the bits that travel on the wire, to service level agreements or legal statements (about
privacy for instance). Rather, we would like to focus on one simple problem: defining a strategy that
supports the evolution of a service provider or consumer while remaining compatible with existing
consumers or provider, respectively. We believe that this strategy is core to delivering the benefits of
SOA and can greatly reduce both the initial cost of building a service (because it reduces the need for
governance) as well as the ongoing service maintenance and operations costs.

The proposed versioning strategy is twofold:

a) Create machine readable contract elements that express all rules enforced at run-time by both
the service consumer and provider
b) Create or leverage a set of compatibility rules between the versions of the contract elements
agreed upon service consumers and providers

Machine readable contract elements are the foundation of versioning because this metadata can and
must be used by both the service consumer and provider to decide whether the current message sent to
and received at an endpoint will and can legitimately be processed. These elements define the lowest
bar for a potentially successful processing of a given message. Of course, business rules in the service
implementation can potentially return a contract exception.

One strategy could be to define no machine readable contract element and keep exchanging exceptions
each time the consumer or provider cannot process a message, until either the consumer or the
provider fixes the problem. For instance, members of the REST community have advocated the adoption
of a “uniform contract” dismissing the need for further machine readable elements which could have
otherwise provided unambiguous semantics while assisting in the implementation, validation or
configuration of a service. Yet, the REST community does not provide evidence that RESTful Web
Services can be evolved in a compatible way.

2

The problem is less about which contract elements one needs, but how to facilitate the expression of
compatibility between two versions of a service provider (or consumer). In other words if a consumer
interacts with a new version of service provider, are we expecting a behavior equivalent to the prior
version or not? Adopting a “uniform contract” such as agreeing simply on sending and receiving
messages at a particular location is not going to help answer the compatibility question.

In this article we will focus on the metadata necessary to validate whether an incoming SOAP message is
legitimate or not. So we will focus on the contract elements defined in a WSDL document. Since the
usage of WSDL 2.0 is not yet widespread, we will be using WSDL 1.1. We do not believe that there would
be any significant changes when applying this strategy to WSDL 2.0. The elements of WSDL 1.1 include:

 Service definition target namespace
 Message types
 Message definitions
 Port types
 Bindings
 Service definitions
 Optional policies expressed using WS-Policies

Fig 1. Elements of a WSDL 1.1. Contract

Versioning guidelines
Service and Schema Versioning can lead to these types of compatibility scenarios (Fig 2):

 No compatibility
 Forwards Compatible
 Backwards Compatible

3

A new version of a contract that continues to support consumers designed to work with the old version
of the contract is considered to be Backwards Compatible.

A contract that is designed to support unknown future consumers is considered to be Forwards
Compatible. Such a contract anticipates that consumers will evolve over time by supporting extensibility
through XML Schema wildcards. This type of compatibility is often found in B2B scenarios where a
consumer works with multiple service providers which may evolve at a slower pace. In the enterprise,
the most common scenario is backwards compatibility.

Backwards compatibility is what is typically meant by “compatible” and is possible when non-breaking
changes are made to a contract. Making breaking changes to a contract will always lead to no
compatibility. These scenarios have been extensively described in the literature by John Evdemon or
Dave Orchard for instance.

Note that contracts can be both backwards and forwards compatible (more on this later).

Fig 2. Service Operations Compatibility Scenarios

The degree of support of Web Services technologies for both forwards and backwards scenarios is
unmatched in the distributed computing technologies world. Neither RPC, CORBA, DCOM or JEE have
been able to support these scenarios out of the box, simply by applying specific design constrains. As a
matter of fact the ability to support these scenarios is a key to achieving loose-coupling and reuse.

When a service is evolved in a backwards compatible manner, it can be reused by more consumers,
without requiring existing consumers’ implementation or configuration to change. When Governance
has failed to predict the needs of future consumers or when the budget prevented to get all the features
needed in V+0, compatible service versioning is what enables updates without impacting existing
consumers’ operations. In particular, this is how “JaBoWS” can slowly but surely evolve into Enterprise
Class services, serving a wide range of consumers.

4

Compatibility is defined by a stated versioning scheme:

 Major versions: incompatible (breaking change)
 Minor versions: compatible (non-breaking change)

Breaking changes are modifications, for instance, to existing schema types that will cause processing of
incoming messages to fail, such as changing an existing optional element to be mandatory or adding
new required elements. Non-breaking changes are e.g. adding a new optional element. Non-breaking
changes to schemas or services are registered as minor versions, while breaking will always be
registered as a new major version.

All the versionable artifacts of a service will be affected by changes, and these changes will ripple
through the artifacts from bottom to top, and eventually the ripple effect will impact your consumers.
This ripple effect is detailed in table 1 and illustrated in figure 3. While versioning lets you control the
effects of changes, compatibility helps you alleviate some of the negative effects of versioning.

Fig 3. The ripple effect of changes

In the following, we will state that a service version is incompatible using a major version and a
compatible version (forwards or backwards) using a minor version. Point version should be used to
denote versions that did not involve contract changes and were limited to implementation, deployment
or configuration changes (for instance a bug correction, a new service container release, etc). Point
versions are always compatible by definition (again this is a statement not a guaranty).

Artifact Change Major Minor Point

Service Breaking X

Service Non-Breaking X

5

Composite Service Incompatible Schema Service X

Composite Service Compatible Service X

Service Incompatible Schema X

Service Compatible Schema X

Schema Breaking X

Schema Non-breaking X

Schema Aggregate Incompatible Schema X

Schema Aggregate Compatible Schema X

Code Bug fix / maintenance X

Code Safe modifications X

Code Semantic / Unsafe modifications X

Other service Any X
artifacts
Table 1. The versioning ripple effect of changes to code, schemas and services

Two message types can be stated to be compatible using these simple rules when designing Message
Type Schemas:

 XML Namespace values must be constant for a given message type and a given major version
 Message type schemas must include mandatory minor and point version custom attribute on
the message type root element, using for instance a type xsd:int.
 Whether XML validation is used or not, each message consumer must verify that the major
version of an incoming message is matching its own implementation version. An exception
should be returned when the major versions of the message sender and receiver do not match.

In the .Net world, Message Type artifacts are also known as data contracts.

6

Web Services Extensibility Guidelines
The principles of forwards compatibility have been well documented (see also this reference), yet they
are rarely applied. For the sake of clarity we are detailing them here.

Service definition target WSDL target namespace can be different from Message types XML
namespace Schema namespaces. WSDL target namespace must be different each
time the service contract or implementation is modified, be it for a
point, minor or major version
This namespace is not used at runtime, provided that SOAP actions are
defined manually instead of automatically by the runtime. Therefore, all
WSDL definitions MUST include manually defined SOAP actions1
Message types Message type schemas must be designed with the utilization of XML
Schema extensibility mechanisms (we provide a detailed discussion of
these mechanisms below)
Message type namespaces must only refer to a major version of the
service contract, indicating an incompatible service version. Minor
version may be specified as an attribute to the root element
Message definitions Parts can potentially be added to message definitions, we however
recommend to use a single part which contains a message envelope in
which content can be extended using XML Schema’s extensibility rules
Port types Port types can be extended with new operations
No changes can be made to the operation’s signature nor the order in
which the operations are called (which is not specified in WSDL)
Bindings New bindings can be defined, however, existing bindings cannot be
modified, including the endpoint of the service
Service definitions Services definitions can only be extended with new ports, existing ports
cannot be altered
Optional policies expressed There are no general framework available to assess compatibility
using WS-Policies scenarios for policies
Table 2. Service Definition Compatibility Design Rules

The design of Message Types using XML Schema must be carefully planned to achieve forwards
compatibility, also known as XSD extensibility.

John Evdemon explains:

The XML Schema standard introduces <xsd:any> as a wildcarding element.
<xsd:any> enables schemas to be extended in a well-defined manner. <xsd:any>
includes a namespace attribute that either constrains or extends the range of
elements that might appear within the wildcard. The namespace attribute can be
set to any of the following:

##any enables the use of elements from any Namespace to extend the schema.

##targetnamespace restricts wildcards to the elements that appear within the
targetNamespace.

7

##other makes it illegal to extend the schema using elements from the
targetNamespace.

The processContents attribute dictates how schema extensions should be
validated by the parser:

strict requires the parser to validate all schema extensions.

skip turns off validation for schema extensions.

lax validates elements from supported namespaces and ignores unknown or
unexpected elements (most Web services specifications use lax).

Regarding XSD extensibility, there is a snag in the XML Schema’s 1.0 specification. Because of the
unique particle attribution (UPA) rule there is an ambiguity during the validation of XML Schema types
that have an optional or unbounded number of elements as their last element in the type definition. For
that reason, when the last element of the type has a variable cardinality, we have to add a specific
element with a cardinality of exactly one, before using the <xs:any
namespace=“##targetNamespace”…/> element.

For instance, you may want to choose an element such as this one:

<eovMxmy> where x and y are the major, minor version numbers (eov stands for end-of-version)

In XML Schema 1.1 this ambiguity will be removed and this additional element will not be needed.

Using XML Schema extensibility features is one thing, but we still need to define and agree on a set of
rules when an older version of a message consumer encounters a new version of a message. It is likely
that this new message will have elements that fall in the some of the extensibility sections. The question
becomes then, what should we do with these elements? We recommend applying the following rules
which result in Forwards Compatibility requiring no consumer side changes:

 The behavior of a service when it encounters an unknown element must be clearly defined by
an extensibility handling rule as part of the contract
 New elements added to a new version of a message type designed to be forwards compatible
must not invalidate the prior version of the message type
 Consumers of a message must accept and remove from processing any element that they do not
recognize
 Responses generated from a request that contains the same types as their corresponding
request must add the corresponding elements they removed prior to processing the request

8

These rules ensure that every consumer is in the position to use XML schema validation for the elements
that it is bound to process in its implementation. In no way, we are recommending to use of XML and
XML schema extensibility in a sloppy and forego validation (Figure 4). Contrary to a widespread belief in
the industry, XML and XML Schema extensibility is essential to a compatibility-based versioning
strategy, and hence essential to achieve reuse.

Consumers and providers’ implementations are asymmetric when it comes to their implementations:

 If the consumer validates the incoming messages sent by the provider, they will pass validation
(because of the implementation rules defined)
 However, -and of course- the service provider implementation must in general keep track of the
schemas for all the minor versions for incoming messages and validate each incoming message
based on its minor version number for a given major version, even possibly route the call to
variants of the implementation

The reason for that is because an upper minor version schema cannot validate a lower version schema
(in general). The upper minor version will most likely have required elements in the same target
namespace that cannot be validated with a lower minor version schema.

Consumer Variations
There is also a need for “extension areas” in an XML Schema that are different from versioning (Figure
4). For instance, extensions are common when consumer specific variations are needed, i.e. when
specialized relationships between consumers and providers (independently of other consumers) are
necessary. These extensions can be viewed as a private contract between a particular consumer and the
service provider, embedded in the contract common to all consumers. Again, having a strategy to enable
these extensions is essential to achieve a good level of reuse of services.

 Extensions must be treated separately from the general versioning patterns. We recommend
implementing extensions using a single element under the root element of the message type.
 Extensions must not be processed by the message consumer, unless they are explicitly defined
in its message type or unless specified with a mustUnderstand=’true’ attribute. The message
consumer’s implementation must generate an exception when it cannot process the required
elements.
 It is advised to have extensions belong to a different namespace from the root of the message
type.

9

Fig 4. Versioning and User Extension Compatibility

With Web Services technologies, the fact that one may use different endpoints to access the same
information via different versions of the business logic simplifies greatly the maintenance and
operations of the corresponding services. Overall, Web Services technologies, XML and XML Schema
offer unprecedented opportunities to support compatibility scenarios unlike distributed computing
technologies before them, including REST which cannot rely on a stable contract to specify a versioning
strategy. In REST, the fact that each resource exposes an endpoint is creating a strong coupling between
the endpoint and the resource and makes it difficult to operationally manage multiple major versions of
the implementation of the business logic as REST offers no room to introduce a layer of indirection. This
coupling between resource and endpoint makes it difficult to assign a version to a resource type. In REST
each resource (instance) can potentially implement its own version of the business logic associated to a
particular version of HTTP verb and arbitrary noun.

10

Compatibility & Composability
The compatibility scenarios defined earlier can be combined into these strategies as defined in the latest
Thomas Erl series book Web Service Contract Design and Versioning for SOA:

 Strict: Any change is considered unsafe and must cause a new version. Non-breaking changes
cause a new minor version. Breaking changes will require a new major version. Both backwards
and forwards compatibility is intentionally disregarded.
 Flexible: Non-breaking changes will only result in a new point version. Breaking changes will of
course require a new major version. This strategy uses backwards compatible contracts, but not
forwards compatible contracts.
 Loose: Use both backwards and forwards compatible contracts. Breaking changes will of course
require a new major version.

“Strict” is a very common approach to handling schema versioning. It is a safe approach that will give
you no surprises when changing contracts. In fact, the schema artifact versioning table shown above is
based on the “Strict” strategy. However, it will lead to an explosion of contract versions as your services
evolve, and this will hurt discoverability and especially governance not to mention reuse. In addition,
operations will need to keep your multitude of service versions up and running. Changes to schemas
that are used in aggregate schemas (schema compositions) will ripple through all involved aggregates
and cause a domino effect of new schema versions. And of course, when a schema used in a service gets
a new version, the service must also get a new version. Composite services that involve these services
will then also be affected and must also get a new version. Thus, the ripple effect is much bigger than
you think.

This versioning domino effect soon has caused a little change to ripple through all versionable artifacts
in your system. And it doesn’t stop there; in the end it will affect your consumers.

Composability will suffer when you have poor service discoverability and a proliferation of service
versions. Which services should an unfortunate consumer use and which services will work together as
composite services? Having standardized service contracts including a common information model for
your domain might not be enough when there are thousands of versions of the standardized services
and schemas.

“Flexible” tries to alleviate the version explosion effect of Strict, by treating all non-breaking changes as
safe and backwards compatible. As backwards compatible contract changes by design continues to
support consumers designed to work with the old version of the contract, a new version is not needed –
i.e. it is just a point version. Services can easily be composed together as all the contracts within a major
version are backwards compatible and only one minor service version – the latest – needs to be
considered for every major version. Add “Loose” to get forwards compatible contracts, and all your
compatibility & composability issues are history.

In theory this seems to be the perfect solution, only breaking changes will require a new version and
hence ripple through all versionable artifacts. In theory - had it not been for possible side-effects of

11

“safe” changes, both functional and non-functional. As Nicolai M. Josuttis shows in the book SOA in
Practice even adding a new optional XML element can have non-functional side-effects such as
increasing the response time of a service, breaking the SLA of the service. It would be safer to provide a
new service version with the new schema, as if there is a problem, only the upgraded consumers that
required the change will be affected. Keep in mind though, that in our proposed recommendations, the
compatibility is stated, not implied, so if the SLA was changed by a single element, this would mandate
the definition of a new major version (and XML namespace), even though from an XML extensibility
perspective, this change is perfectly compatible.

A certain combination of these will work better to our experience:

 Flexible/Strict: Use “Flexible” for all safe schema changes, while “Strict” must be used for any
unsafe modification to schemas. Breaking changes will require a new major version. Support
forwards compatibility.

The “Flexible/Strict” strategy combines the best from the three original strategies. It grades changes into
safe and unsafe even if they are theoretically backwards compatible (i.e. non-breaking). Safe changes
cause point versions, while unsafe changes cause at least a minor version. There are no absolute
classification schemes of which changes are safe and which are unsafe, but we suggest that adding to
schemas are considered safe while modifying existing schema components are considered unsafe.
Always judge if even a “safe” change may cause negative side-effects, remember to consider non-
functional aspects.

Strategy Change Major Minor Point FW

Strict Breaking X

Strict Non-Breaking X

Flexible Breaking X

Flexible Non-Breaking X

Loose Breaking X X

Loose Non-Breaking X X

Flexible/Strict Breaking X +

Flexible/Strict Non-Breaking, Safe X +

Flexible/Strict Non-Breaking, Unsafe X +
Table 3. Compatible changes classified as safe or unsafe

Using “Flexible/Strict” will impact the schema artifact versioning table as all changes that in the “Strict”
sense must be a new minor version now can become just a point version for safe changes. Unsafe non-

12

breaking changes must still be a new minor version. Note that even if you judge a code change to be
safe, we still recommend this to be a new minor version.

Schemas are validated and routed based on their major and minor versions, thus aiming for point
version compatibility will also reduce the need for intricate versioning mechanisms in your services.

We recommend using the “Flexible/Strict” strategy for your published services, and also use forwards
compatibility in the form of planned extensibility. Avoid just throwing in schema wildcards everywhere
as this will lead to vague contracts, countering discoverability. John Evdemon advices that “schemas
should be designed for extensibility, not to avoid versioning”. Judicious use of unambiguous wildcards
can help minimize service versioning. We strongly recommend following these guidelines.

Use a combination of compatible contracts and multiple active service versions to ensure that you’re
system is flexible enough to accommodate the inevitable changes that will happen over time. Keep
things simple. Whatever you do, do not try to implement some implicit automagical handling of
versioning inside your services; instead expose your services at abstract endpoints and apply intelligent
routing to achieve service virtualization and apply schema duck-typing outside your services.

You should use the flexible strategy during development of the services due to the agility needed in that
phase. Wait until the services have been published (are in production) to apply strict versioning aspects,
otherwise you will just end up with a very frustrated bunch of consumer and provider developers.

Note that how platforms support forwards compatibility differs. Some require the use of schema
wildcards while others like WCF have implicit support for forwards compatibility. Always test that your
involved platforms work with your forwards compatible schemas. Don’t rely on this just working,
interoperability is important for composability.

Data Model and Message Type DSLs
One of the core problems of distributed computing technologies is the combined handling of both
information and business logic. Some approaches are good at managing distributed information (REST /
HTTP) and some technologies are good at invoking business logic (Web Services). Technologies that have
tried to address both using a combination of remoting technologies and naming & identity services have
generally failed at delivering an environment where both information access and business logic
invocation coexist harmoniously. Most often, a pattern, such as the Data Transfer Object pattern, has
become the prevalent mode of interaction and information representations are simply conveyed back
and forth between endpoints representing services, i.e. business logic.

One of the fundamental reasons for the lack of solution for this difficult problem is the fact that
Enterprise Data is “relational” and utilizes most often bidirectional associations. By contrast, the Web is
built on a “navigational” data model and unidirectional links. In both cases (navigational and relational),
there is always the need to fetch data in a denormalized way via the same endpoint. This means that
when fetching a purchase order, one might also return some customer specific information (name,
address, telephone…) as well as shipping information. Whether you use a RESTful approach or a Web

13

Services approach, the problem is exactly the same. REST is of course slightly better equipped to provide
a normalized solution to this problem since a link to the customer can be embedded within a purchase
order representation, but this is generally not practical as representations often need to embed related
data, to enhance user experience, limit navigations and network roundtrips.

The goal of this paper is not to solve this distributed information integration problem. We are going to
assume that somehow people can only deal with it behind endpoints in both REST and Web Services
world (this is the state of where we are today until more progress is made in distributed computing
technologies). In this environment, the problem people have to deal with is how to manage
denormalized message types, especially in the context of versioning, i.e. when the enterprise data
model needs a revision (Fig 5.).

Customer Order Shipment
0..n 0..n
name PO#
address

1 0..n

?????

Customer PO Shipment
name Customer Customer
address name name

POs address address

PO# Shipment POs
PO# PO#

Fig 5. How do we keep the enterprise data model and message types synchronized?

Up until this point, the industry has kept Enterprise Data Models, XML Schemas and Message types
relatively separate. At most, people defined an ontology with links to both.

In this article we argue that (Fig 6.)

 XML Schema should not be used for creating and managing enterprise data models.
 Enterprise Data Models should be created and managed based on a DSL (EDM-DSL)
 Message types should be created and managed based on a DSL and using the Enterprise Data
Model elements as building blocks (MT-DSL)
 XML Schemas should be generated from the Message Type DSL (itself referencing elements of
the Enterprise Data Model).

14

Enterprise
Enterprise
Data
Data
Model Based on
Model
DSL
Message
Message
Type
Message
references references TypeXML
Type
Schema
Message
Message Generate
Type Message
Message
Based on Type references
DSL Type
Type
Definition
Message
Message
WSDL
Type
Type
Message
Type

Fig. 6. Enterprise Data Model and Message Type DSLs

Let’s explore these points one by one. XML Schema should not be used for creating and managing
Enterprise Data Model because XML Schema was never designed for that. XML Schema cannot describe
efficiently the relational nature of enterprise data models. XML Schema is hierarchical in nature and
cannot model well bidirectional relationships between information entities. XML Schema is a technology
that is well suited to describe and validate the structure of self-standing “documents” be it message
types, web pages, office documents…

Enterprise Data Models should be created and Managed based on a DSL because no current modeling
technology, be it UML or Entity-Relationship diagrams (ERD) have the appropriate semantics to describe
Enterprise Data Models. The core semantic that is missing, and that makes it a non starter for any
existing technology, is paradoxically having the ability to describe a hierarchical structure of related
elements. In other words be it in UML or ERD, we do not have the semantic to define the boundary of a
purchase order or a customer. We can define classes or entities, but in reality a purchase order or a
customer is effectively “composed” of several classes. We need to be able to define a boundary to these
objects and no “standard” modeling language support this semantic because they themselves are too
close to the physical implementation model (Object Orientation in the case of UML and RDBMS in the
case of ERD). In the case of UML, we would have to define a UML profile to extend it with these
semantics. We recommend however to create a dedicated Data Model DSL instead of using a UML
profile because transformations are a lot easier, uncluttered by the UML metamodel.

Message types should be defined based on a dedicated message type DSL which references elements of
the Enterprise Data Model because, in essence, this is really how Message Types are constructed (or at
least should be constructed). When you create a service interface, be it RESTful or Web Services based,

15

you really want to create a message type (or resource representation) that reflects the enterprise data
model both semantically and structurally, instead of reflecting the particularities of a given back end
system. This is in line with loose coupling practices which recommend to minimize the “contract-to-
implementation” coupling. An approach based on the semantics of an Enterprise Data Model is
expected to reduce the need for both Governance (or at least reuse Data Governance efforts) and
create service interfaces or resource representations that will be most likely reusable and composable.

Finally, flat XML Schemas should be generated from these Message Types definitions (based themselves
on the Enterprise Data Model). Flat schemas improve interoperability between Web Service stack as
some stack have difficulties to deal with complex nested schema files. XML Schema is a great technology
to validate the structure and (some of) the content of “documents”. It should remain the primary choice
for describing the structure and validating the content of incoming messages.

Active Service Versions
It is important to implement service lifecycle management policies and procedures to help with
governing service versions. We recommended creating an “Active Service Versions” policy to keep the
number of service versions that you have to govern to a minimum. Alas, our experience shows that in
practice this will be hard to adhere to, thus implement the policy as a guideline rather than a law.

Such a policy typically states that there should be maximum three active versions of a service available
for consumers, plus a hidden active minor version of the latest major. The hidden minor version gives
current consumers a transition period for reverting to a compatible version, just in case the
compatibility statement made for the latest minor version was erroneous. In that case, the consumer
will manually point to the previous minor version endpoint.

Fig. 7. Service version classification

16

You will typically end up with some services that require 5-6 major active service versions, especially for
popular services that are used by multiple consumers. There will always be some consumers that are
laggards in upgrading to newer service versions, and you might not be able to cut them off. However,
the approach that we are recommending ensure that for every major version available, we only need to
expose the respective latest minor version.

Ensure that new consumers always by default discover the published version of your services (i.e. the
latest major/minor version). The published version is what developers will get using the classic
http://url?WSDL “discovery” of the service. In addition, we recommend that three major versions of a
service can be discovered in your service registry. These must be the latest minor version of each.

Finally, you must monitor the usage of the services to know which are used and by whom. The service
lifecycle stewards must notify all consumers of deprecated versions and gently force them to upgrade to
an active service version. When no one (important) is using a deprecated version, you can decommission
it. This ends the lifecycle management of that service version. You can easily imagine how much harder
the steward’s job would be if he or she had to do the same thing for both the major and multiple minor
versions as well.

The active service versions should be accessible through a single virtual endpoint that the consumers
use to invoke the service. This will lessen the impact that versioning the service will have on its
consumers, as the virtual endpoint stays the same and handles the routing to the correct active service
version. Compatibility reduces the need for virtualization as the same endpoint can service several
generations of compatible consumers. Services are routed based on their major and minor versions,
thus aiming for point version compatibility will also reduce the need for complex virtual endpoint
mechanisms.

Service Virtualization is achieved by combining several ESB patterns such as abstract endpoints,
intelligent routing and schema transformations. Using service virtualization isolates the consumers from
the providers and it processes messages “in-flight” to route and mediate between the providers and
versions that make up a composite service that a consumer invokes or triggers through an event.

Using virtualization is not only for composite services, in fact all your published services at any
classification level would benefit from this seen from a governance perspective.

17

Interoperability
The economy is getting more and more globalized and outsourcing seems to be the standard these days.
The business processes of a company more often than not involve partners and suppliers mashed
together into what is called the extended enterprise

The constituents of an extended enterprise will have heterogeneous systems, just as the different
business units of a company most likely will have heterogeneous systems (figure 8). There is no end to
the diversity of legacy systems in use in companies today. A recent Gartner study shows that the
diversity of platforms used to deliver SOA is growing, even mainframe COBOL have had a surge the last
year.

Composability across these heterogeneous service providers in the extended enterprise will require
interoperability. This affects how you design your services and schemas, including which of the WS*
standards you choose to entail in your services. Our interoperability experience is summarized in the
below table.

Artifact Interoperability

SOAP Adhere to WS-I Basic Profile 1.1

SOAP 1.2 Most legacy platforms and tools require SOAP 1.1

WSDL style Prefer “Document/Literal Wrapped” (D/L-W)

WSDL design Avoid wsdl:import and xsd:import as many tools require a single flat WSDL. An
example is Flex.

Messages Use message exchange patters (MEP) e.g. as defined in WSDL 2.0

Message design Single part element for both request and response

Schema style Prefer “Venetian Blind” (complex types)

Schema style Do not use anonymous types (“Russian Doll”)

Schema design Support XSD extensibility, use marker element before schema wildcard; always
test support for schema wildcards across involved platforms

Schema design D/L-W schema components: allows only elements, prohibits use of attributes

Schema design Use of attributes for data or to annotate data elements might not be
supported by all platforms

Schema arrays Use wrapped arrays/collections

XSD types Not all XSD data types are supported by all platforms (e.g. xs:date,
xs:positiveInteger)

18

XSD nillable Some nillable schema components might not be supported by a platform,
while other components might be required to be nillable

WS* standards The support varies wildly between platforms, always test and verify chosen
standard for interoperability

WS-Security Make sure to agree on version, token type, message or transport security,
order and level of encryption and signing, and establishment of secure
conversations (security sessions)

WS-Policy, Some platforms and tools do not support these standard, thus policy metadata
WS-SecurityPolicy have to be communicated out-of-band. An example is Java Spring-WS.
Table 4. Contract design guidelines

Fig. 8. Growing diversity in SOA platforms

The figure “Trends in Use of Development Languages are Related to SOA Adoption” is from the Gartner
report “2008 SOA User Survey: Adoption Trends and Characteristics” by Daniel Scholler.

19

Conclusion

In this article we have defined a versioning strategy which focuses on reuse by enabling services to
evolve to meet new consumer requirements without breaking existing consumers of the service. In a
way this is a “forward” reuse strategy, as the “new version” of a service is reused by the older
consumers instead of the other way around, where a new consumer reuses a service designed for an
existing service consumer.

From our experience, we feel that compatible, versioned data models, messages and services have not
been a primary concern of SOA initiatives. In addition, of those that defined a versioning strategy, very
few have used XML and XML Schema extensibility. It is our strong belief that a compatibility-based
versioning strategy can increase service discoverability, composability and true reuse. It can also reduce,
albeit not eliminate, the need for service governance. Overall, it is expected that the cost of
construction, operation and maintenance of a service will greatly be reduced by such versioning
strategy. It is time to move beyond primitive reuse to reap the benefits of your service inventory.

1
Harmut Wilms, InnoQ, Private Communication

20

Contract Versioning

More Related Content

Contract Versioning