This book begins with Chapters 1 and 2 providing introductory content and case study background information, respectively. All subsequent chapters are grouped into the following parts:
  Part I: Fundamental Service Contract Design
  Part II: Advanced Service Contract Design
  Part III: Service Contract Versioning
  Part IV: Appendices
Below are descriptions of individual parts and chapters:
Chapter 1: Introduction (TOC)
This chapter establishes the scope and structure of the book by providing an overview of the primary topic areas along with chapter descriptions and information regarding conventions and supplemental resources.

Chapter 2: Case Study (TOC)
The chapters in this book contain numerous case study examples, all of which relate back to the case study background information established in this chapter. Appendix A concludes the case study storylines with a brief summary.

Web Service Contract Design and Versioning for SOA
Web Service Contract Design and Versioning
for SOA

by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley
Foreword by David Chappell
Part I: Fundamental Service Contract Design
Chapter 3: SOA Fundamentals and Web Service Contracts
Chapter 4: Anatomy of a Web Service Contract
Chapter 5: A Plain English Guide to Namespaces
Chapter 6: Fundamental XML Schema: Types and Message Structure Basics
Chapter 7: Fundamental WSDL Part I: Abstract Description Design
Chapter 8: Fundamental WSDL Part II: Concrete Description Design
Chapter 9: Fundamental WSDL 2.0: New Features and Design Options
Chapter 10: Fundamental WS-Policy: Expression, Assertion, and Attachment
Chapter 11: Fundamental Message Design: SOAP Envelope Structure and Header Block Processing

Chapter 3: SOA Fundamentals and Web Service Contracts (TOC)
This chapter begins with an overview of key terms and concepts associated with SOA, service-orientation, and service-oriented computing in general as they pertain to Web service contract design.

Chapter 4: Anatomy of a Web Service Contract (TOC)
This introductory chapter provides a visual exploration of Web service contract structures from both logical and physical perspectives. The focus is on establishing a conceptual understanding of the various parts that can comprise a Web service contract and the mechanics that make these parts work together.
Concepts pertaining to abstract and concrete descriptions are discussed in relation to message, operation, and port type (interface) definitions, along with different message parts, such as the body, header, and headerfault. Also covered are the binding, service, and port (endpoint) sections and how they relate to message parts (body, header, headerfault), envelope structure, and each other.
This chapter contains no code examples and only begins discussing the actual technologies used to build Web service contracts after the basics have been covered in abstract. The final section concludes the chapter with a series of guidelines.

Chapter 5: A Plain English Guide to Namespaces (TOC)
As an integral part of the XML-based Web services framework, both custom and predefined namespaces are used to ensure that all of the technologies covered in this book can harmoniously work together. Therefore, before we get into the actual technology languages used to build Web service contracts, we first provide an informal but in-depth tutorial about namespaces.
Because the topic of namespaces represents a common point of confusion for many IT professionals, this chapter takes extra time to explain the concepts and applications of namespaces in plain English. A range of examples and perspectives are provided so that you are fully prepared for any namespace-related issues discussed in subsequent chapters.



Chapter 6: Fundamental XML Schema: Types and Message Structure Basics (TOC)
We now begin to get into the details of contract design with a chapter dedicated to describing basic XML Schema topics, as they pertain to message design for Web service contracts. The emphasis is on different types of constraints for complex and simple types. Also provided is coverage of how XML Schema types can be customized and extended using type inheritance features.
This chapter also officially kicks off the case study by introducing a set of problems that are solved via the application of XML Schema features. The examples explored ultimately lead to the creation of a set of XML Schema types that will be used by message definitions in the following chapters.



Chapter 7: Fundamental WSDL Part I: Abstract Description Design (TOC)
In this chapter we discuss all aspects of the Web Services Description Language (WSDL) 1.1 that relate to designing and building the parts that comprise the abstract service description. This includes the association of XML Schema types with message definitions, the organization of messages into operation definitions, and the grouping of operations within port type definitions. Also covered is the creation of message headers and the usage of the various namespaces required for different technologies to co-exist within a WSDL document.
Through a series of informal case study examples a complete abstract description is created, incorporating the XML Schema types that were defined in Chapter 6.



Chapter 8: Fundamental WSDL Part II: Concrete Description Design (TOC)
We now move on to the design and development of the concrete description, the part of the WSDL document that binds the abstract description to actual transport and messaging protocols and also assigns it one or more physical network addresses.
This chapter covers all of the primary WSDL 1.1 language elements used to establish this binding, including the service and port definitions, as well as the important binding construct itself. A great deal of content is dedicated to exploring how these native WSDL elements are further supplemented via the use of extensibility elements from other languages, such as SOAP. How header and headerfault message parts are bound to actual SOAP message areas is also described.
The case study examples continue and culminate in the creation of a complete WSDL definition that includes both the abstract and concrete descriptions.

Chapter 9: Fundamental WSDL 2.0: New Features and Design Options (TOC)
This book also covers the WSDL 2.0 standard, which introduces new features and imposes a series of syntactical changes to the WSDL 1.1 language. Through a series of examples, this chapter documents the differences between WSDL 1.1 and 2.0 as they pertain to both abstract and concrete descriptions, and then concludes with a complete WSDL 2.0 version of the WSDL document from Chapter 8.


Chapter 10: Fundamental WS-Policy: Expression, Assertion, and Attachment (TOC)
Through the creation of policy assertions and policy expressions, the WS-Policy language provides various means of extending the technical interface that you can create with WSDL and XML Schema.
This chapter introduces the basics of how policies can be defined and expressed and then associated (attached) to different parts of a WSDL document. Topics include policy subjects, policy alternatives, composite policies, and embedded and external attachment options.
The examples again lead to a revised WSDL definition that includes a simple, attached policy expression.


Chapter 11: Fundamental Message Design: SOAP Envelope Structure and Header Block Processing (TOC)
We now turn our attention to the SOAP technology language that is used to express the structure of messages as they exist on the wire, when they are transmitted to and from Web services. Although this book is dedicated to the Web service contract only, it is important to understand how messages will be processed in order for us to design them effectively.
Aprimary topic in this chapter is the runtime usage of SOAP header blocks and the various roles and options that exist to carry out "targeted processing" where header blocks are designed to be accessed and used only by certain programs along a message path.
Note that this chapter does not explain the SOAP communications framework or any other topics that do not pertain directly to Web service contract design.

Part II: Advanced Service Contract Design
Chapter 12: Advanced XML Schema Part I: Message Flexibility and Type Inheritance and Composition
Chapter 13: Advanced XML Schema Part II: Reusability, Derived Types, Relational Design
Chapter 14: Advanced WSDL Part I: Modularization, Extensibility, MEPs, and Asynchrony
Chapter 15: Advanced WSDL Part II: Message Dispatch, Service Instance Identification, and Non-SOAP
                    HTTP Binding
Chapter 16: Advanced WS-Policy Part I: Policy Centralization and Nested, Parameterized, and Ignorable
                    Assertions
Chapter 17: Advanced WS-Policy Part II: Custom Policy Assertion Design, Runtime Representation, and
                    Compatibility
Chapter 18: Advanced Message Design Part I: WS-Addressing Vocabularies
Chapter 19: Advanced Message Design Part II: WS-Addressing Rules and Design Techniques

Chapter 12: Advanced XML Schema Part I: Message Flexibility and Type Inheritance and Composition (TOC)
There are a variety of messages that a Web service will need to exchange, each with its own unique requirements. This, the first of two chapters dedicated to advanced XML Schema topics, explores the usage of wildcards, extension buckets, and content model groups and documents a variety of techniques that use these XML Schema features to accommodate different types of Web service message designs.
The chapter then continues with an explanation of type inheritance and composition and further discusses how cross-schema inheritance, as a concept, may have different 001_013613517X_01.qxd 9/17/08 4:31 PM Page 9 implications than cross-service inheritance. Specifically, this part of the chapter provides examples that detail how abstract schemas can be created and how schemas in general can be extended.
Finally, a discussion of message design in support of CRUD-style Web service operations is provided. Individual Add, Get, Delete, and Update message designs are described, along with common granularity levels.e 9

Chapter 13: Advanced XML Schema Part II: Reusability, Derived Types, Relational Design (TOC)
The ability to share schemas across Web services is fundamental to establishing separate schema and contract architecture layers. This chapter delves into the various options by which schemas can be partitioned into reusable modules and then included or imported by different schemas (and, ultimately, different WSDL definitions). The creation of a common schema library is furthermore discussed and demonstrated.
Next are sections dedicated to explaining how relational data structures can be simulated using XML Schema features and also how narrative content can be added to supplement base schema content. Finally, the usage and incorporation of pre-defined industry schemas is explored along with several examples and techniques.


Chapter 14: Advanced WSDL Part I: Modularization, Extensibility, MEPs, and Asynchrony (TOC)
Both WSDL 1.1 and 2.0 modularization features and techniques are covered and demonstrated in this chapter, along with issues pertaining to non-transitive limitations that also relate the reuse of XML Schema definitions across WSDL definitions. The use of WSDL import and include are compared, along with WSDL 2.0 interface inheritance design options.
This is followed by a comprehensive exploration of various WSDL extensibility elements and how they can be used and positioned within the WSDL definition structure, with an emphasis on the WSDL binding construct.
Subsequent sections discuss special message exchange patterns (including WSDL 1.1 outbound MEPs and the WSDL 2.0 Robust In-Only MEP) and various advanced techniques for asynchronous message exchanges involving HTTP, SOAP, and SMTP. Finally, a section dedicated to WS-BPEL related extensibility elements is provided along with recommendations as to how to best prepare WSDL definitions for eventual composition by WS-BPEL process definitions.

Chapter 15: Advanced WSDL Part II: Message Dispatch, Service Instance Identification, and Non-SOAP HTTP Binding (TOC)
Various advanced WSDL techniques are explored in this chapter, including the use of new WSDL 2.0 features that allow for broad message coupling. A section dedicated to message dispatch design issues is also provided, along with guidelines as to how to leverage the SOAP Action value to support interpretation of WSDL definitions for dispatch purposes.
Additional topics include different approaches for Web service instance identification and creating header blocks, including the use of the header fault extension. Finally, the binding of WSDL to HTTP without SOAP is explored and demonstrated for both WSDL 1.1 and 2.0.


Chapter 16: Advanced WS-Policy Part I: Policy Centralization and Nested, Parameterized, and Ignorable Assertions (TOC)
Continuing the coverage of the WS-Policy framework that began in Chapter 10, we now delve into various architectural issues, including the application of the Policy Centralization design pattern and different potential approaches for associating separate policy definition documents with WSDL definitions.
Subsequent parts of this chapter demonstrate the use of nested and parameterized policy expressions and then provide detailed coverage of ignorable policy assertions, including a comparison with optional policy assertions. The chapter concludes with an overview of concurrent policy-enabled Web service contracts.


Chapter 17: Advanced WS-Policy Part II: Custom Policy Assertion Design, Runtime Representation, and Compatibility (TOC)
This chapter describes the design process and implications behind creating custom policy assertions. Various examples demonstrate different types of assertions and the pros and cons of customizing policies are further explained. A separate section is provided, dedicated to issues pertaining to the maintenance of custom policy assertion vocabularies.
Later in the chapter, the runtime representation or policy syntax is explored to provide insight as to how policy expressions and alternatives are streamlined into normalized representations. Finally, an intersection algorithm is explained to identify compatibility between service provider and consumer policies.


Chapter 18: Advanced Message Design Part I: WS-Addressing Vocabularies (TOC)
WS-Addressing provides an industry-standard means of extending the base SOAP message design to accommodate a wide range of complex message exchange requirements.
This chapter formally introduces the WS-Addressing standard by individually describing the language elements and SOAP headers established by the Endpoint References (EPR) and Message Addressing Properties (MAP) vocabularies. The chapter provides numerous code samples and concludes with a case study example comprised of a complete set of WS-Addressing headers.


Chapter 19: Advanced Message Design Part II: WS-Addressing Rules and Design Techniques (TOC)
Various, more specialized topics in relation to WS-Addressing are covered in this chapter, including EPR parameter mapping techniques, design issues relating to the binding of Endpoint References with WSDL definitions, and a detailed comparison of WS-Addressing Action values to alternative SOAP Action expressions. The chapter concludes with descriptions of policy assertions provided and standardized by the WSAddressing specification.



Part III: Service Contract Versioning
Chapter 20: Versioning Fundamentals
Chapter 21: Versioning WSDL Definitions
Chapter 22: Versioning Message Schemas
Chapter 23: Advanced Versioning

Chapter 20: Versioning Fundamentals (TOC)
Basic concepts and terminology associated with Web service contract versioning are established in this chapter, together with a detailed explanation of forward and backward compatibility from both technical and governance perspectives.
Version identification is then described and demonstrated through the use of annotated version numbers and namespace values. The chapter ends with sections that describe three primary versioning strategies (Strict, Flexible, Loose) that each support forward and backward compatibility to different extents. These strategies will be used for reference purposes throughout subsequent chapters.


Chapter 21: Versioning WSDL Definitions (TOC)
This chapter explores different techniques for versioning different parts of a WSDL definition with an emphasis on the versioning of WSDL operations. Separate sections provide versioning guidance and examples for adding, renaming, and removing operations as well as modifying operation message exchange patterns and associated fault messages.
Also provided are techniques for versioning port type definitions and various parts of the concrete description. The last section describes what parts of the WSDL language can be used to potentially support forward compatibility.


Chapter 22: Versioning Message Schemas (TOC)
The complex topic of XML Schema-based message versioning is tackled in this chapter, which groups techniques as per the three versioning strategies established in Chapter 20. Versioning approaches to adding, removing, renaming, and modifying existing XML Schema components are documented separately in relation to each versioning strategy.
Throughout these sections various XML Schema language features are explored, including the use of wildcards for forward compatibility and optional elements to accommodate backward compatibility. Another primary topic addressed throughout this chapter is the use of XML Schema namespaces for versioning purposes.


Chapter 23: Advanced Versioning (TOC)
This final chapter provides a mixed bag of versioning guidelines, techniques, and design considerations. It starts off with versioning strategies specifically for WS-Policy expressions and assertions, and then continues with design methods that use policy assertions to express termination information and explore the utilization of custom attributes to express non-ignorable unknown elements (when using wildcards).
Various other versioning approaches are covered, several based on actual contract versioning design patterns, such as Partial Understanding. The chapter concludes with a series of tips for creating and customizing your own versioning strategy.

Part IV: Appendices
The remaining appendices conclude this book with further supporting content.

Appendix A: Case Study Conclusion
Appendix B: How Technology Standards are Developed
Appendix C: Alphabetical Pseudo Schema Reference
Appendix D: Alphabetical Pseudo Schema Reference
Appendix E: SOA Design Patterns Related to this Book

Appendix A: Case Study Conclusion (TOC)
This appendix provides a brief summary and conclusion of the case study storyline, as it pertains to the Web service contracts designed within the ActionCon IT enterprise environment.

Appendix B: How Technology Standards are Developed (TOC)
A concise overview of how the W3C organizes its technical committees is provided, along with descriptions of the processes and stages through which submitted specifications are developed into ratified standards.


Appendix C: Alphabetical Pseudo Schema Reference (TOC)
Skeleton pseudo Schemas are supplied for all of the language elements explained in this book. These Schemas are listed in alphabetical order for quick reference purposes.

Appendix D: Namespaces and Prefixes Used in this Book (TOC)
A reference list of the namespaces and associated prefixes used in previous chapters.

Appendix E: SOA Design Patterns Related to this Book (TOC)
Concise descriptions of each of the design patterns referenced and discused throughout this book. Note that these pattern descriptions are also available online at www.soapatterns.org.