SOA Versioning Best Practices

Al Ghoniem

Introduction
This paper is highlighting best practices recommended for WSDL, Services versioning in SOA environment.


Changes that triggers version numbers increments

Change Breaking
Compatibility
Major Minor Point
Removing an operation X X
Renaming an operation X X
Changing the parameters (in data type or order) of an operation X X
Changing the structure of a complex data type X X
Changing the MEP of an existing WSDL operation definition X X
Adding a fault message to an existing WSDL operation definition X X
Adding a new required XML Schema element or attribute declaration to a message definition X X
Increasing the constraint granularity of an XML Schema element or attribute declaration of a
message definition
X X
Renaming an optional or required XML Schema element or attribute in a message definition X X
Removing an optional or required XML Schema element or attribute or wildcard from a
message definition
X X
Adding a new required WS-Policy assertion or expression. X X
Reducing the constraint granularity of an XML Schema element or attribute declaration of a
message definition.
X
Adding a new optional XML Schema element or attribute declaration to a message definition. X
Adding a new WSDL operation definition and associated message definitions X (Some
Rescores.
says this
is a
minor
Releases)

Adding a new WSDL port type definition and associated operation definitions X
Adding new WSDL binding and service definitions X
Adding a new optional XML Schema element or attribute declaration to a message
Definition
X
Adding a new XML Schema wildcard to a message definition type X
Adding a new optional WS-Policy assertion X
Bug fix X
Performance enhancement X


WSDL Versioning best practices

1- Add major-version information to the WSDL definitions target namespace and file name.
The exception to the preceding rule is when the first version of a WSDL definition is
released. In this case, no version number is added to the namespace.

Rationale:
By encoding only the major release number in the namespace, successive minor releases
share the same namespace and so are compatible.

Examples:
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:cmm="http://www.ventyx.com/ims/cmm/oagis/9.5.1"
xmlns:oa="http://www.openapplications.org/oagis/9/"
xmlns:tns="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-v2"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsu="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" name="Shipment"
targetNamespace="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-v2">

Notes :
Consider using prefix v as follows:
definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:cmm="http://www.ventyx.com/ims/cmm/oagis/9.5.1"
xmlns:oa="http://www.openapplications.org/oagis/9/"
xmlns:tns="http://www.ventyx.com/ims/ws/oagis/9.5.1/v2"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsu="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" name="Shipment"
targetNamespace="http://www.ventyx.com/ims/ws/oagis/9.5.1/v2">

2- Minor and major contract version numbers will be expressed using a documentation element that follows
the opening definitions element.
The version numbers will be displayed after the word Version

Rationale:
WSDL does not have standard version element.
Examples:

<documentation>2.0</documentation>
For Multiple versions :
<documentation>Version 1.0, 2.0</documentation>

3- Encode major and minor version in the target namespace of the WSDL <types> section.

Rationale:
An explicit system of record for the incremental changes to the interface.
Examples:
<types>
<xs:schema elementFormDefault="qualified"
targetNamespace="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-v1.0">
<xs:import schemaLocation="../../../Developer/BODs/NotifyShipment.xsd"
namespace="http://www.ventyx.com/ims/cmm/oagis/9.5.1"/>
<xs:import schemaLocation="../../../Developer/BODs/ConfirmBOD.xsd"
namespace="http://www.ventyx.com/ims/cmm/oagis/9.5.1"/>
</xs:schema>
<xs:schema elementFormDefault="qualified"
targetNamespace="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-v2.0">
<xs:import schemaLocation="../../../Developer/BODs/GetShipment.xsd"
namespace="http://www.ventyx.com/ims/cmm/oagis/9.5.1"/>
<xs:import schemaLocation="../../../Developer/BODs/ShowShipment.xsd"
namespace="http://www.ventyx.com/ims/cmm/oagis/9.5.1"/>
</xs:schema>
</types>


4- Embed major-minor version in the interface (portType) name.

Rationale:
The interface name is mapped to the service endpoint interface in a destination language; by
making the interface version explicit we allow the same code-base to implement different
versions of the same interface.
Examples:

<portType name="SyncNotifyShipmentPortType_v1_0">
<operation name="NotifyShipment">
<input message="tns:NotifyShipmentIn" wsaw:Action="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-
v2.wsdl/SyncNotifyShipment"/>
<output message="tns:ConfirmBOD" wsaw:ReplyAction="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-
v2.wsdl/ConfirmNotifyShipment"/>
</operation>
</portType>
<portType name="SyncGetShipmentPortType_v2_0">
<operation name="GetShipment">
<input message="tns:GetShipmentIn" wsaw:Action="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-
v2.wsdl/SyncGetShipment"/>
<output message="tns:ShowShipmentOut" wsaw:ReplyAction="http://www.ventyx.com/ims/ws/oagis/9.5.1/Shipment-
v2.wsdl/SyncShowShipment"/>
</operation>
</portType>
5- Embed major-minor version in the service name.

Rationale:
Using the same name for the service as that used for the interface.
Examples:

<binding name="NotifyShipment_v1_0_ActiveMQBinding" type="tns:NotifyShipmentPortType_v1_0">
<soap12:binding style="document" transport="http://www.w3.org/2010/soapjms/"/>
<wsp:PolicyReference URI="#NotifyShipmentPort_policy"/>
<operation name="NotifyShipment">
<soap12:operation style="document"/>
<input>
<soap12:body use="literal"/>
</input>
</operation>
</binding>
<service name="ShipmentService_v1_0">
<port name="NotifyShipmentActiveMQEndPt" binding="tns:NotifyShipment_v1_0_ActiveMQBinding">
<soap12:address location="activemq:queue.oagisv951.shipmentv01.notifyshipment"/>
</port>
</service>

6- Embed major-minor version in the Policy.

Rationale:
Change in Policy will trigger an increment in Major-Minor numbers.
Examples:

<wsp:Policy wsu:Id="UseWSAddressing_v1_0_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsaw:UsingAddressing/>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

Question: Major change numbering only?


Do Not(s):

1- Do not use date (year/month) for WSDL versioning :
This approach is used by XSD designers, where the date is embedded in the schema target namespace to indicate major release
information and also give historical reference. Some WSDL designers have in the past used this approach in WSDL contracts;
while it does facilitate major versioning it introduces a new lexical namespace with every contract and so renders the new
contract incompatible with previous versions.

2- Avoid embedding versioning information in message names: The reason for this is that WSDL code generators that adhere to
the wrapped-doc-literal convention require that the name of the message be the same as the name of the operation, so that
they can detect the presence of the wrapped convention and generated appropriate method signatures.
Management of concurrent instances of a service with different versions
Approach Pros Cons
XML Extensions :
Using xs:any and xs:anyAttribute
Compatibility by ignoring unknown
elements.
If not well designed, in valid XML can
be passed.
Service adapters :
Intercepting the message apply XSLT if the message
is not computable then send it through o the service
Clients using old version will use the
new version seamlessly.
Performance overhead.
Technical overhead.
Will not encourage w=the client to
upgrade to he new version of the
service.
Namespace Versioning: Explained earlier in WSDL
versioning.
.NET can resolve XML namespaces
using XMLNameSpaceManager
Performance overhead
WS-Addressing custom Tags:
Useful to keep track and relay Implementation and
Interface changes.
Can include reach information about
implantation or Interfaces changes.
Using custom non-standard tag, that
will not be understood by all
platforms.

Will require intercepting the message
which will add performance
overhead.
Service Brokers and UDDI :
Recommended for more than 30 services.
Has reach features for versioning and
the discovery of services, especially
when many services exists.
Administration overhead.