Service Oriented ArchitectureContract Versioning

Kjell-Sverre JerijærviMicrosoft Services

December 2008

SOA Design Maturity

0: Just a Bunch of Web-Services

1: Design Policies for Contracts

2: Service Models and Data Models

3: Governed Services & Contracts

4: Closed-Loop SOA Governance

SOA Principles

Standardized Service Contracts

Service Loose Coupling

Service Abstraction

Service Reusability

Service Autonomy

Service Statelessness

Service Discoverability

Service Composability

Σ Service-Orientation & Interoperability

http://www.soaprinciples.com/

Versionable Artifacts

Contracts: Service, Messages, Data

WSDL: Service Interface + Messages + Policies

XSD: Data contracts as XML schemas

Deployment

Interface v2.0

Implementation v2.0

Deployment

Interface v1.0

Implementation v1.1

Implementation v1.0

SchemaSchema

Operation

Operation

Policy

Policy

Policy

Endpoint

Endpoint

© JJDubray

Why Contract Versioning

Without formal contract versioning guidelines, bad effects are likely:

Too many versions of the same service running in production

Maintaining mapping between consumers and many service versions is troublesome

Consumers will not know which version to use if too many versions are available

New business rules will not be used by old consumers if old versions do not get deprecated

Versioning Guidelines

Define standards

Service version conventions

Rules for WSDL design

Rules for XSD design

Version conventions for WSDL/schema namespaces

Version conventions for WSDL/schema artifact names

Define policies & governance

Number of service versions supported

How to identify a service and its version

How each version of the service is represented in the service registry

Processes for service lifecycle management and how a service is represented in the repository

The Ripple Effect

Standardized Service Contracts

Composite Services

Services

Aggregate Schemas

Consumers

Schemas

Flow & Decisions

Service Logic (code)

Versioning OverviewArtifact Change Major Minor Point

Service Breaking X

Service Non-Breaking X

Composite Service Incompatible 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 artifacts Any modification X

SCHEMASMessages & Data Types

Schema Versioning

Schema design guidelines

Use backwards compatible schemas

Support forwards compatible schemas (extensibility)

Elective: consumer variations (extensions)

Schemas should be designed for extensibility, not to avoid versioning (wildcards)

Compatibility MUST be defined by a versioning scheme

Major (breaking change): incompatible

Minor (non-breaking change): compatible

Compatibility can be either backwards or forwards or both

Schema Compatibility Recommendation

It is recommended to have a simple and explicit schema versioning policy

Use a “Flexible/Strict” compatibility strategy

Flexible: Safe changes to schemas are backwards compatible and cause just a point version

Strict: All unsafe schema changes must cause a new schema version and thus a new service version

Do not require forwards compatible schemas (Loose, wildcard extensibility)

Avoid implementing some smart automagical mechanism for handling schema version issues in the service logic

Rather use backwards compatibility, explicit schema versions and support multiple active service versions

Compatibility Overview

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 +

Versioning F/S RevisitedArtifact Change Major Minor Point

Service Breaking X

Service Non-Breaking U S

Composite Service Incompatible Service X

Composite Service Compatible Service U S

Service Incompatible Schema X

Service Compatible Schema U S

Schema Breaking X

Schema Non-breaking U S

Schema Aggregate Incompatible Schema X

Schema Aggregate Compatible Schema U S

Code Bug fix / maintenance X

Code Safe modifications X

Code Semantic / Unsafe modifications X

Other service artifacts Any modification X

Schema Versioning Rules

The Schema version MUST be independent of the Service Version itself, however, an increment in schema version MUST result in an increment of the Service version

An increment of the version of a type included or imported in a schema MUST result in a version increment of this schema

A Major increment of the schema version of an operation message type MUST result in a major increment of the service version

A message consumer receiving message of an incompatible version MUST generate an exception, even if the message could be understood and processes by removing any portion that was not recognized

Schema Version Tracking

Schemas MUST include mandatory major version in the XML namespace

XML Namespace values MUST be constant for a given schema type and a given major version

Message type schemas should include minor and point version custom attributes on the message type root element of type xsd:int

Whether XML validation is used or not, each message consumer MUST verify that the major version is compatible with its implementation (through XML namespace)

Minor and Point versions MUST NOT affect namespace

Naming Conventions I

Namespaces and artifact names used by schemas will be versioned by the industry standard YYYY/MM format for namespaces:

urn://schemas.microsoft.com/customer/2006/01/

Likewise the YYYY-MM format for files:http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd

Compatible with…

Compatibility is “not” between consumers and providers

Consumers must be compatible with the Standardized Service Contracts

Providers must be compatible with the Standardized Service Contracts

…this also facilitates principle #2:

Service Loose Coupling

Schema Compatibility

SENDER: v1.0 XSD

1..n Elements

Wildcard

RECEIVER: v1.1 XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.0 XML

RECEIVER: v1.0 XSD

1..n Elements

Wildcard

SENDER: v1.1 XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.1 XML

Backwards Compatible Schema

Forwards Compatible Schema

Service Backwards Compatibility

Consumer v1.0

v1.0 REQUEST XSD

1..n Elements

Wildcard

v1.0 RESPONSE XSD

1..n Elements

Wildcard

Provider v1.1

v1.1 REQUEST XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.1 RESPONSE XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.0 XML

v1.1 XML

Backwards Providers

Providers that handle old request message schemaversions received are backwards compatible services

Consumers are responsible for handling old responsemessage schema versions sent by providers

The service provider implementation MUST 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

Schema duck-typing can be used to deduce version

Service Virtualization and intelligent routing is an alternative mechanism for backwards compatibility

Service Forwards Compatibility

Consumer v1.1

v1.0 REQUEST XSD

1..n Elements

Wildcard

v1.0 RESPONSE XSD

1..n Elements

Wildcard

Provider v1.0

v1.1 REQUEST XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.1 RESPONSE XSD

1..n Elements

Wildcard

1..n Elements (optional)

Wildcard

v1.1 XML

v1.0 XML

Forwards Consumers

Consumers that handle upgraded response messageschema versions are forwards compatible consumers

Providers are responsible for handling upgraded requestmessage schema versions sent by consumers

Extensibility design guidelines enable existing consumers to continue operate unchanged even when the service provider is upgraded in a forwards compatible way

If the consumer validates the incoming messages sent by the provider, they will pass validation (because of the extensibility rules defined)

Breaking changes is conveyed using a new major version and thus a new XML namespace

Schema Wildcards

Loose compatibility through schema wildcards

Both request messages and response messages can be forwards compatible

Might lead to fuzzy contracts with unclear semantics and poor discoverability

Implemented using XSD Extensibility

<xs:any namespace=”##targetNamespace” processContents=”lax” minOccurs=0 maxOccurs=”unbounded” />

<xs:any namespace=”##other” processContents=”lax” minOccurs=0 maxOccurs=”unbounded” />

Extensions are differentfrom Versions

Extensions are common when consumer specific variations are needed

i.e. specialized relationships between consumers and providers (independently of other consumers)

Extensions MUST be implemented within a single element under the root element of the message type

Recommended element name is <ConsumerArea>

They MUST be separate from the general versioning patterns

Extensions NEED NOT be processed by other message consumers

Extensions MAY belong to any namespace

SCHEMA MODELSFederated, Composable Information Models

Schema Models

EAI CDM: Common Data Model

SOA CIM: Common Information ModelMDMrealm

Resource Type 1 Resource Type 2 Resource Type n

BPM: HumanTask + Workflow

Business Process Integration (domain CRM)

Task:Message

Contract A

Event:Message

Contract B

Business Process Integration (domain OHS)

Task:Message

Contract K

Event:Message

Contract L

BPI domain information model: business event messages as projections of CIM data entitites

Federated models: required for B2x integration, cannot enforce model on the outside world

Enterprise canonical CIM model: might be feasible, but federated models are recommended

Resource Domain Model Federated CIM

Model Mismatch:ER vs XML Schema

?????

Customer Order

1

0..n

PO

Customer

name

address

Shipment

Shipment0..n

0..n

POs

Customer

name

address

PO# POs

Customer

name

address

PO#

Shipment

name

address

PO#

PO#

DSL-Driven Models

EnterpriseData

ModelDSL

Message TypeDSL

EnterpriseData

Model

Message TypeMessage

TypeMessage

TypeDefinition

references references

Message TypeMessage

TypeWSDL

Message Type

Message TypeMessage

TypeMessage

TypeXML

Schema

Based on

Based on

referencesGenerate

SERVICE INTERFACESCapabilities / Operations

Service Versioning

Must allow for multiple generations of versioning of service design artifacts and runtime endpoints

Must support multiple versions for Service Requests at runtime for the same endpoint

Must allow for multiple branch versioning

Must support the following use casesCreate a new service version

Change message type schema

Change service interface

Change service bindings

Change service non machine readable metadata

Consume a new service version

Create a new consumer version

Decommission a service version

Service Contract Design

Define service version convention into three categories:

Major version change (breaking change)Dropping deprecated operations

Change an operation signature in a manner that could break consumer compatibility

Change service input and output message type

Service has gone through a major rewrite

Minor version change (non-breaking change)Change of the service contract (schema, interface, etc) but maintain the compatibility of the existing consumers

Consumers may still consider whether the change of the service contract is acceptable

Point version change (build number)Change of service implementation but maintaining the service contract the same

Naming Conventions II

Namespaces and artifact names used by WSDL must follow same conventions as for schemas

Major, minor, point are appended in the service nameCONTOSO_3_1_120 for v3.1.120

Consumer can connect to a particular ACTIVE version of a service by using the WS-Addressing “To” element

soap://contoso/services/customer_3

soap://contoso/services/customer_3_pre

No separate version elements are needed in the SOAP header

Versions: Active, Published, Discovery

v1.0 (decommissioned)

v1.1 (deprecated)

v2.1 (deprecated)

V3.0 (deprecated, pre)

v3.1 (latest major)

time

active

published

v2.0 (decommissioned)

discoverable

Active Service Versions

There should not be more than 3 major versions of the same service running in the production environment

Maintain immediate predecessor minor/point version of the latest major version of the service

If new major service version is introduced and there are already 3 versions of service running, the oldest version of the service must be decommissioned

N Latest (Major) version (Published)

N- Immediate Predecessor (minor/point) version of the Latest Major (Deprecated)

N – 1 Deprecated

N – 2 Deprecated

N – 3 Decommissioned

Once the next major version is released (N+1), the immediate predecessor of N, (aka N-) must be decommissioned

Use a SOA governance process to enforce that the consumers upgrade to the newer “Active” versions to maintain the support from the service Provider

Service Registry

Potential consumers will always be directed to the published (latest major) version of a service in the registry, they cannot search for minor or point versions

Potential consumers can only search for the 3 last major version of a service

This approach eliminates the need for managing too many versions

There is no need to alter the manner in which green page queries are performed in the UDDI model

Use a repository to maintain and document the relationship among multiple versions of the same service in a meaningful manner

Registry (or registar role) will be responsible for notifying consumers of new published versions

Other Service Artifacts

These recommendations do not attempt to model extended service metadata

Attachments

Annotations

Other non-machine readable metadata

Changes to service artifact versions MUST be indicated as at least as point versions (since the implementation should change at a minimum)

When this type of metadata changes, there are enough mechanisms in this guideline to convey and detect

Incompatible version

Compatible versions

…even when the contract did not change

SERVICE MODELSUtility, Entity, Activity, Process, Task, Workflow

Composite Services / Service Bus

Process - Resource LifeCycle

Activity

Entity Entity

Capability

LOB Systems

Servic

es

Orch

estr

ati

on

s

CommonInformation

Model(Resources)

Business Process

InformationModels

(Documents)

Wo

rkfl

ow

Human Task -Episodic Process

Human Task -Episodic Process

I&

AM

: C

laim

s-

Au

thZ

BizEvents

BizProcess

MDMrealm

Service Ontology

DESIGN GUIDELINESServices, Messages, Data Types

Service & Messages Design

Web-Services Interoperability best practices:WS-I BasicProfile 1.xwww.ws-i.org

Recommended WSDL style:Document/Literal Wrapped (D/LW)

One message in – One message out

Use Message Exchange Patterns

Data contracts wrapped in Messages

One Way, Request-Response, Notify

Document/Literal Wrapped WSDL

These are the basic characteristics of the document/literal wrapped pattern:

The input and output message has a single part

The part is an element

The element's complex type has no attributes

The input element has the same name as the operation

StrengthsThere is no type encoding info

Everything that appears in the soap:body is defined by the schema, so you can easily validate this message

You have the method name in the SOAP message

Document/literal is WS-I compliant, and the wrapped pattern meets the WS-I restriction that the SOAP message's soap:body has only one child

WeaknessesThe WSDL is complicated

Look ma, no attributes

Data Type Design

Prefer Venetian Blind pattern over Salami Slice pattern

DO NOT use anonymous types in XML schemas(unqualified Russian Doll pattern)

Use wrapped arrays/collections

Elective: allow extensibility after element and attribute definitions

New forward compatible versions of a schema MUST be extended within the target namespace of the original schema

Extensibility to other namespaces MUST be disallowed in places other than the reserved extensibility point

XSD Best Practices

XML schema design alternatives for this instancedocument:

<Book>

<Title>Illusions</Title>

<Author>Richard Bach</Author>

</Book>

Russian Doll

<xsd:element name="Book">

<xsd:complexType>

<xsd:sequence>

<xsd:element name="Title" type="xsd:string"/>

<xsd:element name="Author" type="xsd:string"/>

</xsd:sequence>

</xsd:complexType>

</element>

Salami Slice

<xsd:element name="Title" type="xsd:string"/>

<xsd:element name="Author" type="xsd:string"/>

<xsd:element name="Book">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref="Title"/>

<xsd:element ref="Author"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

Global Element Declaration,@substitutionGroup

Namespace exposure: always ”qualified”

Venetian Blind

<xsd:simpleType name="Title"><xsd:restriction base="xsd:string” />

</xsd:simpleType>

<xsd:simpleType name="Name"> <xsd:restriction base="xsd:string” />

</xsd:simpleType>

<xsd:complexType name="Publication"> <xsd:sequence>

<xsd:element name="Title" type="Title"/>

<xsd:element name="Author" type="Name"/>

</xsd:sequence>

</xsd:complexType>

<xsd:element name="Book" type="Publication"/>

Namespace exposure toggling: ”qualified” or ”unqualified”

WCF Contract Design

Prefer using the WCF DataContractSerializer (DCS) over theXmlSerializer

DCS prefers Venetian Blind, supports Salami Slice

Document/Literal Wrapped WSDL is required by DCS

Follow message part naming conventions defined by Microsoft

DCS supports only elements for data, not attributes

Not supported: <amount currency=”NOK”>123</…>

Wrapped arrays/collections are preferred by DCS

DCS: elementFormDefault must be ”qualified”

DCS: element substition not supported (@substitutionGroup)

Wrapped Arrays

<xs:complexType name="ItemType”><xs:sequence>

<xs:element name="Id" type="xs:long" />

<xs:element name="Value” type="xs:string" />

</xs:sequence>

</xs:complexType>

<xs:complexType name="ItemListType"><xs:sequence>

<xs:element minOccurs="0" maxOccurs="unbounded" name="Item" type="tns:ItemType"/>

</xs:sequence>

</xs:complexType>

<xs:element name="ItemList" type="tns:ItemListType" />

WSDL Operation Message

<wsdl:message name="GetItemRequest”>

<wsdl:part element="tns:GetItemRequestType" name="parameters” />

</wsdl:message>

<wsdl:message name="GetItemResponse”>

<wsdl:part element="tns:GetItemResponseType” name="parameters” />

</wsdl:message>

<wsdl:portType name="InspectValues”>

<wsdl:operation name="GetItem”>

<wsdl:input message="tns:GetItemRequest" name="GetItemRequest"></wsdl:input>

<wsdl:output message="tns:GetItemResponse" name="GetItemResponse"></wsdl:output>

</wsdl:operation>

</wsdl:portType>

WSDL Fault Message

<wsdl:message name="GetCustomerRequest">

<wsdl:part element="tns:GetCustomerRequest" name="parameters" />

</wsdl:message>

<wsdl:message name="GetCustomerResponse">

<wsdl:part element="tns:GetCustomerResponse" name="parameters" />

</wsdl:message>

<wsdl:message name="FaultDetailList">

<wsdl:part element="fault:FaultDetailList" name="detail" />

</wsdl:message>

<wsdl:portType name="CustomerService">

<wsdl:operation name="GetCustomer">

<wsdl:input … />

<wsdl:output … />

<wsdl:fault message="tns:FaultDetailList" name="FaultDetailList" />

</wsdl:operation>

</wsdl:portType>

INTEROPERABILITYDiversity & Composability

Platform Diversity

JAVA

.NET

Schema Interop Issues

Consumers might not support normalized/modular WSDL+XSD, but require a single/flat WSDL file

Most legacy ASMX consumers

Most Java tools (e.g. Eclipse)

Most AJAX toolkits

Rich Internet Application (RIA) platforms (e.g. Flex/Flash)

Some Web2.0 mashup tools

XSD data types might not be supported by platform.NET has no support for e.g. xs:date, xs:positiveInteger

Unsupported data types typically become string objects

Some xs:nillable elements might not be supported by platform

Some elements might be required to be xs:nillable by platform

Use of attributes for data

Use of attributes to annotate data elements

Service Interop Issues

Support level for WS* standards varies wildly between platforms

SOAP 1.1 or SOAP 1.2WS* support in WCF defaults to Soap12Addressing10

Most legacy platforms support only Soap11

Typical WS-Security interop issues:Which version of the standard the platforms support

Token type for authentication

Message or transport security

Order and level of encryption and signing

Establishment of secure conversations

Some platforms do not support WS-Policy/WS-SecurityPolicyNo policy metadata in WSDL, e.g. when using Java Spring-WS

All policy metadata must be communicated out-of-band

Web Service Contract Design and Versioning for SOA

Thomas Erl, David Orchard et.al. (826 pages)http://www.soabooks.com/wsc/default.asp

Credits

John Evdemonhttp://msdn.microsoft.com/en-us/library/ms954726.aspx

Jean-Jacques Dubrayhttp://ebpml.org/com/an_introduction_to_soa4.swf

David Orchardhttp://www.xml.com/pub/a/2004/10/27/extend.htmlhttp://www.w3.org/TR/xmlschema-guide2versioning/

Don Smith http://blogs.msdn.com/donsmith

Roger L. Costello & cohttp://www.xfront.com/GlobalVersusLocal.html

Russel Butekhttp://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/

References

Principles of Service Design: Service Versioninghttp://msdn.microsoft.com/en-us/library/ms954726.aspx

Using Message Contractshttp://msdn.microsoft.com/en-us/library/ms730255.aspx

Practical WCF DataContract Ruleshttp://kjellsj.blogspot.com/2008/03/wcf-datacontractserializer-schema-rules.html

WCF DataContract Ruleshttp://msdn2.microsoft.com/en-us/library/ms733112.aspx

Which WSDL stylehttp://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/

QUESTIONS?

© 2008 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other

countries.

The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to

changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of

this presentation.

MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.