2. 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
3. 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/
5. 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
6. 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
7. The Ripple Effect
Consumers
Standardized Service Contracts
Composite Services
Flow & Decisions
Services
Service Logic (code)
Aggregate Schemas
Schemas
8. 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
10. 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
11. 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
12. 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 +
13. 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
14. 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
15. 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
16. 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
17. 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
18. 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
19. 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
20. 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
21. 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
22. 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
23. 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” />
24. 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
26. 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
27. 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#
28. 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
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. 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
38. 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
40. 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
41. 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
42. 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
43. XSD Best Practices
XML schema design alternatives for this instance
document:
<Book>
<Title>Illusions</Title>
<Author>Richard Bach</Author>
</Book>
47. 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)
53. 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
54. 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
55. Web Service Contract Design
and Versioning for SOA
Thomas Erl, David Orchard et.al. (826 pages)
http://www.soabooks.com/wsc/default.asp
56. 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/
57. 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/
