4 Versioning Artifacts

This chapter describes versioning strategies and standards.

Common Versioning Strategies

The following describes types of versioning strategies, as explained in Thomas Erl's book, Web Service Contract Design and Versioning for SOA.

Strict Versioning

For strict versioning, any compatible or incompatible change results in a new version of the service contract. This type of versioning does not support backward or forward compatibility (for example, new change and new contract).

Flexible Versioning

For flexible versioning, an incompatible change results in a new version of the service contract, and the contract supports backward compatibility but not forward compatibility.

Loose Versioning

For loose versioning, any incompatible change results in a new version of the service contract, and the contract supports backward and forward compatibility.

Comparison Chart

The following chart compares the types of versioning strategies listed above. The values in the Characteristics column are described as follows:

• Strictness: The rigidity of the contract versioning strategy.

• Governance Impact: The amount of governance burden imposed by the strategy.

• Complexity: The overall complexity of the versioning process.

Characteristic	Strict Strategy	Flexible Strategy	Loose Strategy
Strictness	High	Medium	Low
Governance Impact	High	Medium	High
Complexity	Low	Medium	High

Oracle Retail Versioning Strategy

The version approach proposed for Oracle Retail is the Flexible Strategy, where an incompatible change results in a new version of the service contract, and the contract supports backward compatibility but not forward compatibility.

Reasons for Versioning an Artifact

For this proposal, there are two primary reasons to version an artifact:

• To recognize that an artifact as changed.

• To recognize whether the change is breaking or non-breaking, as described below.

Breaking Changes

A breaking change is also known as non-backward compatibility. For example, newer versions of producers based on the same Business Object will break existing consumers and require a regeneration of the client from the new wsdl.

Non-backward compatible changes include the following:

• Removing an operation.

• Renaming an operation.

• Changing the parameters of an operation, such as data type or order.

Non-breaking Changes

A non-breaking change is also known as backward compatibility. For example, newer versions of producers based on the same Business Object can be deployed without breaking existing consumers.

Backward compatible changes include the following:

• New operations.

• New data types.

• New optional fields to existing data types.

• Type expansion.

Versioning Retail Business Objects Schemas (XSDs)

This section provides examples of versioning Retail Business Objects (BO) schemas (XSD)s.

Versioning Approach for XSDs

The XSD is versioned by an attribute (version) and the namespace. The namespace is the key versioning point.

XSD Version Attribute

Topic	Description
Recommendation	Each XSD has a version attribute.
Rationale	The version attribute is used to indicate a change has occurred to the XSD. It is a simple counter that starts at 1.00 and bumps when any change is applied.
Example	targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1"version="1.0"xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1"

XSD Version Attribute Usage

Topic	Description
Recommendation	For any change, breaking or non-breaking, the version attribute is incremented.
Rationale	For a non-breaking change, the version will increment the point. For a breaking change, the version will bump. The breaking version bump equates to the same version reflected in the namespace.
Example - Non-breaking Change	Original targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" Non-breaking Change targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.1" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" Breaking Change targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2" version="2.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2"

XSD Namespace Versioning

Topic	Description
Recommendation	XSD namespace is versioned.
Rationale	For breaking changes, the BO XSD namepsace is version controlled.
Example	The following example shows how the versioning appears, before and after. Before targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v1" After targetNamespace="http://www.oracle.com/retail/integration/base/bo/PayTermDesc/v2" version="2.0" xmlns="http://www.oracle.com/retail/integration/base/bo/PayTermBO/v2"

Parent/Child Versioning

Topic	Description
Recommendation	For Parent/Child versioning, if a child version changes (a breaking change) the parent version also must change.
Rationale	If a parent imports an XSD and it has a breaking change, the parent also will have a breaking change. So the versioning of the parent should reflect that.

Multiple Versioning

Topic	Description
Recommendation	The Retail Functional Artifacts directory structure does not support multiple versions of a considered XSD is any of its subdirectory.
Rationale	Oracle Retail PL/SQL applications support only single version of a business object.
Example	The following directory structure depicting multiple versions of a considered XSD is not allowed. Only one version directory can exist./retail/integration/base/ bo/ (Business Objects) BO (Object Name) v[1] (Version - latest) BO.xsd (BO Schema) v[2] (Version - latest) BO.xsd (BO Schema)