Soa Contract Versioning

Service Oriented Architecture Contract Versioning Kjell-Sverre Jerijærvi Microsoft 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 Interface v2.0 Interface v1.0 Deployment Implementation v2.0 Deployment Schema Policy Schema End point Implementation v1.1 Policy End point Operation Policy Implementation v1.0 Operation © 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 Consumers Standardized Service Contracts Composite Services Flow & Decisions Services Service Logic (code) Aggregate Schemas Schemas

Versioning Overview Artifact 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

SCHEMAS Messages & 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 Revisited Artifact 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 Backwards Compatible Schema RECEIVER: v1.1 XSD SENDER: v1.0 XSD 1..n Elements 1..n Elements v1.0 XML Wildcard Wildcard 1..n Elements (optional) Wildcard Forwards Compatible Schema SENDER: v1.1 XSD 1..n Elements RECEIVER: v1.0 XSD 1..n Elements Wildcard v1.1 XML 1..n Elements (optional) Wildcard Wildcard

Service Backwards Compatibility Consumer v1.0 Provider v1.1 v1.1 REQUEST XSD v1.0 REQUEST XSD 1..n Elements 1..n Elements v1.0 XML Wildcard Wildcard 1..n Elements (optional) Wildcard v1.1 RESPONSE XSD v1.0 RESPONSE XSD 1..n Elements 1..n Elements v1.1 XML Wildcard Wildcard 1..n Elements (optional) Wildcard

Backwards Providers Providers that handle old request message schema versions received are backwards compatible services Consumers are responsible for handling old response message 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 Provider v1.0 v1.1 REQUEST XSD 1..n Elements v1.0 REQUEST XSD 1..n Elements Wildcard v1.1 XML 1..n Elements (optional) Wildcard Wildcard v1.1 RESPONSE XSD v1.0 RESPONSE XSD 1..n Elements v1.0 XML 1..n Elements Wildcard Wildcard 1..n Elements (optional) Wildcard

Forwards Consumers Consumers that handle upgraded response message schema versions are forwards compatible consumers Providers are responsible for handling upgraded request message 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 different from 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 MODELS Federated, Composable Information Models

Schema Models BPM: HumanTask + Workflow Business Process Business Process Integration (domain CRM) Integration (domain OHS) Task: Event: Task: Event: Message Message Message Message Contract A Contract B Contract K Contract L Resource Type 1 Resource Type 2 Resource Type n Resource Domain Model Federated CIM MDM SOA CIM: Common Information Model realm EAI CDM: Common Data Model 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

Model Mismatch: ER vs XML Schema 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#

DSL-Driven Models 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

SERVICE INTERFACES Capabilities / 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 cases Create 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 name CONTOSO_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 published active v1.0 (decommissioned) v1.1 (deprecated) v2.0 (decommissioned) v2.1 (deprecated) V3.0 (deprecated, pre) discoverable v3.1 (latest major) time

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 MODELS Utility, Entity, Activity, Process, Task, Workflow

Service Ontology Workflow Human Task - Human Task - Business Episodic Process Episodic Process Process Information Models I&AM: Claims - AuthZ BizProcess (Documents) Orchestrations Composite Services / Service Bus BizEvents Process - Resource LifeCycle Common Information Model Services (Resources) Capability Activity Entity Entity LOB Systems MDM realm

DESIGN GUIDELINES Services, Messages, Data Types

Service & Messages Design Web-Services Interoperability best practices: WS-I BasicProfile 1.x www.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 Look ma, The part is an element no attributes The element's complex type has no attributes The input element has the same name as the operation Strengths There 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 Weaknesses The WSDL is complicated

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 instance document: <Book> <Title>Illusions</Title> <Author>Richard Bach</Author> </Book>

Russian Doll <xsd:element name=quot;Bookquot;> <xsd:complexType> <xsd:sequence> <xsd:element name=quot;Titlequot; type=quot;xsd:stringquot;/> <xsd:element name=quot;Authorquot; type=quot;xsd:stringquot;/> </xsd:sequence> </xsd:complexType> </element>

Salami Slice <xsd:element name=quot;Titlequot; type=quot;xsd:stringquot;/> <xsd:element name=quot;Authorquot; type=quot;xsd:stringquot;/> <xsd:element name=quot;Bookquot;> <xsd:complexType> <xsd:sequence> <xsd:element ref=quot;Titlequot;/> <xsd:element ref=quot;Authorquot;/> </xsd:sequence> </xsd:complexType> </xsd:element> Global Element Declaration, @substitutionGroup Namespace exposure: always ”qualified”

Venetian Blind Namespace exposure toggling: <xsd:simpleType name=quot;Titlequot;> ”qualified” or ”unqualified” <xsd:restriction base=quot;xsd:string” /> </xsd:simpleType> <xsd:simpleType name=quot;Namequot;> <xsd:restriction base=quot;xsd:string” /> </xsd:simpleType> <xsd:complexType name=quot;Publicationquot;> <xsd:sequence> <xsd:element name=quot;Titlequot; type=quot;Titlequot;/> <xsd:element name=quot;Authorquot; type=quot;Namequot;/> </xsd:sequence> </xsd:complexType> <xsd:element name=quot;Bookquot; type=quot;Publicationquot;/>

WCF Contract Design Prefer using the WCF DataContractSerializer (DCS) over the XmlSerializer 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=quot;ItemType”> <xs:sequence> <xs:element name=quot;Idquot; type=quot;xs:longquot; /> <xs:element name=quot;Value” type=quot;xs:stringquot; /> </xs:sequence> </xs:complexType> <xs:complexType name=quot;ItemListTypequot;> <xs:sequence> <xs:element minOccurs=quot;0quot; maxOccurs=quot;unboundedquot; name=quot;Itemquot; type=quot;tns:ItemTypequot;/> </xs:sequence> </xs:complexType> <xs:element name=quot;ItemListquot; type=quot;tns:ItemListTypequot; />

WSDL Operation Message <wsdl:message name=quot;GetItemRequest”> <wsdl:part element=quot;tns:GetItemRequestTypequot; name=quot;parameters” /> </wsdl:message> <wsdl:message name=quot;GetItemResponse”> <wsdl:part element=quot;tns:GetItemResponseType” name=quot;parameters” /> </wsdl:message> <wsdl:portType name=quot;InspectValues”> <wsdl:operation name=quot;GetItem”> <wsdl:input message=quot;tns:GetItemRequestquot; name=quot;GetItemRequestquot;></wsdl:input> <wsdl:output message=quot;tns:GetItemResponsequot; name=quot;GetItemResponsequot;></wsdl:output> </wsdl:operation> </wsdl:portType>

WSDL Fault Message <wsdl:message name=quot;GetCustomerRequestquot;> <wsdl:part element=quot;tns:GetCustomerRequestquot; name=quot;parametersquot; /> </wsdl:message> <wsdl:message name=quot;GetCustomerResponsequot;> <wsdl:part element=quot;tns:GetCustomerResponsequot; name=quot;parametersquot; /> </wsdl:message> <wsdl:message name=quot;FaultDetailListquot;> <wsdl:part element=quot;fault:FaultDetailListquot; name=quot;detailquot; /> </wsdl:message> <wsdl:portType name=quot;CustomerServicequot;> <wsdl:operation name=quot;GetCustomerquot;> <wsdl:input … /> <wsdl:output … /> <wsdl:fault message=quot;tns:FaultDetailListquot; name=quot;FaultDetailListquot; /> </wsdl:operation> </wsdl:portType>

INTEROPERABILITY Diversity & Composability

Platform Diversity .NET JAVA

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.2 WS* 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-SecurityPolicy No 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 Evdemon http://msdn.microsoft.com/en-us/library/ms954726.aspx Jean-Jacques Dubray http://ebpml.org/com/an_introduction_to_soa4.swf David Orchard http://www.xml.com/pub/a/2004/10/27/extend.html http://www.w3.org/TR/xmlschema-guide2versioning/ Don Smith http://blogs.msdn.com/donsmith Roger L. Costello & co http://www.xfront.com/GlobalVersusLocal.html Russel Butek http://www.ibm.com/developerworks/webservices/library/ ws-whichwsdl/

References Principles of Service Design: Service Versioning http://msdn.microsoft.com/en-us/library/ms954726.aspx Using Message Contracts http://msdn.microsoft.com/en-us/library/ms730255.aspx Practical WCF DataContract Rules http://kjellsj.blogspot.com/2008/03/wcf-datacontractserializer- schema-rules.html WCF DataContract Rules http://msdn2.microsoft.com/en-us/library/ms733112.aspx Which WSDL style http://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.

Soa Contract Versioning

by Kjell-Sverre Jerijærvi

Accessibility

Categories

Upload Details

Usage Rights

3 Embeds 15

Statistics