Export (0) Print
Expand All
Expand Minimize

Principles of Service Design: Service Versioning


John Evdemon
Microsoft Corporation

August 2005

Summary: The Principles of Service Design series has been developed to communicate best practices and sample codes when relevant. This paper is the second in the multi-paper series focusing on fundamental guidelines for versioning schemas and Web services. Six specific principles for versioning Web services are identified. (17 printed pages)

Applies to:
   Enterprise Architecture
   Service Oriented Architecture
   Web Services
   Service Versioning


Message Versioning
Contract Versioning

About the Principles of Service Design Series

The Principles of Service Design series was developed to communicate best practices relatively quickly, including sample code when relevant. Future papers in this series may include collaborations with other teams or individuals (inside and outside of Microsoft).

Since the service orientation space is rapidly evolving, the papers and sample code in this series may be revised as the space continues to mature.


Web Service Versioning is a hot topic that has generated a broad range of guidance from a variety of sources. Several Web services standardization efforts are underway but none of them address the problem of service versioning.

This is a 100 level paper that provides a quick look at a broad array of options for versioning Web services. Versioning scenarios are been grouped into two categories:

  • Message Versioning
  • Contract Versioning

Readers of this article are assumed to possess general knowledge of the following:

  • XML Schema syntax and Design Principles
  • Web services
  • UDDI
  • .NET Framework

The objective of this paper is to summarize and complement existing service versioning guidance by including recommendations targeting the Microsoft platform.


Service Orientation (SO) enables us to think about enterprise applications in a broader context—application architectures are shifting away from monolithic solution silos into loosely-coupled infrastructures of autonomous services.


Figure 1. From Monolithic Solution Silos to Autonomous Services

The service model is fractal, enabling application solutions to be constructed out of multiple services. This model enables the realization of loosely-coupled business processes, allowing enterprises to experiment with new processes or business models that are relatively free from the constraints of the underlying IT infrastructure.

Recalling the four tenets of Service Orientation, the second tenet is "Services are Autonomous." Autonomy is the fundamental concept behind service orientation. The previous paper in this series provided the following principle for complying with the second tenet of SO:

Services should be deployed and versioned independently of the system in which they are deployed and consumed.

As applications evolve to embrace a fractal services model, how can we version these services in a way that avoids breaking existing consumers?

There are two forms of versioning that we will be address:

  • Forward Compatible—Forward compatibility means that newer versions of producers can be deployed without breaking existing consumers. Forward compatibility is much harder to achieve than backward compatibility since the service must be expected to gracefully interact with a number of unknown or unexpected features. Forward compatibility can be compensated for by adopting standards designed to ignore unrecognizable elements that may appear in the future. This concept (sometimes referred to as MUST IGNORE) was a key design goal in the W3C XML standard.
  • Backward Compatible—A service is backward compatible if it is compatible with earlier versions of itself—especially if these earlier versions are expected to be deprecated. A key design goal of backward compatibility is to ensure that consumers of older versions of a service can continue to interoperate with the new version. Backwards compatibility focuses on preserving existing service contracts while extending the service to add new features.

Additional concepts associated with versioning include:

  • Extensibility—Extensibility is similar in concept to forward compatibility. Extensibility is an architectural principle in which current implementations allow for future growth. Extensions may require adding new functionality or modifying existing functionality. Extensibility enables extensions to be implemented without impacting current implementations. Extensibility is a key feature of XML—this paper includes several recommendations for enabling a consistent approach to schema extensibility.
  • Graceful Degradation—Graceful degradation describes how a service reacts when encountering unexpected circumstances. Services should be designed to respond in a safe, proportionate manner when erroneous or unexpected exceptions occur. Graceful degradation applies to both service behavior and the messages (data) used by a service. For example, consumers may attempt to communicate using malformed/malicious messages or violate policies necessary for successful service interaction. Service internals should attempt to compensate for such inappropriate usage, regardless of user intent.


Versioning is surprisingly missing from Web services—none of the standards organizations hosting Web services efforts address the topic of versioning. The closest may be the WS-I's XML Schema profiling group (although at the time this document was written there was no mention of versioning in the group's charter).

The lack of standards-based guidance for service versioning is a major risk associated with the Web service adoption.

Several papers on versioning have been published from a variety of sources. The goal of this paper is to complement some of these past recommendations by including recommendations targeting the Microsoft platform.


This paper groups service versioning options into two categories:

  • Message Versioning—Focuses on versioning the schemas used to describe messages processed by the service.
  • Contract Versioning—Focuses on versioning the WSDL and contract information used to describe the service.

Message Versioning

Message Versioning focuses on the data that composes the messages created and consumed by a service. For the purposes of this paper, Message Versioning will include both versioning (forward and backward compatibility) and extensibility. Versioning permanently expands the base vocabulary for future implementations while extensions temporarily extend the base vocabulary for a specific implementation.

Most message versioning requirements will fall into one of the following categories (assuming the use of doc-literal services):

  • New Documents—Most industry-standard XML vocabularies define a set of "core" document types such as Purchase Orders, Advanced Ship Notices, and Invoices. Since it is impossible to define every possible type of document a given organization may need, the vocabulary must be extensible, enabling new documents and data structures to be added. For example, RosettaNet has been steadily adding support for new Partner Interface Processes (PIPs) since 1999.
  • Extending Existing Data Constructs—This approach requires extending existing constructs to better reflect the needs of the organization. For example, a Common Alerting Protocol Amber Alert can add jurisdictional information for alerts spanning multiple states.
  • Message Enhancements—New versions of industry-standard vocabularies are frequently issued to add new messages and schemas or change the underlying extensibility model.

Message Versioning builds upon general XML versioning and extensibility guidelines. There are several common techniques for XML versioning and extensibility techniques available:

  • Namespaces
  • Extension Elements
  • Custom version attributes

Namespaces and Extension Elements

XML Namespaces serve two main purposes:

  • Ensure uniqueness of XML element and attribute names (eliminate name collisions).
  • Provide a URI used to specify the language associated with a given XML element or attribute.

XML Namespaces are frequently used to communicate versioning information for the associated vocabulary. For example, the snippet of markup below illustrates how the Global Justice XML Data Model appends versioning information to the end of the namespace URI, indicating that we are working with version 3.0 of the GJXDM schema:

<?xml version="1.0" encoding="UTF-8"?>
   xmlns:xsd= "http://www.w3.org/2001/XMLSchema"
   xmlns:reg= "http://www.it.ojp.gov/jxdm/reg/1.1"
   xmlns:jxdm= "http://www.it.ojp.gov/jxdm/3.0" >

   namespace= "http://www.it.ojp.gov/jxdm/3.0"
   schemaLocation= "../jxdm/3.0/jxdm.xsd" />
<xsd:element name="reg:Registration">
. . .

There are several options for versioning or extending a schema using XML Namespaces:

  1. Use a new XML Namespace for major version releases—(An example of this option appears in the example above.) Versioning the targetNamespace is a breaking change—this means that XML instances will not validate successfully until they are changed to use the new targetNamespace value. Since this is a breaking change it should be used for major versioning changes in the underlying vocabulary. Note also that if you're using serialization, the serializer will generate the appropriate types for you based on the namespace.
  2. Keep XML Namespace values constant and add an XML Schema version attribute—The XML Schema specification allows an optional version attribute on the schema declaration. The advantage of this approach is that it is easy to implement and is fully supported by the XML Schema standard. The impact upon XML instances is fairly minimal since the namespace remains unchanged. There are two disadvantages with this approach:
    • XML schema validation tools are not required to validate instances using the version attribute—the attribute is provided purely for documentation purposes and is not enforceable by XML parsers.
    • Since XML parsers are not required to validate using the version attribute, additional custom processing (over and above parsing and validation) is required to ensure that the expected schema version(s) are being referenced by the instance.
  3. Keep XML Namespace values constant and add a special element for grouping custom extensions—This approach wraps extensions to the underlying vocabulary within a special extension element. This technique is favored by several industry-standard schemas. For example, the Open Application Group's Business Object Documents (OAG BODs) include a <userarea> element to add custom information that may not be part of the base vocabulary. This approach enables us to reuse the same namespace, minimizing the impact upon users of the schema while maximizing the extensibility of the schema constructs (schemas can be both forward and backward compatible). There are two disadvantages to this approach:
    • This approach introduces significantly higher levels of complexity into the schema (anyone who has worked with OAGIS can attest to the complexity of the schemas).
    • This approach is fairly limited—there is no way to implement multiple extensions across different portions of the XML instance since all extensions must be grouped within the extension "wrapper."

This third approach may be a bit confusing since it blurs the line between versioning and extensions. Additional guidelines for designing extensible schemas are presented below (see the "Designing for Extensibility" section later in this article).

Custom Version Attributes

Since XML parsers are not required to validate instances using version, developers may decide to implement their own representation of version, enabling the parser to include it in the validation process. Developers adopting this technique typically make their versioning attribute a fixed, required value for identifying a specific schema version. In the simple schema below we see that instances must set the xsdVersion attribute on the root Demo element to 1.0 or they will be invalid.

<xs:schema xmlns="http://www.contoso.org"
<xs:element name="Demo">
      <xs:attribute name="xsdVersion" 
               type="xs:decimal" use="required" 

The advantage of this approach is that is relatively easy to implement and enables us to work around the fact that the schema version attribute is not included in the validation process. There are three disadvantages to this approach:

  • An XML instance will be unable to use multiple versions of a schema representation because versioning occurs at the schema's root.
  • This approach assumes that all instances will be validated, causing the xsdVersion attribute to be set to 1.0. This is an invalid assumption—some organizations may decide to turn off schema validation for performance reasons. Organizations deciding to turn off schema validation may experience unexpected issues (the least of which may include accepting invalid XML instances). Organizations that decide to turn off schema validation must be fully aware of the consequences of this action, especially since schemas are capable of far more than simple structure and content validation.
  • The XML serialization process in the .NET framework (1.x) is highly optimized and will not serialize attribute values unless they differ from the default value specified in the schema. This means that the value of xsdVersion will not appear in the PSVI (post schema validation infoset) unless a service consumer sets it to a value other than 1.0 (which invalidates our need for the attribute in the first place).

Given the options presented above, the best choice for communicating major version releases is to use the targetNamespace of the schema. This brings us to our first Design Principle for versioning.

Design Principle #1:

Use targetNamespace to communicate major version releases


Major version releases are typically breaking changes.
Ease of implementation and support.

Designing for Extensibility

As we noted above, there is a significant difference between versioning and extending a XML schema. Versioning implies that a permanent change has been implemented, while extensions modify the vocabulary for one or more specific implementations.

Service contracts should be designed with the assumption that once published, they cannot be modified—this approach forces developers to build flexibility into their schema designs. One way to ensure that the service contract remains flexible is to adopt a Contract-First approach to service development. With Contract-First you define your service contract before developing the service itself. The contract can then be used to generate the actual service code. Contract-First is a proven approach for reducing the barriers to interoperability since it builds upon decades of experience (CORBA, COM, and DCE all used interface languages and encouraged a Contract-First approach to development). Many development environments have added simple support for Contract-First, while tools such as thinktecture's WSCF and the GotDotNet XSD Object Code Generator help to further automate this process. Regardless of the development approach you utilize for service development there is no question that service contracts must be designed in an extensible manner to minimize disruptive versioning changes.

Judicious use of <xsd:any>

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.
  • ##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).

The example below illustrates the use of <xsd:any> to enable an extensible definition of name:

<xs:complexType name="name">
   <xs:element name="first" type="xs:string"/>
   <xs:element name="last" type="xs:string"/>
   <xs:any namespace="##any" 

The example above would enable the XML instance to add additional constructs after the last name (for example, John Smith III, John Smith PhD, and so on) while remaining valid based on the schema definition.

While <xsd:any> can be used to extend the schema, there are some general guidelines to keep in mind when designing extensible schemas with <xsd:any>:

  • Abuse of <xsd:any>—Overuse of <xsd:any> may negate the value of using XML Schema—if everything is a wild card you might as well revert to using DTDs. Add <xsd:any> to data structures that will require extensibility (for example, name, address, others). Avoid simply adding <xsd:any> to the end of your schemas to ensure extensibility. <xsd:any> can help delay versioning but should not be treated as a substitute for it. Schemas should be designed for extensibility, not to avoid versioning.
  • Non-determinism—XML was designed to reject ambiguous content models. Non-determinism occurs when a parser is unable to determine the intent of the schema designer. For example, "((a, b) | (a, c))" is an example of an ambiguous content model since we are unable to determine if the value following "a" will be "b" or "c." The XML Schema specification also places several non-deterministic constraints upon the use of <xsd:any>. For example, <xsd:any> can only be used after a required element. Readers interested in learning more about non-determinism's impact upon XML are encouraged to review Appendix E of the W3C XML 1.0 Third Edition Technical Recommendation.

Regardless of the extension mechanism chosen, developers must ensure that all schema extensions utilize unique namespaces since the extensions are not part of the base vocabulary. This fact leads us to Design Principles 2 and 3, each of which target schema extensibility:

Design Principle #2:

Judicious use of unambiguous wildcards can help minimize service versioning.


Extensible schemas adapt to meet changing user or service needs.
Extensible schemas minimize versioning due to schema enhancements.

Design Principle #3:

Extensions must not use the targetNamespace value.


Extensions are not part of the base schema's vocabulary.

Designing extensible schemas is critical to avoid the unnecessary versioning of a service. The W3C Web Services Description Working Group is developing a set of Adjuncts for WSDL 2.0. The Adjuncts will provide a set of predefined extensions to WSDL 2.0 and will appear in Part 2 of the specification. WSDL 2.0's predefined extensions were designed for message exchange patterns, operation styles, and bindings. The extensions define a SOAP Header Block that could be used to extend schemas by adding the new data structures within the WSDL. The following WSDL 2.0 fragment illustrates how a travel reservation schema might be extended to include additional information about a specific frequent flier program:

 <schema targetNamespace="http://example.com/ws/wsdl20/my-ws"

  <complexType name="frequentFlierExtension">
    <element name="is1KMember" type="xs:boolean"
             ad:mustUnderstand="true" />
    <element name="promotionalCode"
<interface name="travelService">
 <operation name="bookTrip">
  <input element="myNS: bookTripRequest">
   <property uri="http://www.w3.org/2004/08/wsdl/feature/AD/data">
    <constraint xmlns:foo="http://contoso.com/">
     foo: frequentFlierExtension

The ADF enables looser coupling between the service and message, since the message can be versioned within the actual interface, effectively shielding consumers from potential changes to the evolution of the service. There are three disadvantages to this approach:

  • It is a violation of the first tenet of Service Orientation (Boundaries are Explicit). ADF extensions leak service implementation details into the boundary while hiding them from older service consumers.
  • ADF is part of the Predefined Features and Extensions for WSDL 2.0 (appearing in the second part of the specification). Vendor support for the Predefined Features and Extensions will be inconsistent since implementing them is optional.
  • WSDL 2.0 is unsuitable for production implementations at the time this document was written. WSDL 2.0 is not expected to reach Proposed Recommendation status at the W3C until early 2006.

The ADF example illustrates that WSDL can play an important role in the evolution of the service. The remainder of this document examines versioning from the contract (WSDL) perspective.

Contract Versioning

Contracts represent the public agreement between a service and the service's consumer. For Web services, service contracts are typically represented using WSDL 1.1. WSDL describes the endpoints, messages, operations, bindings, and ports for a given Web service (although it is also possible to use WSDL to combine multiple services).

As stated earlier, service contracts should be designed with the assumption that once published, they remain relatively static. Adopting this approach forces developers to build flexibility into their contract and schema designs, preferably by adopting a Contract-First approach. While contracts should remain static, services need to evolve to remain useful and relevant to their consumers. In other words, service interfaces have a much longer lifespan than service implementations. It is possible to evolve a service in some ways that avoids breaking contracts with existing consumers:

  • Adding a new operation—Adding a new operation to a service does not break existing consumers since they will be unaware of the new operation's existence. Newer consumers can then take advantage of these new operations without breaking existing consumers.
  • Adding new data structures and data types—New data structures and data types can be added as long as the old ones are preserved. New, optional structures and data types added to the end of messages sent to services will not break existing consumers since they will be unaware of the new data structures. Services can also expand the range of possible data values or types they can accept without impacting existing consumers (assuming a doc-literal encoding style is utilized).
  • Adding a new interface for an existing operation—Once again, existing consumers will be unaware of the new interface and will be unaffected by it. Newer consumers will have a choice of interfaces to utilize.
  • Remember the First Tenet—The first tenet of Service Orientation tells us that boundaries are explicit. A boundary represents the border between a service's public interface and its internal, private implementation. Service internals can be modified, evolved, or totally rewritten as long as the contract for that service remains unchanged. When service implementation details leak into the service boundary this freedom is lost and the contract becomes much more fragile.
  • Type restriction in response messages—Response messages cannot, for the most part, be modified without breaking existing consumers. Services may restrict the range of possible types sent as a response without breaking the contract, depending on how a given consumer has been developed. Consumers will most likely still expect a given range of response values without realizing that the range of possible responses has just been reduced in scope.
  • Use <wsa:Action>—ASMX uses the soapAction header to perform message dispatching by default. This enables service operation names to change without impacting consumers because the soapAction remains constant. soapAction is only valid over HTTP because the WSDL specification restricts its usage to HTTP. Luckily, WS-Addressing's <wsa:Action> element can be used to communicate intent across any protocol (even HTTP).
  • Use a Service Broker—A service broker serves as a front-end to the targeted service, redirecting the request to the appropriate version of the service, based upon the content of the request itself. Service brokers are available as commercial products or can be specialized services designed to serve as façades for existing systems.

The list above leads us to our fourth and fifth design principles:

Design Principle #4:

When adding new data structures, make them optional and add them to the end of service request messages.


Existing consumers remain unaware of the new data structures.

Design Principle #5:

Changing service response messages (other than type restrictions) are breaking changes and will require a new version of the service.


Existing consumers cannot serialize unexpected data structures.

Breaking Changes

Sometimes it is impossible to avoid implementing a change that will break existing service consumers. This is known as a breaking change. A breaking change means that a new service must be deployed with a new namespace containing a new version number. How will this impact consumers of the old service? If we can leave the old service with the old namespace in place there is no impact (other than the costs associated with supporting a potentially out of date service). If we must replace the existing service we can generate an exception for consumers, indicating that the service has been upgraded and providing a link to documentation on how to upgrade their consumers. An intermediary (or broker as previously indicated) can also be established to handle and redirect deprecated service requests.

Another approach to handling breaking changes may be to simulate overloading, enabling consumers to use the same interface with both new and old messages. The service then responds in an appropriate manner based on the contents of the message sent. While this works well for traditional object-oriented programming, ASMX Web services do not support overloading. Specifying different method signatures for a single [WebMethod] also requires specifying unique SoapAction values for each of them. This approach can be used to simulate an overloading experience for service consumers. There are two disadvantages to this approach:

  • The implementation and maintenance of the service becomes more complex.
  • This approach also appears to be a bit of a violation of the first tenet ("Boundaries are Explicit") since the surface area of our service shifts depending upon message contents instead of adhering to a well-defined, consistent interface.

Assuming we must implement a breaking change, what is the best way to notify existing consumers about the change? As stated earlier, we can develop a dedicated service (or broker) that returns an exception with the appropriate links on upgrading their code, but a cleaner approach would involve communicating changes to the service in the metadata used to describe the service—for this we turn to UDDI.

While the UDDI 3.0.2 specification provides guidance for supporting multiple versions of the API, service versioning is not specifically addressed. Luckily, the UDDI Technical Models (tModels) are extensible, enabling service versioning to be included within service registrations (this is discussed later in greater detail). There is generally a one-to-one relationship between service interfaces and tModels—anytime a service interface changes, the associated tModel must also be updated and re-deployed. Users can then perform simple key searches using tModelKeys to locate services that comply with a specific version of the interface. Other versions of the interface would not appear within the search results because they would have been registered using different tModelKey values.

There are two well-known approaches for implementing service versioning in UDDI:

  • Add a Version Number to the tModel—tModels contain a structure known as tModelInstanceInfo (see here). tModelInstanceInfo structures may occur multiple times, each of which may contain a set of instanceDetails that include information such as a service description and overview documentation. The instanceDetails data structure is extensible, allowing us to add a version number for the service being registered. Adding a version number to instanceDetails enables tModels to communicate service versioning information along with other information used to describe the service. The drawback to this approach is that it requires users to be aware of a new element that was added to the instanceDetails (version number). This approach also requires Green Page interfaces to be extended, enabling searches on the new version number element.
  • Promote compliance with multiple interfaces—Services may expose multiple interfaces, potentially supporting more than one version of the interface at the same time. Services compatible with both earlier and later versions of an interface can reference the appropriate tModels in the tModelInstanceDetails collection. tModelInstanceDetails provides a collection of attributes used to uniquely identify compatible services (the specification refers to these collected attributes as the "technical fingerprint" of a service—see here). This approach enables multiple versions of an interface to be published without having to specify version numbers or manage relationships between various tModels and interfaces.

These options bring us to our sixth and final design principle for versioning:

Design Principle #6:

Adopt a one to one relationship between interface versions and UDDI tModels.


Ease of implementation.
Avoids extending tModels in a proprietary manner.
Minimizes the risk of inconsistent version numbering.

The Role of WS-MetadataExchange

The WS-MetadataExchange (WS-MEX) specification will enable service consumers to retrieve metadata for a given service prior to using it. WS-MEX enables consumers to query for specific types of metadata, ensuring that responses to the service inquiry can be recognized and processed by the consumer. The following example illustrates how a requester can use WS-MetadataExchange to request the policy (WS-Policy) of the targeted service:

   <wsa:Action>         http://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadata/Request
   <ex:MyRefProp xmlns:ex='http://server.example.org/refs' >

At the time this document was written there were only two WS-Policy assertion languages available:

  • WS-SecurityPolicy
  • WS-ReliableMessaging Policy Assertion (WS-RM Policy)

We expect to see additional assertion languages published as the WS-Policy framework continues to mature, possibly adding semantics for communicating service versioning.


This paper surveyed several versioning techniques and provided some recommendations specific to the Microsoft platform. In addition to surveying current techniques we also peeked at some future options for versioning in the WSDL 2.0 and WS-MetadataExchange specifications.

Six design principles were identified to summarize best practices for service versioning. This is not a static list and will likely grow as the Web services specifications continue to evolve:

  1. Use targetNamespace to communicate major version releases.
  2. Judicious use of unambiguous wildcards can minimize service versioning.
  3. Extensions must not use the targetNamespace value.
  4. When adding new data structures, make them optional and add them to the end of service request messages.
  5. Changing service response messages (other than type restrictions) are breaking changes that will require a new version of the service.
  6. Adopt a one-to-one relationship between interface versions and UDDI tModels.

Despite the growing adoption of Web services, the topic of versioning has yet to be adequately addressed by any standards organization. This paper was designed to minimize the risks associated with service versioning by communicating the advantages and disadvantages of several options in use today.

Readers should review the design principles, understand the advantages and disadvantages of each, and adopt a versioning strategy that best fits the needs of their organization.


WS-I XML Schema Profiling Working Group (Charter)


Common Alerting Protocol (CAP)

Global Justice XML Data Model (GJXDM)

Open Application Group

ThinkTecture WSCF Tool

GotDotNet XSD Object Code Generator

Universal Description Discovery & Integration (UDDI)

W3C XML 1.0 Technical Recommendation, Third Edition

Web services Description Language (WSDL) 1.1


WSDL 2.0 Pre-Defined Extensions


Thanks to the following people for providing feedback or inspiring some of the content in this paper:

  • Jonathon Marsh, Microsoft
  • Don Smith, Microsoft
  • Kyle Brown, IBM
  • Michael Ellis, IBM
  • David Orchard, BEA
  • Roger Costello, Mitre
© 2014 Microsoft