County Justice Information Exchange Project...County Justice Information Exchange Project (CJIEP). This document includes an overall system architecture and design, work and data flows

County Justice Information Exchange Project

Architectural Solution and Technical Requirements Version 1.4

Architectural Solution and Technical Requirements Document

Table of Contents 1 Introduction ....................................... .................................................................................... 2

1.1 Purpose................................................................................................................ 2 1.2 Scope................................................................................................................... 2 1.3 Organization........................................................................................................ 2

2 System Overview .................................... .............................................................................. 3 3 Design Considerations.............................. ........................................................................... 6

3.1 Assumptions and Dependencies ......................................................................... 6 3.2 Guidelines ........................................................................................................... 7

4 Architectural Strategies ........................... ............................................................................ 7 4.1 County Information Exchange Pilot Project Standards ...................................... 7 4.2 WS-I Basic Profile 1.0 ........................................................................................ 9

4.2.1 Messaging ( SOAP / HTTP ) ...................................................................... 9 4.2.2 WSDL ......................................................................................................... 9 4.2.3 UDDI......................................................................................................... 10 4.2.4 XML and XML schema............................................................................ 10

5 System Architecture ................................ ........................................................................... 10 5.1 View-Oriented Reference Architecture ............................................................ 10 5.2 SOA Layers:...................................................................................................... 12 5.3 Web Services .................................................................................................... 13 5.4 Service Agent:................................................................................................... 14 5.5 UDDI Registry.................................................................................................. 15 5.6 Justice Information Exchange Model (JIEM)................................................... 16

6 Security ........................................... ..................................................................................... 16 7 Glossary........................................... .................................................................................... 16 8 Appendix........................................... ................................................................................... 19 Basic Profile Version 1.0.......................... ................................................................................... 20

Final Material................................................................................................................ 20 Date: 2004/04/16 19:06:16 ........................................................................................... 20 Abstract ......................................................................................................................... 20 Status of this Document ................................................................................................ 20 Notice............................................................................................................................ 20 Feedback ....................................................................................................................... 21 Table of Contents.......................................................................................................... 21 1. Introduction............................................................................................................... 24

1.1 Guiding Principles .............................................................................................. 24 1.2 Notational Conventions ...................................................................................... 26

2. Scope of the Profile................................................................................................... 27 3. Profile Conformance................................................................................................. 27

3.1 Conformance of Artifacts ................................................................................... 28 3.2 Conformance of Services, Consumers and Registries ........................................ 28 3.3 Conformance Annotation in Descriptions .......................................................... 29 3.4 Conformance Annotation in Messages ............................................................... 31 3.5 Conformance Annotation in Registry Data......................................................... 32

4. Messaging ................................................................................................................. 34 4.1 XML Representation of SOAP Messages........................................................... 35 4.2 SOAP Processing Model..................................................................................... 41


4.3 Use of SOAP in HTTP........................................................................................ 42 5. Service Description................................................................................................... 47

5.1 Document Structure ............................................................................................ 47 5.2 Types................................................................................................................... 54 5.3 Messages ............................................................................................................. 56 5.4 Port Types ........................................................................................................... 59 5.5 Bindings .............................................................................................................. 60 5.6 SOAP Binding .................................................................................................... 61 5.7 Use of XML Schema .......................................................................................... 72

6. Service Publication and Discovery ........................................................................... 73 6.1 bindingTemplates................................................................................................ 73 6.2 tModels ............................................................................................................... 74

7. Security ..................................................................................................................... 75 7.1 Use of HTTPS..................................................................................................... 76

Appendix I: Referenced Specifications ........................................................................ 77 Appendix II: Extensibility Points.................................................................................. 77 Appendix III: Acknowledgements................................................................................ 79

Basic Profile Version 1.1.......................... ................................................................................... 81 Final Material................................................................................................................ 81 2004-08-24.................................................................................................................... 81 Abstract ......................................................................................................................... 81 Status of this Document ................................................................................................ 81 Notice............................................................................................................................ 81 Feedback ....................................................................................................................... 82 Table of Contents.......................................................................................................... 83 1. Introduction............................................................................................................... 85

1.1 Relationships to Other Profiles ........................................................................... 85 1.2 Changes from Basic Profile Version 1.0............................................................. 86 1.3 Guiding Principles .............................................................................................. 86 1.4 Notational Conventions ...................................................................................... 87 1.5 Profile Identification and Versioning.................................................................. 89

2 Profile Conformance.................................................................................................. 89 2.1 Conformance Requirements................................................................................ 89 2.2 Conformance Targets.......................................................................................... 90 2.3 Conformance Scope............................................................................................ 91 2.4 Claiming Conformance....................................................................................... 91

3. Messaging ................................................................................................................. 92 3.1 SOAP Envelopes................................................................................................. 93 3.2 SOAP Processing Model..................................................................................... 96 3.3 SOAP Faults........................................................................................................ 97 3.4 Use of SOAP in HTTP...................................................................................... 100

4. Service Description................................................................................................. 104 4.1 Required Description ........................................................................................ 105 4.2 Document Structure .......................................................................................... 106 4.3 Types................................................................................................................. 112 4.4 Messages ........................................................................................................... 114 4.5 Port Types ......................................................................................................... 117


4.6 Bindings ............................................................................................................ 119 4.7 SOAP Binding .................................................................................................. 119 4.8 Use of XML Schema ........................................................................................ 131

5. Service Publication and Discovery ......................................................................... 131 5.1 bindingTemplates.............................................................................................. 132 5.2 tModels ............................................................................................................. 133

6. Security ................................................................................................................... 134 6.1 Use of HTTPS................................................................................................... 135

Appendix A: Referenced Specifications..................................................................... 135 Appendix B: Extensibility Points................................................................................ 136 Appendix C: Defined Terms....................................................................................... 138 Appendix D: Acknowledgements ............................................................................... 139

Page i

Table of Figures Figure 1 - High level Web-based SOA design.................................................................... 5 Figure 2 - Process Choreography........................................................................................ 6 Figure 3 - Report Probation Sentence Process.................................................................... 6 Figure 4 – View oriented reference architecture............................................................... 11 Figure 5 - SOA layers ....................................................................................................... 13 Figure 6 - Web Service Overview .................................................................................... 14 Figure 7 - Service Agent ................................................................................................... 15

Page 2

1 Introduction

1.1 Purpose This document will provide the proposed architectural design specifications for the County Justice Information Exchange Project (CJIEP). This document includes an overall system architecture and design, work and data flows along with potential implementation strategies. It is a technical document encompassing the following:

• Identification, classification, specification, and design of business services for

five data exchanges identified by CCAP, PCCD and Subject Matter Experts from Allegheny, Lancaster and Warren Counties, along with the District Attorneys’ Association. This includes their choreography from the perspective of both consumer and provider.

• Identification, classification, specification, and design of components (within the business services) that provide the functional realization of the identified services.

• Identification, classification, specification, and design of service providers, service consumers and optionally (if needed), the service broker(s).

• Identification, classification, specification, and design of service registries where service definitions and descriptions are published.

• Identification, classification, specification, and design of SOA layers: Where components and services reside.

1.2 Scope The architectural design addresses elements specific to the Information Exchange implementation. It details the technical specifications for each aspect identified in the CCAP Information Exchange Milestone Acceptance Form.

1.3 Organization

This document details the architecture, choreography and components that comprise the Information Exchange Project. For each component, the specification shall provide features, data elements and implementation details. The architectural design consists of the following key sections.

Page 3

Section Description Introduction • Purpose

• Scope • Organization

System Overview • Architectural Overview • Components • Business Process / Workflow

Design Considerations • Assumptions and Dependencies • Goals and Guidelines

Architectural Strategies • Pilot Project Standards • WS-I Basic Profile 1.0

System Architecture • View-Oriented Reference Architecture • SOA Layers • Web Services • Service Agent • UDDI Registry

Security • Overview Glossary • Glossary of Terms Appendix • WS-I Basic Profile 1.0 final specification

• WS-I Basic Profile 1.1 final specification

2 System Overview The proposed information exchange infrastructure will be based on a framework that makes the most of current technologies and is able to evolve with ever changing business processes in the criminal justice field. The framework that has emerged to apply these technologies to information sharing is Service-Oriented Architecture (SOA). According to the Office of Justice Programs (OJP) of the U.S. Department of Justice:

The decentralized, loosely coupled characteristics of an SOA approach means that law enforcement, prosecutors, defense counsel, courts, corrections, probation, and parole can share information without sharing a common set of objectives or funding sources. The only agreement has to be a mutual understanding of what information will be shared with whom. The focus is on the messages, not on the structure of the database, the application, or the network. We are free to specify business goals for sharing data while leaving it to individual agencies to incrementally support and implement the underlying mechanisms.1

1 A Framework for Justice Information Sharing: Service-Oriented Architecture available at http://it.ojp.gov/documents/20041209_SOA_Report.pdf

Page 4

This project will employ a Web services-based SOA that will utilize all four core standards of Web services: XML, Web Service Description Language (WSDL), Simple Object Access Protocol (SOAP) and Universal Description, Discovery and Integration (UDDI) It will also utilize the Global Justice Extensible Markup Language (GJXML) Data Model (GJXDM), an XML standard designed specifically for criminal justice information exchanges, providing law enforcement, public safety agencies, prosecutors, public defenders, and the judicial branch with a tool to effectively share data and information in a timely manner. The use of GJXDM will facilitate the implementation of future exchanges beyond the scope of the initial pilot deployment to any system that adheres to this common standard. Web services may be developed by any party whose system will be incorporated into the SOA architecture. For the purposes of this project, the vendor DSI will be responsible for the web services for most of the applications in the pilot. A web service in SOA is an application function packaged as a reusable component for use in a business process. It either provides information or facilitates a change to business data from one state to another. The development process used to implement a particular service is flexible (e.g., .NET, JAVA, ORACLE) as long as the service responds to the specified commands and offers the required quality of service. Web services are based on invocation using SOAP messages, which are described using WSDL over a standard protocol such as HTTP. Use of Web services is a best practice when communicating with external business partners. The high-level web-based SOA architecture is shown below. Each system designated as a service provider will implement a web service to accept a message containing the designated exchange message. Each system identified as a service consumer will need to implement a “Service Agent” which will be responsible for packaging the exchange message, identifying the specified service provider for the exchange, and accessing the provider’s web service to exchange the message.

Page 5

The design of the system begins with the concept of the business processes of an agency (e.g., case-flow management, investigations, or trial preparation), which have been scripted into conversations by criminal justice practitioner Subject Matter Experts (SME) under the Justice Information Exchange Model (JIEM) pioneered by the SEARCH organization. A conversation is defined as a series of exchanges related to the criminal justice business process. Each exchange identifies the critical components (e.g., personal identification, sentencing document, arrest report, etc.), which define the parameters of the services that comprise the entire system. In SOA terms, a business process consists of a series of operations that is executed in an ordered sequence according to a set of business rules. This sequencing, selection, and execution of operations is termed service or process choreography. In this design, choreographed services are invoked in order to respond to business events. The following diagram choreographs the process of a single exchange. The triggering event and entry conditions signal the creation of the specified GJXDM exchange message(s). Each message will be picked up by the Service Agent which will package the exchange message into a SOAP envelope, discover the appointed service provider via the UDDI service, and pass the message to the provider over HTTP.

Figure 1 - High level Web-based SOA design

Page 6

The following diagram choreographs the process described above for the Report Probation Sentence exchange included in the pilot. The triggering event and entry conditions ( Court sentences subject to probation or parole ) signal the creation and publication of the specified GJXDM Court Case Event Message from the AOPC CPCMS system. This message will be picked up by the Service Agent which will package the message into a SOAP envelope, discover the appointed service provider via the UDDI service, and pass the message to the service provider ( Adult Probation ) over HTTP.

3 Design Considerations This section describes many of the issues, which need to be addressed or resolved before attempting to devise a complete design solution.

3.1 Assumptions and Dependencies

• Access to all development platforms requiring web service and service agent development. Verification of prior VPN access will resolve this.

Figure 2 - Process Choreography

Figure 3 - Report Probation Sentence Process

Page 7

• To keep timeline on track, DSI, Cross Current and counties implementing their own web services will have them available for deployment and testing at the conclusion of the development period.

• The Service Agent or Web Service consumer component based design necessitates that each service consumer deploy a service agent to initiate the message transfer. Cross Current will be tasked to provide this component for the pilot.

• Due to time constraints of pilot project, the schema for document definitions may need to be extended beyond the GJXDM definition to accommodate the pilot county’s information. Prior schema development for the JNet provided AOPC Court Case Event Message should be used as the basis for any additional work.

3.2 Guidelines

• SOAD – Service Oriented Architecture and Design. This approach combines elements from OOAD ( Object Oriented Analysis and Design ), BPM ( Business Process Modeling ) and EA (Enterprise Architecture ). The SOAD approach reinforces well-established, general software architecture principles such as information hiding, modularization, and extensibility. But it also adds additional themes such as service identification, service repositories, and a service bus middleware pattern if required. UML modeling will be the notation of choice for the design. Use case, sequence and class diagrams will be the standard for defining the exchanges used in this pilot.

• For the detailed design portion of this project, additional UML diagrams will be provided for UML State, Activity and Collaboration. Also, schema documents will be created using appropriate GJXDM based Information Exchange Packages ( IEP ) and supporting Information Exchange Package Documentation.

4 Architectural Strategies The Web Services Interoperability Organization (WS-I) consortium is providing valuable services that can be leveraged by the justice community. WS-I develops profiles of standards that are shown to be interoperable and effective for private sector industry. These same profiles can be adopted and customized for the justice community. The following standards will provide the guidelines and direction for the architecture of this project.

4.1 County Information Exchange Pilot Project Stan dards For the pilot project, the WS-I Basic Profile 1.0 will be the SOA standards specification “starting point” for non-proprietary Web services specification conformance, this profile includes:

Page 8

SOAP 1.1, WSDL 1.1, UDDI 2.0, XML 1.0, XML Schema and HTTP 1.1 The WS-I Basic Profile 1.0 final specification is attached as: Appendix section 8.1 As business driven needs of the pilot require additional Web services capabilities, and the PCCD County Architect provides approval, the WS-I Basic Profile 1.1, which consists of a set of additional (specifically in the area of security) non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability, will be followed for conformance. The WS-I Basic Profile 1.1 final specification is attached as: Appendix section 8.2 If necessary, again, based on business need and the lack of capability support by WS-I Basic Profile 1.0, 100% conformance to this specification will be a goal of the pilot project. Pilot usage of Itinerary-Based Routing, if needed - Itinerary based routing is when a message contains a list of addresses it would need to visit. This list is in the metadata and is carried with the message. The County Information Exchange Pilot Project intra-county service bus will have several end points and a message could need to visit multiple service location end points, as it does so, it is then forwarded on by each service location’s invocation mechanism based on it’s Itinerary based routing list contained in it’s metadata. The example message, shown below, carries a list of locations that the message would pass through in its progress to the final destination. <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Header> <m:path xmlns:m="http://schemas.xmlsoap.org/"> <m:action>http://myServer/service</m:action> <m:to>soap://sale.com/endpoint</m:to> <m:fwd> <m:via>soap://order.com</m:via> <m:via>soap://pricing.com</m:via> </m:fwd> <m:rev> <m:via/> </m:rev>

Page 9

<m:id>uuid:A034C795-3DE7-49f0-AD03-505BD09437C1</m:id> </m:path> </S:Header> <S:Body> ... </S:Body> </S:Envelope> The service consumer would determine the need to invoke Itinerary-Based Routing, each service provider on the County Information Exchange Pilot Project intra-county service bus will be designed to handle Itinerary-Based Routing if requested by the service consumer. If absolutely necessary, based on business need and PCCD County Architect approval, the following non-WS-I Basic Profile 1.1 specification may be considered during the pilot: WSIL SAML WS-Security 1.0 (as a foundation to WS-Trust, WS-Secure Conversation, WS-Policy, WS-Authorization and WS-Privacy) WS-Addressing (as a foundation to WS- Resource Framework and WS-Notification) WS-Reliability WS-Reliable Messaging BPML BPEL4WS WS-Choreography BPSS ebXML Registry

4.2 WS-I Basic Profile 1.0 The profile identifies how Web services specifications should be used together to create interoperable Web services. The Basic Profile deals with the following components.

4.2.1 Messaging ( SOAP / HTTP ) SOAP 1.1 defines an XML-based message exchange model for the transmitting and processing of messages. SOAP over HTTP messaging will allow our Web Service interfaces to communicate with each other.

4.2.2 WSDL Web Service Description Language (WSDL), an XML format for describing Web services, will be employed to describe standardized communications between our Web Services. WSDL service definitions provide documentation for distributed

Page 10

systems and serve as a basis for automating the details involved in applications communication. In addition, the SOA implementation of WSDL to describe the available services will allow our services to support dynamic binding and services reuse.

4.2.3 UDDI The Universal Description Discovery and Integration specification (UDDI) will provide a platform-independent means of describing , discovering and integrating our services over the network. The UDDI data structures provide a framework for the description of basic business and service information and create a mechanism to provide detailed service access information using WSDL.

4.2.4 XML and XML schema

The system will use Global Justice XML (GJXML), an XML standard designed specifically for criminal justice information exchanges. The GJXDM is an object-oriented data model for organizing the content of a data dictionary (the Global JXDD) in a database. From this database an XML schema specification can be generated that consistently represents the semantics and structure of common data elements and types required to exchange information within the justice and public safety communities. GJXDM provides a consistent, extensible, maintainable XML schema reference specification for data elements and types that represent the data requirements of all the documents contained in the pilot and in potential future exchanges.

5 System Architecture This section provides an overview of the basic elements of the system and how these individual elements will interact to provide the information exchange functionality. It includes descriptions of a view-oriented reference architecture used to describe the project’s system, the SOA layers it encompasses, the web services involved, the service agent and the UDDI registry.

5.1 View-Oriented Reference Architecture A system architecture is basically a mechanism for communicating with diverse stakeholders about the complex organization of a system. An SOA can be defined as a kind of system architecture that aims to integrate diverse information systems and business processes while allowing them to remain autonomous. A view-oriented reference architecture facilitates the identification of what basic elements need to be in place for an SOA to be successful, and on how to document the architecture in a way that communicates effectively to all interested partners. A reference architecture is a model or prototype architecture that can serve two related purposes. First, it can identify the essential views and elements for a type of architecture and in doing so, it can serve as both a template and “checklist” to assist

Page 11

architects in planning their own SOA description projects. Secondly, it can serve as a starting point for architects to use in their SOA description projects. The diagram below presents a graphical overview of the entire reference architecture. This overview will identify the views and major elements of the SOA architecture.

The Requirements View describes, in ordinary language, what services will be available in the architecture, and what constraints or rules will be enforced as users interact with those services. The project’s use case documents for the defined exchanges provide the functional requirements for this view. The Design View identifies services and messages needed to satisfy the functional requirements documented in the Requirements View. It also includes technology profiles that identify families of standards, approaches, or techniques that together satisfy the technical requirements documented in the Requirements View. The sequence diagrams, class diagrams, UML state, activity and collaboration diagrams and adherence to the WS-I Basic Profile 1.0 standard constitute the elements for this view. The Implementation View documents how the elements of the design view are implemented. It defines how the design is mapped into elements that can actually be deployed, executed, and used in an operational environment. These elements will be

Figure 4 – View oriented reference architecture

Page 12

defined in the detailed design document, GJXDM based Information Exchange Packages ( IEP’s ), and supporting Information Exchange Package Documentation. The Deployment View documents how the Implementation View elements are physically made operationally available for use. Its purpose is to communicate the physical characteristics of the SOA in terms of the hardware and infrastructure on which services physically reside, as well as the networks that provide connectivity between services and service requestors. These elements will be defined in the detailed design document. The Artifact Registry View provides for an overall strategy and mechanism for storing the elements and artifacts from the other views in a way that makes them available to stakeholders to consume in whatever way is appropriate for them. The UDDI registry and WSDL document usage provide the elements for this view. The Management and Policy View establishes standards that govern the structure and quality of elements in the requirements, design, and implementation views; it also documents mechanisms for overall management and governance of the architecture. The use case, sequence, and class diagrams, plus the specification of WS-I Basic Profile standards for all documents provide the elements for this view.

5.2 SOA Layers: Service Oriented Architectures are generally comprised of stateless, fully-encapsulated, and self-describing services satisfying a generic business service, which in this case is the individual exchange. The exchange will consist of a number of collaborating or orchestrated services. The following diagram illustrates how the design of the proposed judicial information exchange system maps to the Business, Service and Component SOA layers.

Page 13

5.3 Web Services A Web service is the set of actions that the hosting enterprise is prepared to execute. Web service interfaces defined by WSDL hide implementation details. Services communicate by exchanging messages as opposed to invoking methods directly on another service. The web service advertises the set of structured messages that it will exchange through the use of WSDL rather than directly exposing a set of operations, methods, or functions. When a message is received by a Web service, the appropriate action is performed and a response message may be returned. There is no assumption that subsequent messages received are associated with prior ones (i.e., Web services are stateless), nor are services mutually dependent. The concept of web service-based architecture as loosely coupled is based on the following factors, which will comprise the main principles to be applied in the Pilot:

• A small set of simple and ubiquitous interfaces to all participating software agents (Exchange message).

• Only generic semantics will be encoded at the interfaces. • The interfaces will be universally available for all providers and consumers

(UDDI registry).

Service

Layer

Component

Layer

Information Exchange

Conversation

Functional Domain

Business Process

Business Services

Software Services

Software Components

Exchange 1 Exchange 2 Exchange 3

Web Service

Exchange 2/3

Component

Exchange 1

Component

Business

Layer

Figure 5 - SOA layers (see http://www-128.ibm.com/developerworks/webservices/library/ws-soad1/ )

Page 14

• Descriptive messages will be constrained by an extensible schema delivered through the interfaces (Documents and GJXDM schema definitions).

• Minimal (or no) system behavior will be prescribed by messages. • A schema will limit the vocabulary and structure of messages. • An extensible schema will enable new versions of services to be introduced

without breaking existing services.

The following diagram illustrates how a service can support multiple bindings for a given interface, but each binding should be accessible at a unique address identified by a URI, referred to as a Web service endpoint. Consumers must discover all of the details described here before they can interact with a Web service.

5.4 Service Agent: The Service Agent will facilitate the transfer of messages involved in each exchange. A Service Agent resides on every system designated as a document Provider. It is responsible for the following:

Figure 6 - Web Service Overview

Page 15

• Retrieving the message from the message Provider (JNet network). • Accessing the UDDI registry to obtain location of the corresponding WSDL

interface. • Packaging the GJXDM XML message into a SOAP envelope • Sending the SOAP formatted message to the web service specified by the

WSDL The diagram below illustrates the elements of the service agent. The Receive Function will be responsible for picking up or receiving the Court Case Event Message. The Web Service Proxy will package the message, identify the appropriate web service(s) to be called via UDDI and send the SOAP formatted message to the specified web service(s).

5.5 UDDI Registry The UDDI Registry will describe services, discover service providers, and integrate services provided by the Producers on the network. The following steps will be necessary to create and register services in the UDDI registry.

1. Create the WSDL service interface definition for each exchange. A set of service types will be defined and described with one or more service interface definition WSDL documents. The service interface definition will include service interfaces and protocol bindings, and will be made publicly available. 2. Build services that conform to the standard service definitions identified for this project. Either manually or using appropriate UDDI-aware tooling, implementers will retrieve the description of the standard definition and obtain the corresponding WSDL definition document. WSDL-aware tooling, in turn, can help generate an implementation that supports the standard interfaces and bindings. 3. Deploy and register the new service in the UDDI repository. Either manually or using WSDL and UDDI-aware tooling, a UDDI structure is created, and then

Figure 7 - Service Agent

Page 16

registered. Typically when using WSDL and UDDI-aware tools, service deployment information (a “deployment descriptor” document) will be generated at that same time.

5.6 Justice Information Exchange Model (JIEM) SEARCH has developed a conceptual framework to present the flow of justice information between criminal justice agencies. This framework defines the key events that trigger the sharing of this information. It identifies the agencies involved in the exchange and provides reporting functionality to describe the nature of the information exchange. Along with this framework, SEARCH has developed a Web-based modeling tool and a methodology to capture detailed information regarding the processes, events, agencies, information and conditions associated with justice information integration. For the pilot, SEARCH/MTG was engaged by PCCD to conduct Phase I JIEM business process analysis and modeling. They have documented exchanges that occur between the following agencies, as appropriate; district justice, clerk of courts, district attorney, probation/parole, and jail in three pilot counties.

6 Security As determined at the April 27th architecture meeting at CCAP, security for exchanges is outside the scope of the pilot project. WS-Security can be implemented at a later date when the need arises and funding becomes available. The WS-Security protocol contains specifications on how Authentication and Confidentiality can be enforced on Web Services messaging. For now, security in each county will be provided by the existing fire-wall technology which insulates their private network from the public network.

7 Glossary

Term Description

BPM Business Process Modeling – Workflow management for orchestrating business processes.

Business Service A logical assembly of components, the interaction of which achieves a desired business goal.

CCAP

County Commissioners Association of Pennsylvania – A statewide, nonprofit, bipartisan association representing the commissioners, chief clerks, administrators, their equivalents in home rule counties, and solicitors of Pennsylvania’s sixty-seven counties (CCAP mission statement).

Choreography Term used to refer to the sequence and conditions that describe exchange of messages.

Page 17

Term Description

CJIEP County Justice Information Exchange Project – The project to which this document refers.

Conversation A series of exchanges related to a criminal justice business process DA District Attorney

EA Enterprise Architecture - architectural view of enterprise information systems and supporting technologies.

Exchange

The critical components (e.g., personal identification, sentencing document, arrest report, etc.), which define the parameters of the services that comprise the entire system.

Exchange Document Document that is involved in an exchange between criminal justice agencies.

GJXDM Global Justice XML Data Model – Data reference model used for the exchange of justice and public safety information.

GJXML Global Justice XML – XML schema used to define GJXDM

HTTP Hypertext Transmission Protocol – the standard data transmission format used between web browsers and web servers

IEP

Information Exchange Package – A common set of artifacts to document the structure and content of a GJXDM-conformant XML instance used in an information exchange.

JIEM Justice Information Exchange Model – Model describing the flow of justice information between criminal justice agencies.

Loosely Coupled Web services concept designed for implementing data exchange between frequently changing sources.

MTG

MTG Management Consultants, L.L.C – Management consultants contracted by SEARCH to perform the JIEM analysis for the creation of the ToBe document exchange model.

OJP Office of Justice Programs – Organization providing federal leadership in improving the nations criminal and juvenile justice systems.

OOAD

Object Oriented Analysis and Design –The examination of a problem by modeling it as a group of interacting objects and then transforming the object-oriented model into the specifications required to create the system.

PCCD

Pennsylvania Commission on Crime and Delinquency – Organization promoting a collaborative approach to enhance the quality of justice through guidance, leadership and resources by empowering citizens and communities and influencing state policy (PCCD mission statement).

SEARCH

The National Consortium for Justice Information and Statistics. Organization focused on improving information management and exchange between criminal justice and public safety agencies.

Service Agent

Mechanism responsible for packaging the exchange message, identifying the specified service provider for the exchange, and accessing the provider’s web service to exchange the message.

Service Consumer Agency that utilizes web services provided by other agencies. Consumer’s service agent passes the exchange message to the service provider.

Service Provider Agency that provides web services to consumer agencies. Provider’s web service receives the selected exchange message from a consumer.

Page 18

Term Description

SOA Service Oriented Architecture – Software architecture methodology that provides interaction of independent, reusable components that perform business process.

SOAD Object Oriented Analysis and Design for SOA architecture.

SOAP Simple Object Access Protocol – XML based message protocol for exchanging messages between web services.

Subject Matter Experts (SME)

Subject Matter Experts encompass individuals from Warren, Lancaster, Allegheny, the DA’s Association, PCCD and CCAP.

UDDI Universal Description, Discovery and Integration – Registry for listings and discovery of web-services and their descriptions.

UML Unified Modeling Language - An object-oriented analysis and design language from the Object Management Group.

URI Uniform Resource Identifier – A standard protocol for identifying a way for identifying resources on the Internet.

VPN Virtual Private Network – A private network configured within a public network that allows external access to the private network.

Web Services Web Services encompasses a collection of protocols and technologies allowing a standardized exchange of data.

Web Service Proxy Web service that functions as a relay between web service consumer and web service provider.

WS–I

Web Services Interoperability Organization – an open industry organization chartered to promote web services interoperability across platforms, operating systems and programming languages.

WSDL Web Service Description Language – XML language used for describing web services.

XML Extensible Markup Language – Markup language used for creating custom documents for data exchange.

Page 19

8 Appendix

Page 20

Basic Profile Version 1.0

Final Material

Date: 2004/04/16 19:06:16 This version:

http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html Latest version:

http://www.ws-i.org/Profiles/BasicProfile-1.0.html Errata for this Version:

http://www.ws-i.org/Profiles/BasicProfile-1.0-errata.html Editors:

Keith Ballinger, Microsoft David Ehnebuske, IBM Martin Gudgin, Microsoft Mark Nottingham, BEA Systems Prasad Yendluri, webMethods

Administrative contact: [email protected]

Copyright © 2002-2004 by The Web Services-Interoperability Organization (WS-I) and Certain of its Members. All Rights Reserved.

Abstract

This document defines the WS-I Basic Profile 1.0, consisting of a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications which promote interoperability.

Status of this Document

This is a final specification. Please refer to the errata, which may include normative corrections to it.

Notice

The material contained herein is not a license, either expressly or impliedly, to any intellectual property owned or controlled by any of the authors or developers of this material or WS-I. The material contained herein is provided on an "AS IS" basis and to the maximum extent permitted by applicable law, this material is provided AS IS AND WITH ALL FAULTS, and the authors and developers of this material and WS-I hereby disclaim all other warranties and conditions, either express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike

Page 21

effort, of lack of viruses, and of lack of negligence. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THIS MATERIAL.

IN NO EVENT WILL ANY AUTHOR OR DEVELOPER OF THIS MATERIAL OR WS-I BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS MATERIAL, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

Feedback

If there are areas in this specification that could be clearer, or if errors or omissions are identified, WS-I would like to be notified in order to provide the best possible interoperability guidance.

By sending email, or otherwise communicating with WS-I, you (on behalf of yourself if you are an individual, and your company if you are providing Feedback on behalf of the company) will be deemed to have granted to WS-I, the members of WS-I, and other parties that have access to your Feedback, a non-exclusive, non-transferable, worldwide, perpetual, irrevocable, royalty-free license to use, disclose, copy, license, modify, sublicense or otherwise distribute and exploit in any manner whatsoever the Feedback you provide regarding the work. You acknowledge that you have no expectation of confidentiality with respect to any Feedback you provide. You represent and warrant that you have rights to provide this Feedback, and if you are providing Feedback on behalf of a company, you represent and warrant that you have the rights to provide Feedback on behalf of your company. You also acknowledge that WS-I is not required to review, discuss, use, consider or in any way incorporate your Feedback into future versions of its work. If WS-I does incorporate some or all of your Feedback in a future version of the work, it may, but is not obligated to include your name (or, if you are identified as acting on behalf of your company, the name of your company) on a list of contributors to the work. If the foregoing is not acceptable to you and any company on whose behalf you are acting, please do not provide any Feedback.

Feedback on this document should be directed to [email protected].

Table of Contents

1. Introduction 1.1. Guiding Principles 1.2. Notational Conventions

Page 22

2. Scope of the Profile 3. Profile Conformance 3.1. Conformance of Artifacts 3.2. Conformance of Services, Consumers and Registries 3.3. Conformance Annotation in Descriptions 3.4. Conformance Annotation in Messages 3.5. Conformance Annotation in Registry Data 4. Messaging 4.1. XML Representation of SOAP Messages 4.1.1. SOAP Messages and the Unicode BOM 4.1.2. SOAP Fault Syntax 4.1.3. SOAP Faults and Namespaces 4.1.4. SOAP Fault Extensibility 4.1.5. SOAP Fault Language 4.1.6. SOAP Custom Fault Codes 4.1.7. SOAP encodingStyle Attribute 4.1.8. SOAP's use of XML 4.1.9. SOAP and XML Declarations 4.1.10. SOAP Trailers 4.1.11. Acceptable SOAP Character Encodings 4.1.12. SOAP mustUnderstand Attribute 4.1.13. SOAP Body and Namespaces 4.1.14. SOAP Envelope Namespace 4.1.15. Use of xsi:type Attributes 4.2. SOAP Processing Model 4.2.1. Mandatory Headers 4.2.2. Generating mustUnderstand Faults 4.2.3. SOAP Fault Processing 4.3. Use of SOAP in HTTP 4.3.1. HTTP Versions 4.3.2. Identifying SOAP Faults 4.3.3. HTTP Methods and Extensions 4.3.4. SOAPAction Header Syntax 4.3.5. HTTP and TCP Ports 4.3.6. HTTP Success Status Codes 4.3.7. HTTP Redirect Status Codes 4.3.8. HTTP Client Error Status Codes 4.3.9. HTTP Server Error Status Codes 4.3.10. HTTP Cookies 5. Service Description 5.1. Document Structure 5.1.1. WSDL Schema Definitions 5.1.2. WSDL and Schema Import 5.1.3. WSDL Import location Attribute Syntax 5.1.4. WSDL Import location Attribute Semantics 5.1.5. Placement of WSDL import Elements

Page 23

5.1.6. XML Version Requirements 5.1.7. WSDL and the Unicode BOM 5.1.8. Acceptable WSDL Character Encodings 5.1.9. Namespace Coercion 5.1.10. WSDL documentation Element 5.1.11. WSDL Extensions 5.2. Types 5.2.1. QName References 5.2.2. Schema targetNamespace Syntax 5.2.3. soapenc:Array 5.2.4. WSDL and Schema Definition Target Namespaces 5.3. Messages 5.3.1. Bindings and Parts 5.3.2. Bindings and Faults 5.3.3. Unbound portType Element Contents 5.3.4. Declaration of part Elements 5.4. Port Types 5.4.1. Ordering of part Elements 5.4.2. Allowed Operations 5.4.3. Distinctive Operations 5.4.4. parameterOrder Attribute Construction 5.4.5. Exclusivity of type and element Attributes 5.5. Bindings 5.5.1. Use of SOAP Binding 5.6. SOAP Binding 5.6.1. Specifying the transport Attribute 5.6.2. HTTP Transport 5.6.3. Consistency of style Attribute 5.6.4. Encodings and the use Attribute 5.6.5. Default for use Attribute 5.6.6. Multiple Bindings for portType Elements 5.6.7. Wire Signatures for Operations 5.6.8. Multiple Ports on an Endpoint 5.6.9. Child Element for Document-Literal Bindings 5.6.10. One-Way Operations 5.6.11. Namespaces for soapbind Elements 5.6.12. Consistency of portType and binding Elements 5.6.13. Describing headerfault Elements 5.6.14. Enumeration of Faults 5.6.15. Type and Name of SOAP Binding Elements 5.6.16. name Attribute on Faults 5.6.17. Omission of the use Attribute 5.6.18. Consistency of Messages with Descriptions 5.6.19. Response Wrappers 5.6.20. Namespace for Part Accessors 5.6.21. Namespaces for Children of Part Accessors

Page 24

5.6.22. Required Headers 5.6.23. Allowing Undescribed Headers 5.6.24. Ordering Headers 5.6.25. Describing SOAPAction 5.6.26. SOAP Binding Extensions 5.7. Use of XML Schema 6. Service Publication and Discovery 6.1. bindingTemplates 6.2. tModels 7. Security 7.1. Use of HTTPS Appendix I: Referenced Specifications Appendix II: Extensibility Points Appendix III: Acknowledgements

1. Introduction

This document defines the WS-I Basic Profile 1.0 (hereafter, "Profile"), consisting of a set of non-proprietary Web services specifications, along with clarifications to and amplifications of those specifications which promote interoperability.

Section 1 introduces the Profile, and relates the philosophy that it takes with regard to interoperability.

Section 2, "Scope of the Profile," delimits the areas where the Profile improves interoperability.

Section 3, "Profile Conformance," explains what it means to be conformant to the Profile.

Each subsequent section addresses a component of the Profile, and consists of two parts; an overview detailing the component specifications and their extensibility points, followed by subsections that address individual parts of the component specifications. Note that there is no relationship between the section numbers in this document and those in the referenced specifications.

1.1 Guiding Principles

The Profile was developed according to a set of principles that, together, form the philosophy of the Profile, as it relates to bringing about interoperability. This section documents these guidelines.

No guarantee of interoperability It is impossible to completely guarantee the interoperability of a particular service. However, the Profile does address the most common problems that implementation experience has revealed to date.

Application semantics

Page 25

Although communication of application semantics can be facilitated by the technologies that comprise the Profile, assuring the common understanding of those semantics is not addressed by it.

Testability When possible, the Profile makes statements that are testable. However, such testability is not required. Preferably, testing is achieved in a non-intrusive manner (e.g., examining artifacts "on the wire").

Strength of requirements The Profile makes strong requirements (e.g., MUST, MUST NOT) wherever feasible; if there are legitimate cases where such a requirement cannot be met, conditional requirements (e.g., SHOULD, SHOULD NOT) are used. Optional and conditional requirements introduce ambiguity and mismatches between implementations.

Restriction vs. relaxation When amplifying the requirements of referenced specifications, the Profile may restrict them, but does not relax them (e.g., change a MUST to a MAY).

Multiple mechanisms If a referenced specification allows multiple mechanisms to be used interchangeably, the Profile selects those that are well-understood, widely implemented and useful. Extraneous or underspecified mechanisms and extensions introduce complexity and therefore reduce interoperability.

Future compatibility When possible, the Profile aligns its requirements with in-progress revisions to the specifications it references (e.g., SOAP 1.2, WSDL 1.2). This aids implementers by enabling a graceful transition, and assures that WS-I does not 'fork' from these efforts. When the Profile cannot address an issue in a specification it references, this information is communicated to the appropriate body to assure its consideration.

Compatibility with deployed services Backwards compatibility with deployed Web services is not a goal for the Profile, but due consideration is given to it; the Profile does not introduce a change to the requirements of a referenced specification unless doing so addresses specific interoperability issues.

Focus on interoperability Although there are potentially a number of inconsistencies and design flaws in the referenced specifications, the Profile only addresses those that affect interoperability.

Conformance targets Where possible, the Profile places requirements on artifacts (e.g., WSDL descriptions, SOAP messages) rather than the producing or consuming software's behaviors or roles. Artifacts are concrete, making them easier to verify and therefore making conformance easier to understand and less error-prone.

Lower-layer interoperability

Page 26

The Profile speaks to interoperability at the application layer; it assumes that interoperability of lower-layer protocols (e.g., TCP, IP, Ethernet) is adequate and well-understood. Similarly, statements about application-layer substrate protocols (e.g., SSL/TLS, HTTP) are only made when there is an issue affecting Web services specifically; WS-I does not attempt to assure the interoperability of these protocols as a whole. This assures that WS-I's expertise in and focus on Web services standards is used effectively.

1.2 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Normative statements in the Profile (i.e., those impacting conformance, as outlined in "Profile Conformance") are presented in the following manner:

RnnnnStatement text here.

where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword (e.g., "MUST") and one conformance target keyword (e.g., "MESSAGE").

Some statements clarify the referenced specification(s), but do not place additional constraints upon implementations. For convenience, clarifications are annotated in the following manner: C

Some statements are derived from ongoing standardization work on the referenced specification(s). For convenience, such forward-derived statements are annotated in the following manner: xxxx, where "xxxx" is an identifier for the specification (e.g., "SOAP12" for SOAP Version 1.2, currently under development). Note that because such work is not complete, the specification that the requirement is derived from may change; this information is included only as a convenience to implementers.

This specification uses a number of namespace prefixes throughout; their associated URIs are listed below. Note that the choice of any namespace prefix is arbitrary and not semantically significant.

soap - "http://schemas.xmlsoap.org/soap/envelope/"

xsi - "http://www.w3.org/2001/XMLSchema-instance"

xsd - "http://www.w3.org/2001/XMLSchema"

soapenc - "http://schemas.xmlsoap.org/soap/encoding/"

wsdl - "http://schemas.xmlsoap.org/wsdl/"

Page 27

soapbind - "http://schemas.xmlsoap.org/wsdl/soap/"

wsi - "http://ws-i.org/schemas/conformanceClaim/"

uddi - "urn:uddi-org:api_v2"

2. Scope of the Profile

The scope of the Profile delineates the technologies that it addresses; in other words, the Profile only attempts to improve interoperability within its own scope. Initially, the Profile's scope is bounded by the specifications referenced by it; for a complete list of the Profile's referenced specifications, see Appendix I.

The Profile's scope is further refined by extensibility points. Referenced specifications often provide extension mechanisms and unspecified or open-ended configuration parameters. When identified as an extensibility point, such a mechanism or parameter is outside the scope of the Profile, and its use is not subject to claims of conformance to this Profile.

Because the use of extensibility points may impair interoperability, their use should be negotiated or documented in some fashion by the parties to a Web service; for example, this could take the form of an out-of-band agreement.

Note that the Profile may still place requirements on the use of an extensibility point, without constraining its range. Also, specific uses of extensibility points may be further restricted by other profiles, to improve their interoperability when used in conjunction with the Profile.

For a complete list of the Profile's extensibility points, see Appendix II.

3. Profile Conformance

Conformance to the Profile is defined by adherence to the set of requirements for a specific target, within the scope of the Profile.

The scope of the Profile is defined above ("Scope of the Profile"); conformance to the Profile is dependent upon conformance to those referenced specifications that are in-scope, except when in conflict with the Profile's Requirements, which take precedence for purposes of conformance.

Requirements state the criteria for conformance to the Profile within its stated scope. They embody refinements, interpretations and clarifications that improve interoperability therein. Requirement levels, using RFC2119 language (e.g., MUST, MAY, SHOULD) indicate the nature of the requirement and its impact on conformance. Each requirement is individually identified (e.g., R9999) for convenience.

Page 28

Additional text may be included in the Profile to illuminate requirements (e.g., rationale and examples); however, requirement statements alone should be considered in determining conformance.

Targets allow for the description of conformance in different contexts, to allow conformance testing and certification of artifacts (such as SOAP messages and WSDL descriptions), Web service instances, and Web service consumers. The sections below describe the Profile's conformance targets.

To allow services to advertise conformance to the Profile, messages, descriptions and registry data can be annotated with conformance claims, which use a URI to assert conformance with a particular profile.

The conformance claim URI for this Profile is "http://ws-i.org/profiles/basic/1.0".

3.1 Conformance of Artifacts

The most basic level of conformance is that of an artifact. The Profile makes requirement statements about three kinds of artifacts:

MESSAGE - protocol elements that are exchanged, usually over a network, to effect a Web service (e.g., SOAP/HTTP messages).

DESCRIPTION - descriptions of types, messages, interfaces and their concrete protocol and data format bindings, and the network access points associated with Web services (e.g., WSDL descriptions).

REGDATA - registry elements that are involved in the registration and discovery of Web services (e.g. UDDI tModels).

An instance of an artifact is considered conformant when all of the requirements associated with it are met.

3.2 Conformance of Services, Consumers and Registri es

A deployed instance of a Web service (as specified by wsdl:port or uddi:bindingTemplate ) is considered conformant if it produces only conformant artifacts, and is capable of consuming conformant artifacts, as appropriate. Note that this means that where multiple conformant artifacts are possible, a conformant service must be able to consume them all (e.g., while a sender might choose whether to encode XML in UTF-8 or UTF-16 when sending a message, a receiver must be capable of using either).

Similarly, a consumer of a service instance is considered conformant if it produces only conformant artifacts and is capable of consuming conformant artifacts, as appropriate.

Finally, a registry is considered conformant if it satisfies the profile requirements for the target REGISTRY.

Page 29

INSTANCE - software that implements a wsdl:port or a uddi:bindingTemplate.

CONSUMER - software that invokes an INSTANCE

REGISTRY - a UDDI registry, capable of managing REGDATA.

Conformant Web service instances must comply with all requirement statements associated with INSTANCE.

Likewise, conformant consumers must comply with all requirements statements associated with CONSUMER.

Both conformant Web service instances and consumers must comply, as appropriate, with all of the requirement statements associated with:

SENDER - software that generates a message according to the protocol(s) associated with it

RECEIVER - software that consumes a message according to the protocol(s) associated with it (e.g., SOAP processors)

Note that conformance does not apply to a service as a whole; only ports are considered when determining conformance of instances. Therefore, the Profile places no constraints on wsdl:service definitions. In particular, they can contain multiple wsdl:port elements, each of which may or may not be conformant.

Types of Web services (as described by wsdl:binding and wsdl:portType ) are considered conformant if, when properly implemented and deployed in the environment in which they were intended to operate, they result in conformant instances.

Additionally, an instance of a Web service is required to make the contract that it operates under available in some fashion.

R0001 An INSTANCE MUST be described by a WSDL 1.1 service description, by a UDDI binding template, or both.

"described," in this context, means that if an authorized consumer requests a service description of a conformant service instance, then the service instance provider must make the WSDL document, the UDDI binding template, or both available to that consumer. A service instance may provide run-time access to WSDL documents from a server, but is not required to do so in order to be considered conformant. Similarly, a service instance provider may register the instance provider in a UDDI registry, but is not required to do so to be considered conformant. In all of these scenarios, the WSDL contract must exist, but might be made available through a variety of mechanisms, depending on the circumstances.

3.3 Conformance Annotation in Descriptions

Page 30

Conformance claims can be associated with a particular WSDL element (e.g., wsdl:portType ) to scope them to that construct.

R0002 A DESCRIPTION MAY contain conformance claims regarding instances, as specified in the conformance claim schema.

R0003 A DESCRIPTION's conformance claims MUST be children of the wsdl:documentation element of each of the elements: wsdl:port, wsdl:binding, wsdl:portType, wsdl:operation (as a child element of wsdl:portType but not of wsdl:binding) and wsdl:message.

A conformance claim on an element means that the element (and the instance it represents, in the case of a port) is conformant to the requirements of the Profile it claims to obey that are relevant for this type of element.

A conformance claim on an element also implies that the same claim is made for all the elements that it uses, based on the following transitivity rules, applied recursively:

A claim on a wsdl:port is inherited by the referenced wsdl:binding

A claim on a wsdl:binding is inherited by the referenced wsdl:portType

A claim on a wsdl:portType is inherited by the referenced wsdl:operation s

A claim on a wsdl:operation is inherited by the referenced wsdl:message s of its child wsdl:output and/or wsdl:input

The conformance claim schema is:

<?xml version="1.0" encoding="UTF-8" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSc hema"

targetNamespace="http://ws-i.org/schemas/conforma nceClaim/"

xmlns:tns="http://ws-i.org/schemas/conformanceCla im/"

xmlns:soap="http://schemas.xmlsoap.org/soap/envel ope/"

elementFormDefault="qualified"

attributeFormDefault="unqualified" >

<xsd:import namespace="http://schemas.xmlsoap.org/soap/envelope /"

schemaLocation="http://schemas.xmlsoap.org/soap /envelope/" />

Page 31

<xsd:element name="Claim" >

<xsd:complexType>

<xsd:sequence>

<xsd:any namespace="##any" processContents= "lax"

minOccurs="0" maxOccurs="unbounded" />

</xsd:sequence>

<xsd:attribute name="conformsTo" type="xsd:an yURI" use="required"/>

<xsd:attribute ref="soap:mustUnderstand" use= "prohibited" />

<xsd:anyAttribute namespace="##any" processContents="lax"/>

</xsd:complexType>

</xsd:element>

</xsd:schema>

For example, CORRECT: <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoa p.org/wsdl" xmlns:tns="http://example.org/myservice" xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/s oap" xmlns:wsi="http://ws-i.org/schemas/conformanceCla im/" targetNamespace="http://example.org/myservice"> <wsdl:portType name="MyPortType"> ... </wsdl:portType> <wsdl:binding name="MyBinding" portType="MyPortTy pe" > ... </wsdl:binding> <wsdl:service name="MyService" > <wsdl:port name="MyPort" binding="tns:MyBinding " > <wsdl:documentation> <wsi:Claim conformsTo="http://ws-i.org/prof iles/basic/1.0" /> </wsdl:documentation> <soapbind:address location="http://example.or g/myservice/myport" /> </wsdl:port> </wsdl:service> </wsdl:definitions>

3.4 Conformance Annotation in Messages

Page 32

As new versions of the Profile as well as other profiles are released, it is possible for a service to support multiple profiles. When receiving a message, the service may want to be able to determine the profile to which this message conforms. To allow SOAP messages to indicate the profiles they conform to, WS-I prescribes use of the wsi:Claim element as a SOAP header.

R0004 A MESSAGE MAY contain conformance claims, as specified in the conformance claim schema.

R0005 A MESSAGE's conformance claims MUST be carried as SOAP header blocks.

R0006 A MESSAGE MAY contain conformance claims for more than one profile.

R0007 A SENDER MUST NOT use the soap:mustUnderstand attribute when sending a SOAP header block containing a conformance claim.

A SOAP message may contain conformance claims, carried as SOAP header blocks, indicating to the recipient that the sender claims that the message conforms to one or more profiles. Absence of a conformance claim in a message must not be construed as implying that the message does or does not conform to one or more profiles. Also, conformance claim header blocks are considered informative and therefore must not be mandatory header blocks. The Profile therefore prevents the use of soap:mustUnderstand attribute on the conformance claim header block. For example, CORRECT: <soap:Envelope xmlns:soap="http://schemas.xmlsoap. org/soap/envelope/" > <soap:Header>  <wsi:Claim conformsTo="http://ws-i.org/profiles /basic/1.0" xmlns:wsi="http://ws-i.org/schemas/conformance Claim/" />  </soap:Header> <soap:Body>  </soap:Body> </soap:Envelope>

3.5 Conformance Annotation in Registry Data In the same way that it is useful to annotate various elements of descriptions with profile conformance claims, is it useful to do so for uddi:tModel elements. The natural mechanism in UDDI for adding attributes to a uddi:tModel is to define and use a category system. The Profile adopts this mechanism to add the ability for uddi:tModel s to assert conformance with WS-I Profiles, and with the Profile in particular.

Page 33

R3020 REGDATA of type uddi:tModel claiming conformance with a Profile MUST be categorized using the ws-i-org:conformsTo:2002_12 taxonomy.

R3030 REGDATA of type uddi:tModel claiming conformance with a Profile MUST use the ws-i-org:conformsTo:2002_12 categorization value corresponding to the conformance claim URI for that Profile.

R3021 A REGISTRY MUST support the WS-I Conformance category system by adding the ws-i-org:conformsTo:2002_12 tModel definition to its registry content.

The content of the tModel for the ws-i-org:conformsTo:2002_12 tModel is as follows:

<tModel tModelKey="uuid:65719168-72c6-3f29-8c20-62d efb0961c0">

<name>ws-i-org:conformsTo:2002_12</name>

<description xml:lang="EN">Category system used f or UDDI entities

to point to the WS-I concept to which they confor m to</description>

<overviewDoc>

<overviewURL>http://ws-i.org/schemas/conformanceClaim/</overviewURL>

</overviewDoc>

<categoryBag>

<keyedReference

keyName="uddi-org:types:categorization"

keyValue="categorization"

tModelKey="uuid:C1ACF26D-9672-4404-9D70-39B756E 62AB4" />

</categoryBag>

</tModel>

For example, CORRECT: <tModel tModelKey="..."> <name>BarSOAPService</name> <description xml:lang="EN">Bar's SOAP Service</d escription> <overviewDoc>...</overviewDoc> <categoryBag>

Page 34

<keyedReference tModelKey="uuid:65719168-72c6-3f29-8c20-62 defb0961c0" keyName="ws-I_conformance:BasicProfile1.0" keyValue="http://ws-i.org/profiles/basic/1 .0" /> </categoryBag>

Since wsdl:service elements are not necessarily mapped to a single uddi:businessService and are also not subject to conformance claims, it would be unclear what it meant if a uddi:businessEntity or a uddi:businessService element were to claim conformance with the Profile. Also, uddi:bindingTemplate elements can't be categorized because the UDDI V2 XML Schema does not provide a uddi:categoryBag for them. Hence, the conformance claim made by wsdl:port elements can't be documented in the corresponding uddi:bindingTemplate .

R3005 REGDATA other than uddi:tModel elements representing conformant Web service types MUST NOT be categorized using the ws-i-org:conformsTo:2002_12 taxonomy and a categorization of "http://ws-i.org/profiles/basic/1.0".

It would be ambiguous if the conformance claim a uddi:tModel made were not consistent with the claim made by the wsdl:binding it uses.

R3004 REGDATA of type uddi:tModel MUST be constructed so that the conformance claim it makes is consistent with the conformance claim made by the wsdl:binding to which it refers.

4. Messaging

This section of the Profile incorporates the following specifications by reference, and defines extensibility points within them:

Simple Object Access Protocol (SOAP) 1.1 Extensibility points:

Header blocks - Header blocks are the fundamental extensibility mechanism in SOAP.

Processing order - The order of processing of a SOAP message's components (e.g., headers) is unspecified, and therefore may need to be negotiated out-of-band.

Use of intermediaries - SOAP Intermediaries is an underspecified mechanism in SOAP 1.1, and their use may require out-of-band negotiation. Their use may also necessitate careful consideration of where Profile conformance is measured.

soap:actor values - The value of the soap:actor attribute is a private agreement between the parties to a Web service.

Page 35

Fault details - the contents of a Fault's detail element are not prescribed by SOAP 1.1.

Extensible Markup Language (XML) 1.0 (Second Edition)

RFC2616: Hypertext Transfer Protocol -- HTTP/1.1 Extensibility points:

HTTP Authentication - HTTP authentication allows for extension schemes, arbitrary digest hash algorithms and parameters.

Unspecified Header Fields - HTTP allows arbitrary headers to occur in messages.

Expect-extensions - The Expect/Continue mechanism in HTTP allows for expect-extensions.

Content-Encoding - The set of content-codings allowed by HTTP is open-ended.

Transfer-Encoding - The set of transfer-encodings allowed by HTTP is open-ended.

Upgrade - HTTP allows a connection to change to an arbitrary protocol using the Upgrade header.

RFC2965: HTTP State Management Mechanism

4.1 XML Representation of SOAP Messages

The following specifications (or sections thereof) are referred to in this section of the Profile;

SOAP 1.1, Section 4

SOAP 1.1 defines an XML-based structure for transmitting messages. The Profile mandates the use of that structure, and places the following constraints on its use:

4.1.1 SOAP Messages and the Unicode BOM

XML 1.0 allows UTF-8 encoding to include a BOM; therefore, receivers of messages must be prepared to accept them. The BOM is mandatory for XML encoded as UTF-16.

R4001 A RECEIVER MUST accept messages that include the Unicode Byte Order Mark (BOM).C

Page 36

4.1.2 SOAP Fault Syntax

A SOAP Fault is a SOAP message that has a single child element of the soap:Body element, that element being a soap:Fault element. The Profile restricts the content of the soap:Fault element to those elements explicitly described in SOAP 1.1.

R1000 When a MESSAGE contains a soap:Fault element, that element MUST NOT have element children other than faultcode, faultstring, faultactor and detail.

For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor> <detail>There were <b>lots</b> of elements in the message that I did not understand </detail> <m:Exception xmlns:m='http://example.org/faults/e xceptions' > <m:ExceptionType>Severe</m:ExceptionType> </m:Exception> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor> <detail> <m:msg xmlns:m='http://example.org/faults/exce ptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> <m:Exception xmlns:m='http://example.org/fault s/exceptions'> <m:ExceptionType>Severe</m:ExceptionType> </m:Exception> </detail> </soap:Fault>

4.1.3 SOAP Faults and Namespaces

The children of the soap:Fault element are local to that element, therefore namespace qualification is unnecessary.

R1001 When a MESSAGE contains a soap:Fault element its element children MUST be unqualified.

For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <soap:faultcode>soap:Client</soap:faultcode> <soap:faultstring>Invalid message format</soap:fa ultstring> <soap:faultactor>http://example.org/someactor</so ap:faultactor> <soap:detail>

Page 37

<m:msg xmlns:m='http://example.org/faults/exc eptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> </soap:detail> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns='' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor> <detail> <m:msg xmlns:m='http://example.org/faults/exc eptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> </detail> </soap:Fault>

4.1.4 SOAP Fault Extensibility

For extensibility, additional attributes are allowed to appear on the detail element and additional elements are allowed to appear as children of the detail element.

R1002 A RECEIVER MUST accept fault messages that have any number of elements, including zero, appearing as children of the detail element. Such children can be qualified or unqualified.

R1003 A RECEIVER MUST accept fault messages that have any number of qualified or unqualified attributes, including zero, appearing on the detail element. The namespace of qualified attributes can be anything other than "http://schemas.xmlsoap.org/soap/envelope/".

4.1.5 SOAP Fault Language

Faultstrings are human-readable indications of the nature of a Fault. As such, they may not be in a particular language, and therefore xml:lang can be used to indicate the language of the faultstring.

R1016 A RECEIVER MUST accept fault messages that carry an xml:lang attribute on the faultstring element.

4.1.6 SOAP Custom Fault Codes

SOAP 1.1 allows custom fault codes to appear inside the faultcode element, through the use of the "dot" notation.

Use of this mechanism to extend the meaning of the SOAP 1.1-defined fault codes can lead to namespace collision. Therefore, its use should be avoided, as

Page 38

doing so may cause interoperability issues when the same names are used in the right-hand side of the "." (dot) to convey different meaning.

Instead, the Profile encourages the use of the fault codes defined in SOAP 1.1, along with additional information in the detail element to convey the nature of the Fault.

Alternatively, it is acceptable to define custom fault codes in a namespace controlled by the specifying authority.

A number of specifications have already defined custom fault codes using the "." (dot) notation. Despite this, their use in future specifications is discouraged.

R1004 When a MESSAGE contains a faultcode element the content of that element SHOULD be one of the fault codes defined in SOAP 1.1 or a namespace qualified fault code.

R1031 When a MESSAGE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to refine the meaning of the Fault.

It is recommended that applications that require custom fault codes either use the SOAP1.1 defined fault codes and supply additional information in the detail element, or that they define these codes in a namespace that is controlled by the specifying authority. For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns:c='http://example.org/faultcodes' > <faultcode>soap:Server.ProcessingError</faultcode > <faultstring>An error occurred while processing t he message </faultstring> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns:c='http://example.org/faultcodes' > <faultcode>c:ProcessingError</faultcode> <faultstring>An error occured while processing th e message </faultstring> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Server</faultcode> <faultstring>An error occured while processing th e message </faultstring> </soap:Fault>

4.1.7 SOAP encodingStyle Attribute

The soap:encodingStyle attribute is used to indicate the use of a particular scheme in the encoding of data into XML. However, this introduces complexity, as this function can also be served by the use of XML Namespaces. As a result, the Profile prefers the use of literal, non-encoded XML.

Page 39

R1005 A MESSAGE MUST NOT contain soap:encodingStyle attributes on any of the elements whose namespace name is "http://schemas.xmlsoap.org/soap/envelope/".

R1006 A MESSAGE MUST NOT contain soap:encodingStyle attributes on any element that is a child of soap:Body.

R1007 A MESSAGE described in an rpc-literal binding MUST NOT contain soap:encodingStyle attribute on any elements are grandchildren of soap:Body.

4.1.8 SOAP's use of XML

XML DTDs and PIs may introduce security vulnerabilities, processing overhead and ambiguity in message semantics when used in SOAP messages. As a result, these XML constructs are disallowed by section 3 of SOAP 1.1.

R1008 A MESSAGE MUST NOT contain a Document Type Declaration. C

R1009 A MESSAGE MUST NOT contain Processing Instructions. C

4.1.9 SOAP and XML Declarations

Presence or absence of an XML declaration does not affect interoperability. Certain implementations might always precede their XML serialization with the XML declaration.

R1010 A RECEIVER MUST accept messages that contain an XML Declaration. C

4.1.10 SOAP Trailers

The interpretation of sibling elements following the soap:Body element is unclear. Therefore, such elements are disallowed.

R1011 A MESSAGE MUST NOT have any element children of soap:Envelope following the soap:Body element.

This requirement clarifies a mismatch between the SOAP 1.1 specification and the SOAP 1.1 XML Schema. For example, INCORRECT: <soap:Envelope xmlns:soap='http://schemas.xmlsoap.o rg/soap/envelope/' > <soap:Body> <p:Process xmlns:p='http://example.org/Operatio ns' /> </soap:Body> <m:Data xmlns:m='http://example.org/information' > Here is some data with the message

Page 40

</m:Data> </soap:Envelope> CORRECT: <soap:Envelope xmlns:soap='http://schemas.xmlsoap.o rg/soap/envelope/' > <soap:Body> <p:Process xmlns:p='http://example.org/Operatio ns' > <m:Data xmlns:m='http://example.org/information' > Here is some data with the message </m:Data> </p:Process> </soap:Body> </soap:Envelope>

4.1.11 Acceptable SOAP Character Encodings

The Profile requires all XML processors are required support the "UTF-8" and "UTF-16" character encodings, in order to aid interoperability.

As a consequence of this, in conjunction with SOAP 1.1's requirement to use the text/xml media type (which has a default character encoding of "us-ascii"), the charset parameter must always be present on the SOAP envelope's media type. A further consequence of this is that the encoding pseudo-attribute of XML declaration within the message is always ignored, in accordance with the requirements of both XML 1.0 and RFC3023, "XML Media Types".

R1012 A MESSAGE MUST be serialized as either UTF-8 or UTF-16.

R1018 The media type of a MESSAGE's envelope MUST indicate the correct character encoding, using the charset parameter. C

When SOAP is used with the HTTP binding, the media type is carried in the Content-Type HTTP header field.

4.1.12 SOAP mustUnderstand Attribute

The soap:mustUnderstand attribute has a restricted type of "xsd:boolean" that takes only "0" or "1". Therefore, only those two values are allowed.

R1013 A MESSAGE containing a soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1". C

4.1.13 SOAP Body and Namespaces

The use of unqualified element names may cause naming conflicts, therefore qualified names must be used for the children of soap:Body .

R1014 The children of the soap:Body element in a MESSAGE MUST be namespace qualified.

Page 41

4.1.14 SOAP Envelope Namespace

SOAP 1.1 states that a message with an Envelope element with a namespace name other than "http://schemas.xmlsoap.org/soap/envelope/" should be discarded. The Profile requires that a Fault be generated instead, to assure unambiguous operation.

R1015 A RECEIVER MUST generate a fault if they encounter a message whose document element has a local name of "Envelope" but a namespace name that is not "http://schemas.xmlsoap.org/soap/envelope/".

4.1.15 Use of xsi:type Attributes

In many cases, senders and receivers will share some form of type information related to the messages being exchanged. The xsi:type attribute is only needed where no such schema exists, that is where both sides are assuming that all exchanged items are "xsd:anyType".

R1017 A RECEIVER MUST NOT mandate the use of the xsi:type attribute in messages except as required in order to indicate a derived type (see XML Schema Part 1: Structures, Section 2.6.1).

4.2 SOAP Processing Model


SOAP 1.1, Section 2

SOAP 1.1 defines a message exchange model for processing of messages. In particular, it defines rules for the processing of header blocks and the body of message. It also defines rules related to generation of faults. The Profile places the following constraints on the processing model:

4.2.1 Mandatory Headers

SOAP 1.1's processing model is underspecified with respect to the processing of mandatory header blocks. Mandatory header blocks are those children of the soap:Header element bearing a soap:mustUnderstand attribute with a value of "1".

R1025 A RECEIVER MUST handle messages in such a way that it appears that all checking of mandatory header blocks is performed before any actual processing. SOAP12

This requirement guarantees that no undesirable side effects will occur as a result of noticing a mandatory header block after processing other parts of the message.

Page 42

4.2.2 Generating mustUnderstand Faults

The Profile requires that receivers generate a Fault when they encounter header blocks that they do not understand targeted at them.

R1027 A RECEIVER MUST generate a "soap:MustUnderstand" fault when a message contains a mandatory header block (i.e., one that has a soap:mustUnderstand attribute with the value "1") targeted at the receiver (via soap:actor) that the receiver does not understand.

4.2.3 SOAP Fault Processing

When a Fault is generated, no further processing should be performed. In request-response exchanges, a Fault message will be transmitted to the sender of the request message, and some application level error will be flagged to the user.

R1028 When a Fault is generated by a RECEIVER, further processing SHOULD NOT be performed on the SOAP message aside from that which is necessary to rollback, or compensate for, any effects of processing the message prior to the generation of the Fault.

R1029 Where the normal outcome of processing a SOAP message would have resulted in the transmission of a SOAP response, but rather a SOAP Fault is generated instead, a RECEIVER MUST transmit a SOAP Fault message in place of the response.

R1030 A RECEIVER that generates a SOAP Fault SHOULD notify the end user that a SOAP Fault has been generated when practical, by whatever means is deemed appropriate to the circumstance.

4.3 Use of SOAP in HTTP


SOAP 1.1, Section 6

HTTP/1.1

HTTP State Management Mechanism

SOAP 1.1 defines a single protocol binding, for HTTP. The Profile mandates the use of that binding, and places the following constraints on its use:

Page 43

4.3.1 HTTP Versions

Several versions of HTTP are defined. HTTP/1.1 has performance advantages, and is more clearly specified than HTTP/1.0.

R1140 A MESSAGE SHOULD be sent using HTTP/1.1.

R1141 A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.

Note that support for HTTP/1.0 is implied in HTTP/1.1, and that intermediaries may change the version of a message; for more information about HTTP versioning, see RFC2145, "Use and Interpretation of HTTP Version Numbers."

4.3.2 Identifying SOAP Faults

Some consumer implementations use only the HTTP status code to determine the presence of a SOAP Fault. Because there are situations where the Web infrastructure changes the HTTP status code, and for general reliability, the Profile requires that they examine the envelope.

R1107 A RECEIVER MUST interpret SOAP messages containing only a soap:Fault element as a Fault.

4.3.3 HTTP Methods and Extensions

The SOAP1.1 specification defined its HTTP binding such that two possible methods could be used, the HTTP POST method and the HTTP Extension Framework's M-POST method. The Profile requires that only the HTTP POST method be used and precludes use of the HTTP Extension Framework.

R1132 A HTTP request MESSAGE MUST use the HTTP POST method.

R1108 A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).

The HTTP Extension Framework is an experimental mechanism for extending HTTP in a modular fashion. Because it is not deployed widely and also because its benefits to the use of SOAP are questionable, the Profile does not allow its use.

4.3.4 SOAPAction Header Syntax

Testing has demonstrated that requiring the SOAPAction HTTP header field-value to be quoted increases interoperability of implementations. Even though HTTP allows unquoted header field-values, some SOAP implementations require that they be quoted.

SOAPAction is purely a hint to processors. All vital information regarding the intent of a message is carried in soap:Envelope .

Page 44

R1109 The value of the SOAPAction HTTP header field in a HTTP request MESSAGE MUST be a quoted string. C

R1119 A RECEIVER MAY respond with a Fault if the value of the SOAPAction HTTP header field is not quoted. C

For example, CORRECT:

A WSDL Description that has:

<soapbind:operation soapAction="foo" />

results in a message with a SOAPAction HTTP header field of:

SOAPAction: "foo"

CORRECT:


<soapbind:operation />

or

<soapbind:operation soapAction="" />

results in a message with a corresponding SOAPAction HTTP header field as follows:

SOAPAction: ""

4.3.5 HTTP and TCP Ports

SOAP is designed to take advantage of the HTTP infrastructure. However, there are some situations (e.g., involving proxies, firewalls and other intermediaries) where there may be harmful side effects. As a result, instances may find it advisable to use ports other than the default for HTTP (port 80).

R1110 An INSTANCE MAY accept connections on TCP port 80 (HTTP). C

There has been considerable debate within the W3C and IETF regarding the propriety of the use of port 80 for SOAP messages bound to HTTP. It has been concluded that this is an acceptable practice.

4.3.6 HTTP Success Status Codes

HTTP uses the 2xx series of status codes to communicate success. In particular, 200 is the default for successful messages, but 202 can be used to indicate that a message has been submitted for processing. Additionally, other 2xx status codes may be appropriate, depending on the nature of the HTTP interaction.

Page 45

R1124 An INSTANCE MUST use a 2xx HTTP status code for responses that indicate a successful outcome of a request.

R1111 An INSTANCE SHOULD use a "200 OK" HTTP status code for responses that contain a SOAP message that is not a SOAP fault.

R1112 An INSTANCE SHOULD use either a "200 OK" or "202 Accepted" HTTP status code for a response that does do not contain a SOAP message but indicates successful HTTP outcome of a request.

4.3.7 HTTP Redirect Status Codes

There are interoperability problems with using many of the HTTP redirect status codes, generally surrounding whether to use the original method, or GET. The Profile mandates "307 Temporary Redirect", which has the semantic of redirection with the same HTTP method, as the correct status code for redirection. For more information, see the 3xx status code descriptions in RFC2616.

R1130 An INSTANCE MUST use HTTP status code "307 Temporary Redirect" when redirecting a request to a different endpoint.

R1131 A CONSUMER MAY automatically redirect a request when it encounters a "307 Temporary Redirect" HTTP status code in a response.

RFC2616 notes that user-agents should not automatically redirect requests; however, this requirement was aimed at browsers, not automated processes (which many Web services will be). Therefore, the Profile allows, but does not require, consumers to automatically follow redirections.

4.3.8 HTTP Client Error Status Codes

HTTP uses the 4xx series of status codes to indicate failure due to a client error. Although there are a number of situations that may result in one of these codes, the Profile highlights those when the payload of the HTTP request is not the proper media type (i.e., "text/xml", as required by the SOAP/HTTP binding), and when the anticipated method ("POST") is not used.

R1125 An INSTANCE MUST use a 4xx HTTP status code for responses that indicate a problem with the format of the request.

R1113 An INSTANCE SHOULD use a "400 Bad Request "HTTP status code, if the request message is a malformed HTTP request, or not well-formed XML.

Page 46

R1114 An INSTANCE SHOULD use a "405 Method not Allowed" HTTP status code if the request method was not "POST".

R1115 An INSTANCE SHOULD use a "415 Unsupported Media Type" HTTP status code if the Content-Type HTTP request header did not have a value consistent with the value specified for the corresponding binding of the input message.

Note that these requirements do not force an instance to respond to requests. In some cases, such as Denial of Service attacks, an instance may choose to ignore requests.

4.3.9 HTTP Server Error Status Codes

HTTP uses the 5xx series of status codes to indicate failure due to a server error.

R1126 An INSTANCE MUST use a "500 Internal Server Error" HTTP status code if the response message is a SOAP Fault.

4.3.10 HTTP Cookies

The HTTP State Management Mechanism ("Cookies") allows the creation of stateful sessions between Web browsers and servers. Being designed for hypertext browsing, Cookies do not have well-defined semantics for Web services, and, because they are external to the SOAP Envelope, are not accommodated by either SOAP 1.1 or WSDL 1.1. However, there are situations where it may be necessary to use Cookies; e.g., for load balancing between servers, or for integration with legacy systems that use Cookies. For these reasons, the Profile limits the ways in which Cookies can be used, without completely disallowing them.

R1120 An INSTANCE MAY use the HTTP state mechanism ("Cookies").

R1122 An INSTANCE using Cookies SHOULD conform to RFC2965.

R1121 An INSTANCE SHOULD NOT require consumer support for Cookies in order to function correctly.

R1123 The value of the cookie MUST be considered to be opaque by the CONSUMER.

The Profile recommends that cookies not be required by instances for proper operation; they should be a hint, to be used for optimization, without materially affecting the execution of the Web service. However, they may be required in legacy integration and other exceptional use cases, so requiring them does not make an instance non-conformant. While Cookies thus may have meaning to the instance, they should not be used as an out-of-bound data channel between the

Page 47

instance and the consumer. Therefore, interpretation of Cookies is not allowed at all by the consumer - it is required to treat them as opaque (i.e., have no meaning to the consumer).

5. Service Description

The Profile uses Web Services Description Language (WSDL) to enable the description of services as sets of endpoints operating on messages.


Web Services Description Language (WSDL) 1.1 Extensibility points:

WSDL extensions - WSDL allows extension elements in certain places; use of such extensions requires out-of-band negotiation.

Relative URIs - WSDL does not adequately specify the use of relative URIs; their use may require further coordination; see XML Base for more information.

Validation mode - whether the parser used to read WSDL and XML Schema documents performs DTD validation or not.

Fetching of external resources - whether the parser used to read WSDL and XML Schema documents fetches external entities and DTDs.

XML Schema Part 1: Structures Extensibility points:

Schema annotations - XML Schema allows for annotations, which may be used to convey additional information about data structures.

XML Schema Part 2: Datatypes

5.1 Document Structure


WSDL 1.1, Section 2.1

WSDL 1.1 defines an XML-based structure for describing Web services. The Profile mandates the use of that structure, and places the following constraints on its use:

Page 48

5.1.1 WSDL Schema Definitions

The normative schemas for WSDL appearing in Appendix 4 of the WSDL 1.1 specification have inconsistencies with the normative text of the specification. The Profile references new schema documents that have incorporated fixes for known errors.

R2028 A DESCRIPTION using the WSDL namespace (prefixed "wsdl" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd".

R2029 A DESCRIPTION using the WSDL SOAP binding namespace (prefixed "soapbind" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd".

Although the Profile requires WSDL descriptions to be Schema valid, it does not require consumers to validate WSDL documents. It is the responsibility of a WSDL document's author to assure that it is Schema valid.

5.1.2 WSDL and Schema Import

Some examples in WSDL 1.1 incorrectly show the WSDL import statement being used to import XML Schema definitions. The Profile clarifies use of the import mechanisms to keep them consistent and confined to their respective domains. Imported schema documents are also constrained by XML version and encoding requirements consistent to those of the importing WSDL documents.

R2001 A DESCRIPTION MUST only use the WSDL "import" statement to import another WSDL description.

R2002 To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema "import" statement.

R2003 A DESCRIPTION MUST use the XML Schema "import" statement only within the xsd:schema element of the types section.

R2004 A DESCRIPTION MUST NOT use the XML Schema "import" statement to import a Schema from any document whose root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".

R2009 An XML Schema directly or indirectly imported by a DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).

Page 49

R2010 An XML Schema directly or indirectly imported by a DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.

R2011 An XML Schema directly or indirectly imported by a DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

For example, INCORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/d efinitions" xmlns:xsd1="http://example.com/stockquote/schema s"" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /schemas" location="http://example.com/stockquote/st ockquote.xsd"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceR equest"/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquot e/definitions"> <import namespace="http://example.com/stockqu ote/definitions" location="http://example.com/stockquote/ stockquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="..."/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/" xmlns:xsd1="http://example.com/stockquote/schema s" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /definitions" location="http://example.com/stockquote/sto ckquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceReq uest"/> </message> ... </definitions>

5.1.3 WSDL Import location Attribute Syntax

WSDL 1.1 is not clear about whether the location attribute of the wsdl:import statement is required, or what its content is required to be.

Page 50

R2007 A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.

Although the wsdl:import statement is modeled after the xsd:import statement, the location attribute is required by wsdl:import while the corresponding attribute on xsd:import , schemaLocation is optional. Consistent with location being required, its content is not intended to be empty.

5.1.4 WSDL Import location Attribute Semantics

WSDL 1.1 is unclear about whether WSDL processors must actually retrieve and process the WSDL document from the URI specified in the location attribute on the wsdl:import statements it encounters.

R2008 In a DESCRIPTION the value of the location attribute of a wsdl:import element SHOULD be treated as a hint. C

This means that WSDL processor may, but need not, retrieve a WSDL description from the URI specified in the location attribute on a wsdl:import element because a WSDL processor may have other ways of locating a WSDL description for a given namespace. For example, it may already have a cached or built-in representation, or it may retrieve a representation from a metadata repository or UDDI server.

5.1.5 Placement of WSDL import Elements

Example 3 in WSDL 1.1 Section 3.1 causes confusion regarding the placement of wsdl:import .

R2022 When they appear in a DESCRIPTION, wsdl:import elements MUST precede all other elements from the WSDL namespace except wsdl:documentation.

R2023 When they appear in a DESCRIPTION, wsdl:types elements MUST precede all other elements from the WSDL namespace except wsdl:documentation and wsdl:import.

For example, INCORRECT: <definitions name="StockQuote" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /definitions" location="http://example.com/stockquote/st ockquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" type="tns:TradePriceReques t"/> </message> ... <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:Stoc kQuoteSoap">

Page 51

.... </port> </service> <types> <schema targetNamespace="http://example.com/s tockquote/schemas" xmlns="http://www.w3.org/2001/XMLSch ema"> ....... </schema> </types> </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquot e/definitions"> <import namespace="http://example.com/stockquo te/base" location="http://example.com/stockquote/stoc kquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="..."/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema targetNamespace="http://example.com/st ockquote/schemas" xmlns="http://www.w3.org/2001/XMLSchema"> ....... </schema> </types> <message name="GetLastTradePriceInput"> <part name="body" element="tns:TradePriceRe quest"/> </message> ... <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:Stoc kQuoteSoap"> .... </port> </service> </definitions>

5.1.6 XML Version Requirements

Neither WSDL 1.1 nor XML Schema 1.0 mandate a particular version of XML. For interoperability, WSDL documents and the schemas they import expressed in XML must use version 1.0.

R4004 A DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

Page 52

5.1.7 WSDL and the Unicode BOM

XML 1.0 allows documents that use the UTF-8 character encoding to include a BOM; therefore, description processors must be prepared to accept them.

R4002 A DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).C

5.1.8 Acceptable WSDL Character Encodings

The Profile consistently requires either UTF-8 or UTF-16 encoding for both SOAP and WSDL (see also R1012).

R4003 A DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.

5.1.9 Namespace Coercion

Namespace coercion on wsdl:import is disallowed by the Profile.

R2005 The targetNamespace attribute on the wsdl:definitions element of a description that is being imported MUST have same the value as the namespace attribute on the wsdl:import element in the importing DESCRIPTION.

5.1.10 WSDL documentation Element

The WSDL 1.1 schema and the WSDL 1.1 specification are inconsistent with respect to where wsdl:documentation elements may be placed.

R2020 The wsdl:documentation element MAY occur as a child of the wsdl:import element in a DESCRIPTION. WSDL20

R2021 The wsdl:documentation element MAY occur as a child of the wsdl:part element in a DESCRIPTION. WSDL20

R2024 The wsdl:documentation element MAY occur as a first child of the wsdl:definitions element in a DESCRIPTION. WSDL20

5.1.11 WSDL Extensions

Requiring support for WSDL extensions that are not explicitly specified by this or another WS-I Profile can lead to interoperability problems with development tools that have not been instrumented to understand those extensions.

R2025 A DESCRIPTION containing WSDL extensions MUST NOT use them to contradict other requirements of the Profile.

R2026 A DESCRIPTION SHOULD NOT include extension elements with a wsdl:required attribute value of "true" on any

Page 53

WSDL construct (wsdl:binding, wsdl:portType, wsdl:message, wsdl:types or wsdl:import) that claims conformance to the Profile.

R2027 If during the processing of an element in the WSDL namespace in a description, a consumer encounters a WSDL extension element amongst its element children, that has a wsdl:required attribute with a boolean value of "true" that the consumer does not understand or cannot process, the CONSUMER MUST fail processing of that element in the WSDL namespace.

Development tools that consume a WSDL description and generate software for a Web service instance might not have built-in understanding of an unknown WSDL extension. Hence, use of required WSDL extensions should be avoided. Use of a required WSDL extension that does not have an available specification for its use and semantics imposes potentially insurmountable interoperability concerns for all but the author of the extension. Use of a required WSDL extension that has an available specification for its use and semantics reduces, but does not eliminate the interoperability concerns that lead to this refinement.

The following elements are extensible via attributes only:

wsdl:import

wsdl:part

wsdl:portType

wsdl:input (in portType operation)

wsdl:output (in portType operation)

wsdl:fault (in portType operation)

The following elements are extensible via elements as well as attributes:

wsdl:definitions

wsdl:types

wsdl:message

wsdl:operation

wsdl:binding

wsdl:input (in binding operation)

wsdl:output (in binding operation)

wsdl:fault (in binding operation)

wsdl:service

Page 54

wsdl:port

5.2 Types



The wsdl:types element of WSDL 1.1 encloses data type definitions that are relevant to the Web service described. The Profile places the following constraints pertinent to those portions of the content of the wsdl:types element that are referred to by WSDL elements that make Profile conformance claims:

5.2.1 QName References

XML Schema requires each QName reference to use either the target namespace, or an imported namespace (one marked explicitly with an xsd:import element). QName references to namespaces represented only by nested imports are not allowed.

WSDL 1.1 is unclear as to which schema target namespaces are suitable for QName references from a WSDL element. The Profile allows QName references from WSDL elements both to the target namespace defined by the xsd:schema element, and to imported namespaces. Similar to XML Schema, namespaces not referenced directly within the WSDL file (through the targetNamespace attribute on xsd:schema , or through the namespace attribute on xsd:import ) are available for use in QName reference. QName references to namespaces that are only defined through a nested import are not allowed.

R2101 A DESCRIPTION MUST NOT use QName references to elements in namespaces that have been neither imported, nor defined in the referring WSDL document.

R2102 A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in the targetNamespace attribute on the xsd:schema element, or to a namespace defined in the namespace attribute on an xsd:import element within the xsd:schema element.

5.2.2 Schema targetNamespace Syntax

Requiring a targetNamespace on all xsd:schema elements that are children of wsdl:types is a good practice, places a minimal burden on authors of WSDL documents, and avoids the cases that are not as clearly defined as they might be.

R2105 All xsd:schema elements contained in a wsdl:types element of a DESCRIPTION MUST have a targetNamespace

Page 55

attribute with a valid and non-null value, UNLESS the xsd:schema element has xsd:import and/or xsd:annotation as its only child element(s).

5.2.3 soapenc:Array

The recommendations in WSDL 1.1 Section 2.2 for declaration of array types have been interpreted in various ways, leading to interoperability problems. Further, there are other clearer ways to declare arrays.

R2110 In a DESCRIPTION, array declarations MUST NOT extend or restrict the soapenc:Array type.

R2111 In a DESCRIPTION, array declarations MUST NOT use wsdl:arrayType attribute in the type declaration.

R2112 In a DESCRIPTION, array declaration wrapper elements SHOULD NOT be named using the convention ArrayOfXXX.

R2113 A MESSAGE containing serialized arrays MUST NOT include the soapenc:arrayType attribute.

For example, INCORRECT:

Given the WSDL Description: <xsd:element name="MyArray2" type="tns:MyArray2Type "/> <xsd:complexType name="MyArray2Type" xmlns:soapenc="http://schemas.xmlsoap.org/soap/enc oding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" > <xsd:complexContent> <xsd:restriction base="soapenc:Array"> <xsd:sequence> <xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="tns:MyArray2Type[]"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType>

The SOAP message would serialize as (omitting namespace declarations for clarity): <MyArray2 soapenc:arrayType="tns:MyArray2Type[]" > <x>abcd</x> <x>efgh</x> </MyArray2> CORRECT:

Given the WSDL Description: <xsd:element name="MyArray1" type="tns:MyArray1Type "/> <xsd:complexType name="MyArray1Type">

Page 56

<xsd:sequence> <xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType>

The SOAP message would serialize as (omitting namespace declarations for clarity): <MyArray1> <x>abcd</x> <x>efgh</x> </MyArray1>

5.2.4 WSDL and Schema Definition Target Namespaces

The names defined by schemas and the names assigned to WSDL definitions are in separate symbol spaces.

R2114 The target namespace for WSDL definitions and the target namespace for schema definitions in a DESCRIPTION MAY be the same.WSDL20

5.3 Messages



In WSDL 1.1, wsdl:message elements are used to represent abstract definitions of the data being transmitted. It uses wsdl:binding elements to define how the abstract definitions are bound to a specific wire format. The Profile places the following constraints on wsdl:message elements and on how conformant wsdl:binding elements may use wsdl:message element(s).

In this section the following definitions are used to make the requirements more compact and easier to understand.

An "rpc-literal binding" is a wsdl:binding element whose child wsdl:operation elements are all rpc-literal operations.

An "rpc-literal operation" is a wsdl:operation child element of wsdl:binding each of whose soapbind:body descendant elements specifies the use attribute with the value "literal" and each of which either:

Specifies the style attribute with the value "rpc"; or

Is the child of a soapbind:binding element which specifies the style attribute with the value "rpc", and does not itself have the style attribute specified.

A "document-literal binding" is a wsdl:binding element whose child wsdl:operation elements are all document-literal operations.

Page 57

A "document-literal operation" is a wsdl:operation child element of wsdl:binding each of whose soapbind:body descendent elements specifies the use attribute with the value "literal" and each of which either:

Specifies the style attribute with the value "document"; or

Is the child of a soapbind:binding element which specifies the style attribute with the value "document", and does not itself have the style attribute specified; or

Is the child of a soapbind:binding element which does not have the style attribute specified, and does not itself have the style attribute specified.

5.3.1 Bindings and Parts

There are various interpretations about how many wsdl:part elements are permitted or required for document-literal and rpc-literal bindings and how they must be defined.

R2201 A document-literal binding in a DESCRIPTION MUST, in each of its soapbind:body element(s), have at most one part listed in the parts attribute, if the parts attribute is specified.

R2210 If a document-literal binding in a DESCRIPTION does not specify the parts attribute on a soapbind:body element, the corresponding abstract wsdl:message MUST define zero or one wsdl:parts.

R2202 A wsdl:binding in a DESCRIPTION MAY contain soapbind:body element(s) that specify that zero parts form the soap:Body.

R2203 An rpc-literal binding in a DESCRIPTION MUST refer, in its soapbind:body element(s), only to wsdl:part element(s) that have been defined using the type attribute.

R2211 A MESSAGE described with an rpc-literal binding MUST NOT have the xsi:nil attribute with a value of "1" or "true" on the part accessors.

R2207 A wsdl:message in a DESCRIPTION MAY contain wsdl:parts that use the elements attribute provided those wsdl:parts are not referred to by a soapbind:body in an rpc-literal binding.

R2204 A document-literal binding in a DESCRIPTION MUST refer, in each of its soapbind:body element(s), only to wsdl:part element(s) that have been defined using the element attribute.

Page 58

R2208 A binding in a DESCRIPTION MAY contain soapbind:header element(s) that refer to wsdl:parts in the same wsdl:message that are referred to by its soapbind:body element(s).

Use of wsdl:message elements with zero parts is permitted in Document styles to permit operations that can send or receive messages with empty soap:Body s. Use of wsdl:message elements with zero parts is permitted in RPC styles to permit operations that have no (zero) parameters and/or a return value.

For document-literal bindings, the Profile requires that at most one part, abstractly defined with the element attribute, be serialized into the soap:Body element.

When a wsdl:part element is defined using the type attribute, the wire representation of that part is equivalent to an implicit (XML Schema) qualification of a minOccurs attribute with the value "1", a maxOccurs attribute with the value "1" and a nillable attribute with the value "false".

5.3.2 Bindings and Faults

There are several interpretations for how wsdl:part elements that describe soapbind:fault , soapbind:header , and soapbind:headerfault may be defined.

R2205 A wsdl:binding in a DESCRIPTION MUST refer, in each of its soapbind:header, soapbind:headerfault and soapbind:fault elements, only to wsdl:part element(s) that have been defined using the element attribute.

Because faults and headers do not contain parameters, soapbind:fault , soapbind:header and soapbind:headerfault assume, per WSDL 1.1, that the value of the style attribute is "document". R2204 requires that all wsdl:part elements with a style attribute whose value is "document" that are bound to soapbind:body be defined using the element attribute. This requirement does the same for soapbind:fault , soapbind:header and soapbind:headerfault elements.

5.3.3 Unbound portType Element Contents

WSDL 1.1 is not explicit about whether it is permissible for a wsdl:binding to leave the binding for portions of the content defined by a wsdl:portType unspecified.

R2209 A wsdl:binding in a DESCRIPTION SHOULD bind every wsdl:part of a wsdl:message in the wsdl:portType to which it refers to one of soapbind:body, soapbind:header, soapbind:fault or soapbind:headerfault.

A portType defines an abstract contract with a named set of operations and associated abstract messages. Although not disallowed, it is expected that every

Page 59

part of the abstract input, output and fault messages specified in a portType is bound to soapbind:body or soapbind:header (and so forth) as appropriate when using the SOAP binding as defined in WSDL 1.1 Section 3.

5.3.4 Declaration of part Elements

Examples 4 and 5 in WSDL 1.1 Section 3.1 incorrectly show the use of XML Schema types (e.g. "xsd:string") as a valid value for the element attribute of a wsdl:part element.

R2206 A wsdl:message in a DESCRIPTION containing a wsdl:part that uses the element attribute MUST refer, in that attribute, to a global element declaration.

For example, INCORRECT: <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string "/> <part name="time" element="xsd:timeInstant"/> </message> INCORRECT: <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string "/> </message> CORRECT: <message name="GetTradePriceInput"> <part name="body" element="tns:SubscribeToQuo tes"/> </message>

5.4 Port Types



In WSDL 1.1, wsdl:portType elements are used to group a set of abstract operations. The Profile places the following constraints on conformant wsdl:portType element(s):

5.4.1 Ordering of part Elements

Permitting the use of parameterOrder helps code generators in mapping between method signatures and messages on the wire.

R2301 The order of the elements in the soap:body of a MESSAGE MUST be the same as that of the wsdl:parts in the wsdl:message that describes it.

R2302 A DESCRIPTION MAY use the parameterOrder attribute of an wsdl:operation element to indicate the return value and method signatures as a hint to code generators.

Page 60

5.4.2 Allowed Operations

Solicit-Response and Notification operations are not well defined by WSDL 1.1; furthermore, WSDL 1.1 does not define bindings for them.

R2303 A DESCRIPTION MUST NOT use Solicit-Response and Notification type operations in a wsdl:portType definition.

5.4.3 Distinctive Operations

Operation name overloading in a wsdl:portType is disallowed by the Profile.

R2304 A wsdl:portType in a DESCRIPTION MUST have operations with distinct values for their name attributes.

Note that this requirement applies only to the wsdl:operation s within a given wsdl:portType . A wsdl:portType may have wsdl:operation s with names that are the same as those found in other wsdl:portType s.

5.4.4 parameterOrder Attribute Construction

WSDL 1.1 does not clearly state how the parameterOrder attribute of the wsdl:portType should be constructed.

R2305 A wsdl:portType in a DESCRIPTION MUST be constructed so that the parameterOrder attribute, if present, omits at most 1 wsdl:part from the output message.

If a wsdl:part from the output message is omitted from the list of wsdl:part s that is the value of the parameterOrder attribute, the single omitted wsdl:part is the return value. There are no restrictions on the type of the return value. If no part is omitted, there is no return value.

5.4.5 Exclusivity of type and element Attributes

WSDL 1.1 does not clearly state that both type and element attributes cannot be specified to define a wsdl:part in a wsdl:message .

R2306 A wsdl:message in a DESCRIPTION MUST NOT specify both type and element attributes on the same wsdl:part.

5.5 Bindings



In WSDL 1.1, the wsdl:binding element supplies the concrete protocol and data format specifications for the operations and messages defined by a particular

Page 61

wsdl:portType . The Profile places the following constraints on conformant binding specifications:

5.5.1 Use of SOAP Binding

The Profile limits the choice of bindings to the well defined and most commonly used SOAP binding. MIME and HTTP GET/POST bindings are not permitted by the Profile.

R2401 A wsdl:binding element in a DESCRIPTION MUST use WSDL SOAP Binding as defined in WSDL 1.1 Section 3.

Note that this places a requirement on the construction of conformant wsdl:binding elements. It does not place a requirement on descriptions as a whole; in particular, it does not preclude WSDL documents from containing non-conformant wsdl:binding elements.

5.6 SOAP Binding



WSDL 1.1 defines a binding for SOAP 1.1 endpoints. The Profile mandates the use of SOAP binding as defined in WSDL 1.1, and places the following constraints on its use:

5.6.1 Specifying the transport Attribute

There is an inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding the transport attribute. The WSDL 1.1 specification requires it; however, the schema shows it to be optional.

R2701 The wsdl:binding element in a DESCRIPTION MUST be constructed so that its soapbind:binding child element specifies the transport attribute.

5.6.2 HTTP Transport

The profile limits the underlying transport protocol to HTTP.

R2702 A wsdl:binding element in a DESCRIPTION MUST specify the HTTP transport protocol with SOAP binding. Specifically, the transport attribute of its soapbind:binding child MUST have the value "http://schemas.xmlsoap.org/soap/http".

Note that this requirement does not prohibit the use of HTTPS; See R5000.

Page 62

5.6.3 Consistency of style Attribute

The style , "document" or "rpc", of an interaction is specified at the wsdl:operation level, permitting wsdl:binding s whose wsdl:operation s have different style s. This has led to interoperability problems.

R2705 A wsdl:binding in a DESCRIPTION MUST use either be a rpc-literal binding or a document-literal binding.

5.6.4 Encodings and the use Attribute

The Profile prohibits the use of encodings, including the SOAP encoding.

R2706 A wsdl:binding in a DESCRIPTION MUST use the value of "literal" for the use attribute in all soapbind:body, soapbind:fault, soapbind:header and soapbind:headerfault elements.

5.6.5 Default for use Attribute

There is an inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding whether the use attribute is optional on soapbind:body , soapbind:header , and soapbind:headerfault , and if so, what omitting the attribute means.

R2707 A wsdl:binding in a DESCRIPTION that contains one or more soapbind:body, soapbind:fault, soapbind:header or soapbind:headerfault elements that do not specify the use attribute MUST be interpreted as though the value "literal" had been specified in each case.

5.6.6 Multiple Bindings for portType Elements

The Profile explicitly permits multiple bindings for the same portType.

R2709 A wsdl:portType in a DESCRIPTION MAY have zero or more wsdl:bindings that refer to it, defined in the same or other WSDL documents.

5.6.7 Wire Signatures for Operations

An endpoint that supports multiple operations must unambiguously identify the operation being invoked based on the input message that it receives. This is only possible if all the operations specified in the wsdl:binding associated with an endpoint have a unique wire signature.

R2710 The operations in a wsdl:binding in a DESCRIPTION MUST result in wire signatures that are different from one another.

Page 63

The Profile defines the "wire signature" of an operation in a wsdl:binding to be the fully qualified name of the child element of the soap:Body of the SOAP input message it describes. For the case of an empty soap:Body this name is an empty string.

In the case of rpc-literal binding, the operation name is used as a wrapper for the part accessors. In the document-literal case, since a wrapper with the operation name is not present, the message signatures must be correctly designed so that they meet this requirement.

5.6.8 Multiple Ports on an Endpoint

When input messages destined for two different wsdl:port s at the same network endpoint are indistinguishable on the wire, it may not be possible to determine the wsdl:port being invoked by them. This may cause interoperability problems. However, there may be situations (e.g., SOAP versioning, application versioning, conformance to different profiles) where it is desirable to locate more than one port on an endpoint; therefore, the Profile allows this.

R2711 A DESCRIPTION SHOULD NOT have more than one wsdl:port with the same value for the location attribute of the soapbind:address element.

5.6.9 Child Element for Document-Literal Bindings

WSDL 1.1 is not completely clear what, in document-literal style bindings, the child element of soap:Body is.

R2712 A document-literal binding MUST be represented on the wire as a MESSAGE with a soap:Body whose child element is an instance of the global element declaration referenced by the corresponding wsdl:message part.

5.6.10 One-Way Operations

There are differing interpretations of how HTTP is to be used when performing one-way operations.

R2714 For one-way operations, an INSTANCE MUST NOT return a HTTP response that contains a SOAP envelope. Specifically, the HTTP response entity-body must be empty.

R2750 A CONSUMER MUST ignore a SOAP response carried in a response from a one-way operation.

R2727 For one-way operations, a CONSUMER MUST NOT interpret a successful HTTP response status code (i.e., 2xx) to mean the message is valid or that the receiver would process it.

Page 64

One-way operations do not produce SOAP responses. Therefore, the Profile prohibits sending a SOAP envelope in response to a one-way operation. This means that transmission of one-way operations can not result in processing level responses or errors. For example, a "500 Internal Server Error" HTTP response that includes a SOAP message containing a SOAP Fault element can not be returned.

The HTTP response to a one-way operation indicates the success or failure of the transmission of the message. Based on the semantics of the different response status codes supported by the HTTP protocol, the Profile specifies that "200" and "202" are the preferred status codes that the sender should expect, signifying that the one-way message was received. A successful transmission does not indicate that the SOAP processing layer and the application logic has had a chance to validate the message or have committed to processing it.

Despite the fact that the HTTP 1.1 assigns different meanings to response status codes "200" and "202", in the context of the Profile they should be considered equivalent by the initiator of the request. The Profile accepts both status codes because some SOAP implementations have little control over the HTTP protocol implementation and cannot control which of these response status codes is sent.

5.6.11 Namespaces for soapbind Elements

There is confusion about what namespace is associated with the child elements of various children of soap:Envelope , which has led to interoperability difficulties. The Profile defines these.

R2716 A document-literal binding in a DESCRIPTION MUST NOT have the namespace attribute specified on contained soapbind:body, soapbind:header, soapbind:headerfault and soapbind:fault elements.

R2717 An rpc-literal binding in a DESCRIPTION MUST have the namespace attribute specified, the value of which MUST be an absolute URI, on contained soapbind:body elements.

R2726 An rpc-literal binding in a DESCRIPTION MUST NOT have the namespace attribute specified on contained soapbind:header, soapbind:headerfault and soapbind:fault elements.

In a document-literal SOAP binding, the serialized element child of the soap:Body gets its namespace from the targetNamespace of the schema that defines the element. Use of the namespace attribute of the soapbind:body element would override the element's namespace. This is not allowed by the Profile.

Conversely, in a rpc-literal SOAP binding, the serialized child element of the soap:Body element consists of a wrapper element, whose namespace is the value of the namespace attribute of the soapbind:body element and whose local

Page 65

name is either the name of the operation or the name of the operation suffixed with "Response". The namespace attribute is required, as opposed to being optional, to ensure that the children of the soap:Body element are namespace-qualified.

5.6.12 Consistency of portType and binding Elements

The WSDL description must be consistent at both wsdl:portType and wsdl:binding levels.

R2718 A wsdl:binding in a DESCRIPTION MUST have the same set of wsdl:operations as the wsdl:portType to which it refers. C

5.6.13 Describing headerfault Elements

There is inconsistency between WSDL specification text and the WSDL schema regarding soapbind:headerfault s.

R2719 A wsdl:binding in a DESCRIPTION MAY contain no soapbind:headerfault elements if there are no known header faults.

The WSDL 1.1 schema makes the specification of soapbind:headerfault element mandatory on wsdl:input and wsdl:output elements of an operation, whereas the WSDL 1.1 specification marks them optional. The specification is correct.

5.6.14 Enumeration of Faults

A Web service description should include all faults known at the time the service is defined. There is also need to permit generation of new faults that had not been identified when the Web service was defined.

R2740 A wsdl:binding in a DESCRIPTION SHOULD contain a soapbind:fault describing each known fault.

R2741 A wsdl:binding in a DESCRIPTION SHOULD contain a soapbind:headerfault describing each known header fault.

R2742 A MESSAGE MAY contain a fault detail entry in a SOAP fault that is not described by a wsdl:fault element in the corresponding WSDL description.

R2743 A MESSAGE MAY contain the details of a header processing related fault in a SOAP header block that is not described by a wsdl:headerfault element in the corresponding WSDL description.

Page 66

5.6.15 Type and Name of SOAP Binding Elements

The WSDL 1.1 schema disagrees with the WSDL 1.1 specification about the name and type of an attribute of the soapbind:header and soapbind:headerfault elements.

R2720 A wsdl:binding in a DESCRIPTION MUST use the attribute named part with a schema type of "NMTOKEN" on all contained soapbind:header and soapbind:headerfault elements.

R2749 A wsdl:binding in a DESCRIPTION MUST NOT use the attribute named parts on contained soapbind:header and soapbind:headerfault elements.

The WSDL Schema gives the attribute's name as "parts" and its type as "NMTOKENS". The schema is incorrect since each soapbind:header and soapbind:headerfault element references a single wsdl:part . For example, CORRECT: <binding name="StockQuoteSoap" type="tns:StockQuote PortType"> <soapbind:binding style="document" transport="http://schemas.xmlsoap.o rg/soap/http"/> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"> <soapbind:body parts="body" use="literal"/> <soapbind:header message="tns:SubscribeToQu otes" part="subscribeheader" use="literal" /> </input> </operation> </binding>

5.6.16 name Attribute on Faults

There is inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema, which does not list the name attribute.

R2721 A wsdl:binding in a DESCRIPTION MUST have the name attribute specified on all contained soapbind:fault elements.

R2754 In a DESCRIPTION, the value of the name attribute on a soapbind:fault element MUST match the value of the name attribute on its parent wsdl:fault element.

5.6.17 Omission of the use Attribute

There is inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding the use attribute.

R2722 A wsdl:binding in a DESCRIPTION MAY specify the use attribute on contained soapbind:fault elements. C

Page 67

R2723 If in a wsdl:binding in a DESCRIPTION the use attribute on a contained soapbind:fault element is present, its value MUST be "literal".

R2728 A wsdl:binding in a DESCRIPTION that omits the use attribute on a contained soapbind:fault element MUST be interpreted as though use="literal" had been specified. C

WSDL 1.1 Section 3.6 indicates that the use attribute of soapbind:fault is required while in the schema the use attribute is defined as optional. The Profile defines it as optional, to be consistent with soapbind:body .

Since the use attribute is optional, the Profile identifies the default value for the attribute when omitted.

Finally, to assure that the Profile is self-consistent, the only permitted value for the use attribute is "literal".

5.6.18 Consistency of Messages with Descriptions

These requirements specify that when an instance receives a message that does not conform to the WSDL description, a fault should be generated unless the instance takes it upon itself to process the message regardless of this.

As specified by the SOAP processing model, (a) a "VersionMismatch" faultcode must be generated if the namespace of the "Envelope" element is incorrect, (b) a "MustUnderstand" fault must be generated if the instance does not understand a SOAP header block with a value of "1" for the soap:mustUnderstand attribute. In all other cases where a message is inconsistent with its WSDL description, a fault with a "Client" faultcode should be generated.

R2724 If an INSTANCE receives a message that is inconsistent with its WSDL description, it SHOULD generate a soap:Fault with a faultcode of "Client", unless a "MustUnderstand" or "VersionMismatch" fault is generated.

R2725 If an INSTANCE receives a message that is inconsistent with its WSDL description, it MUST check for "VersionMismatch", "MustUnderstand" and "Client" fault conditions in that order.

5.6.19 Response Wrappers

WSDL 1.1 Section 3.5 could be interpreted to mean the RPC response wrapper element must be named identical to the name of the wsdl:operation .

R2729 A MESSAGE described with an rpc-literal binding that is a response message MUST have a wrapper element whose name is the corresponding wsdl:operation name suffixed with the string "Response".

Page 68

5.6.20 Namespace for Part Accessors

For rpc-literal SOAP messages, WSDL 1.1 is not clear what namespace, if any, the accessor elements for parameters and return value are a part of. Different implementations make different choices, leading to interoperability problems.

R2735 A MESSAGE described with an rpc-literal binding MUST place the part accessor elements for parameters and return value in no namespace.

Settling on one alternative is crucial to achieving interoperability. The Profile places the part accessor elements in no namespace as doing so is simple, covers all cases, and does not lead to logical inconsistency.

5.6.21 Namespaces for Children of Part Accessors

For rpc-literal SOAP messages, WSDL 1.1 is not clear on what the correct namespace qualification is for the child elements of the part accessor elements when the corresponding abstract parts are defined to be of types from a different namespace than the targetNamespace of the WSDL description for the abstract parts.

R2737 A MESSAGE described with an rpc-literal binding MUST namespace qualify the children of part accessor elements for the parameters and the return value with the targetNamespace in which their types are defined.

WSDL 1.1 Section 3.5 states: "The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content not explicitly defined by the abstract types."

However, it does not explicitly state that the element and attribute content of the abstract (complexType) types is namespace qualified to the targetNamespace in which those elements and attributes were defined. WSDL 1.1 was intended to function in much the same manner as XML Schema. Hence, implementations must follow the same rules as for XML Schema. If a complexType defined in targetNamespace "A" were imported and referenced in an element declaration in a schema with targetNamespace "B", the element and attribute content of the child elements of that complexType would be qualified to namespace "A" and the element would be qualified to namespace "B". For example, CORRECT:

Given this WSDL, which defines some schema in the "http://example.org/foo/" namespace in the wsdl:types section contained within a wsdl:definitions that has a targetNamespace attribute with the value "http://example.org/bar/" (thus, having a type declared in one namespace and the containing element defined in another); <definitions xmlns="http://schemas.xmlsoap.org/wsdl /" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

Page 69

xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soa p/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:bar="http://example.org/bar/" targetNamespace="http://example.org/bar/" xmlns:foo="http://example.org/foo/"> <types> <xsd:schema targetNamespace="http://example.org/ foo/" xmlns:tns="http://example.org/foo/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xsd:complexType name="fooType"> <xsd:sequence> <xsd:element ref="tns:bar"/> <xsd:element ref="tns:baf"/> </xsd:sequence> </xsd:complexType> <xsd:element name="bar" type="xsd:string"/> <xsd:element name="baf" type="xsd:integer"/> </xsd:schema> </types> <message name="BarMsg"> <part name="BarAccessor" type="foo:fooType"/> </message> <portType name="BarPortType"> <operation name="BarOperation"> <input message="bar:BarMsg"/> </operation> </portType> <binding name="BarSOAPBinding" type="bar:BarPortTyp e"> <soapbind:binding transport="http://schemas.xmlsoap.org/soap/http /" style="rpc"/> <operation name="BarOperation"> <input message="bar:BarMsg"> <soapbind:body use="literal" namespace="http://example.org/bar/"/> </input> </operation> </binding> <service name="serviceName"> <port name="BarSOAPPort" binding="bar:BarSOAPBind ing"> <soapbind:address location="http://example.org/ myBarSOAPPort"/> </port> </service> </definitions>

The resulting SOAP message for BarOperation is: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soa p/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc e" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:foo="http://example.org/foo/"> <s:Header/> <s:Body> <m:BarOperation xmlns:m="http://example.org/b ar/"> <BarAccessor>

Page 70

<foo:bar>String</foo:bar> <foo:baf>0</foo:baf> </BarAccessor> </m:BarOperation> </s:Body> </s:Envelope>

5.6.22 Required Headers

WSDL 1.1 does not clearly specify whether all soapbind:header s specified on the wsdl:input or wsdl:output elements of a wsdl:operation element in the SOAP binding section of a WSDL description must be included in the resultant SOAP messages when they are transmitted. The Profile makes all such headers mandatory, as there is no way in WSDL 1.1 to mark a header optional.

R2738 A MESSAGE MUST include all soapbind:headers specified on a wsdl:input or wsdl:output of a wsdl:operation of a wsdl:binding that describes it.

5.6.23 Allowing Undescribed Headers

Headers are SOAP's extensibility mechanism. Headers that are not defined in the WSDL description may need to be included in the SOAP messages for various reasons.

R2739 A MESSAGE MAY contain SOAP header blocks that are not described in the wsdl:binding that describes it.

R2753 A MESSAGE containing SOAP header blocks that are not described in the appropriate wsdl:binding MAY have the mustUnderstand attribute on such SOAP header blocks set to '1'.

5.6.24 Ordering Headers

There is no correlation between the order of soapbind:header s in the description and the order of SOAP header blocks in the message. Similarly, more than one instance of each specified SOAP header block may occur in the message.

R2751 The order of soapbind:header elements in soapbind:binding sections of a DESCRIPTION MUST be considered independent of the order of SOAP header blocks in the message.

R2752 A MESSAGE MAY contain more than one instance of each SOAP header block for each soapbind:header element in the appropriate child of soapbind:binding in the corresponding description.

Page 71

5.6.25 Describing SOAPAction

Interoperability testing has demonstrated that requiring the SOAPAction HTTP header field-value to be quoted increases interoperability of implementations. Even though HTTP allows for header field-values to be unquoted, some implementations require that the value be quoted.

The SOAPAction header is purely a hint to processors. All vital information regarding the intent of a message is carried in the Envelope.

R2744 A HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation, if present in the corresponding WSDL description.

R2745 A HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted empty string value, if in the corresponding WSDL description, the soapAction of soapbind:operation is either not present, or present with an empty string as its value.

See also R1119 and related requirements for more discussion of SOAPAction. For example, CORRECT:




SOAPAction: "foo"

CORRECT:



or



SOAPAction: ""

5.6.26 SOAP Binding Extensions

The wsdl:required attribute has been widely misunderstood and used by WSDL authors sometimes to incorrectly indicate the optionality of soapbind:header s. The wsdl:required attribute, as specified in WSDL1.1, is an extensibility

Page 72

mechanism aimed at WSDL processors. It allows new WSDL extension elements to be introduced in a graceful manner. The intent of wsdl:required is to signal to the WSDL processor whether the extension element needs to be recognized and understood by the WSDL processor in order that the WSDL description be correctly processed. It is not meant to signal conditionality or optionality of some construct that is included in the messages. For example, a wsdl:required attribute with the value "false" on a soapbind:header element must not be interpreted to signal to the WSDL processor that the described SOAP header block is conditional or optional in the messages generated from the WSDL description. It is meant to be interpreted as "in order to send a message to the endpoint that includes in its description the soapbind:header element, the WSDL processor MUST understand the semantic implied by the soapbind:header element."

The default value for the wsdl:required attribute for WSDL 1.1 SOAP Binding extension elements is "false". Most WSDL descriptions in practice do not specify the wsdl:required attribute on the SOAP Binding extension elements, which could be interpreted by WSDL processors to mean that the extension elements may be ignored. The Profile requires that all WSDL SOAP 1.1 extensions be understood and processed by the consumer, irrespective of the presence or the value of the wsdl:required attribute on an extension element.

R2747 A CONSUMER MUST understand and process all WSDL 1.1 SOAP Binding extension elements, irrespective of the presence or absence of the wsdl:required attribute on an extension element; and irrespective of the value of the wsdl:required attribute, when present.

R2748 A CONSUMER MUST NOT interpret the presence of the wsdl:required attribute on a soapbind extension element with a value of "false" to mean the extension element is optional in the messages generated from the WSDL description.

5.7 Use of XML Schema


XML Schema Part 1: Structures


WSDL 1.1 uses XML Schema as one of its type systems. The Profile mandates the use of XML Schema as the type system for WSDL descriptions of Web Services.

R2800 A DESCRIPTION MAY use any construct from XML Schema 1.0.

Page 73

R2801 A DESCRIPTION MUST use XML Schema 1.0 Recommendation as the basis of user defined datatypes and structures.

6. Service Publication and Discovery

When publication or discovery of Web services is required, UDDI is the mechanism the Profile has adopted to describe Web service providers and the Web services they provide. Business, intended use, and Web service type descriptions are made in UDDI terms; detailed technical descriptions are made in WSDL terms. Where the two specifications define overlapping descriptive data and both forms of description are used, the Profile specifies that the descriptions must not conflict.

Registration of Web service instances in UDDI registries is optional. By no means do all usage scenarios require the kind of metadata and discovery UDDI provides, but where such capability is needed, UDDI is the sanctioned mechanism.

Note that the Web services that constitute UDDI V2 are not fully conformant with the Profile 1.0 because they do not accept messages encoded in both UTF-8 and UTF-16 as required by the Profile. (They accept UTF-8 only.) That there should be such a discrepancy is hardly surprising given that UDDI V2 was designed and, in many cases, implemented before the Profile was developed. UDDI's designers are aware of UDDI V2's nonconformance and will take it into consideration in their future work.


UDDI Version 2.04 API Specification, Dated 19 July 2002

UDDI Version 2.03 Data Structure Reference, Dated 19 July 2002

UDDI Version 2 XML Schema

6.1 bindingTemplates


UDDI Version 2.03 Data Structure Reference, Section 7

UDDI represents Web service instances as uddi:bindingTemplate elements. The uddi:bindingTemplate plays a role that is the rough analog of the wsdl:port , but provides options that are not expressible in WSDL. To keep the WSDL description of an instance and its UDDI description consistent, the Profile places the following constraints on how uddi:bindingTemplate elements may be constructed.

Page 74

WSDL's soapbind:address element requires the network address of the instance to be directly specified. In contrast, UDDI V2 provides two alternatives for specifying the network address of instances it represents. One, the uddi:accessPoint , mirrors the WSDL mechanism by directly specifying the address. The other, the uddi:hostingRedirector , provides a Web service-based indirection mechanism for resolving the address, and is inconsistent with the WSDL mechanism.

R3100 REGDATA of type uddi:bindingTemplate representing a conformant INSTANCE MUST contain the uddi:accessPoint element.

For example, INCORRECT: <bindingTemplate bindingKey="..."> <description xml:lang="EN">BarSOAPPort</descript ion> <hostingRedirector bindingKey="..."/> <tModelInstanceDetails> ... </tModelInstanceDetails> </bindingTemplate> CORRECT: <bindingTemplate bindingKey="..."> <description xml:lang="EN">BarSOAPPort</descript ion> <accessPoint>http://example.org/myBarSOAPPort</a ccessPoint> <tModelInstanceDetails> ... </tModelInstanceDetails> </bindingTemplate>

6.2 tModels



UDDI represents Web service types as uddi:tModel elements. (See UDDI Data Structures section 8.1.1.) These may, but need not, point (using a URI) to the document that contains the actual description. Further, UDDI is agnostic with respect to the mechanisms used to describe Web service types. The Profile cannot be agnostic about this because interoperation is very much complicated if Web service types do not have descriptions or if the descriptions can take arbitrary forms.

The UDDI API Specification, appendix I.1.2.1.1 allows but does not require uddi:tModel elements that use WSDL to describe the Web service type they represent to state that they use WSDL as the description language. Not doing so leads to interoperability problems because it is then ambiguous what description language is being used.

Page 75

Therefore the Profile places the following constraints on how uddi:tModel elements that describe Web service types may be constructed:

The Profile chooses WSDL as the description language because it is by far the most widely used such language.

R3002 REGDATA of type uddi:tModel representing a conformant Web service type MUST use WSDL as the description language.

To specify that conformant Web service types use WSDL, the Profile adopts the UDDI categorization for making this assertion.

R3003 REGDATA of type uddi:tModel representing a conformant Web service type MUST be categorized using the uddi:types taxonomy and a categorization of "wsdlSpec".

For the uddi:overviewURL in a uddi:tModel to resolve to a wsdl:binding , the Profile must adopt a convention for distinguishing among multiple wsdl:binding s in a WSDL document. The UDDI Best Practice for Using WSDL in a UDDI Registry specifies the most widely recognized such convention.

R3010 REGDATA of type uddi:tModel representing a conformant Web service type MUST follow V1.08 of the UDDI Best Practice for Using WSDL in a UDDI Registry.

It would be inconsistent if the wsdl:binding that is referenced by the uddi:tModel does not conform to the Profile.

R3011 The wsdl:binding that is referenced by REGDATA of type uddi:tModel MUST itself conform to the Profile.

7. Security

As is true of all network-oriented information technologies, the subject of security is a crucial one for Web services. For Web services, as for other information technologies, security consists of understanding the potential threats an attacker may mount and applying operational, physical, and technological countermeasures to reduce the risk of a successful attack to an acceptable level. Because an "acceptable level of risk" varies hugely depending on the application, and because costs of implementing countermeasures is also highly variable, there can be no universal "right answer" for securing Web services. Choosing the absolutely correct balance of countermeasures and acceptable risk can only be done on a case by case basis.

That said, there are common patterns of countermeasures that experience shows reduce the risks to acceptable levels for many Web services. The Profile adopts, but does not mandate use of, the most widely used of these: HTTP secured with either TLS 1.0 or SSL 3.0 (HTTPS). That is, conformant Web

Page 76

services may use HTTPS; they may also use other countermeasure technologies or none at all.

HTTPS is widely regarded as a mature standard for encrypted transport connections to provide a basic level of confidentiality. HTTPS thus forms the first and simplest means of achieving some basic security features that are required by many real-world Web service applications. HTTPS may also be used to provide client authentication through the use of client-side certificates.


RFC2818: HTTP Over TLS

RFC2246: The TLS Protocol Version 1.0 Extensibility points:

TLS Cyphersuite - TLS allows for the use of arbitrary encryption algorithms.

TLS Extensions - TLS allows for extensions during the handshake phase.

The SSL Protocol Version 3.0 Extensibility points:

SSL Cyphersuite - SSL allows for the use of arbitrary encryption algorithms.

RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile Extensibility points:

Certificate Authority - The choice of the Certificate Authority is a private agreement between parties.

Certificate Extensions - X509 allows for arbitrary certificate extensions.

7.1 Use of HTTPS

HTTPS is such a useful, widely understood basic security mechanism that the Profile needs to allow it.

R5000 An INSTANCE MAY require the use of HTTPS.

R5001 If an INSTANCE requires the use of HTTPS, the location attribute of the soapbind:address element in its wsdl:port description MUST be a URI whose scheme is "https"; otherwise it MUST be a URI whose scheme is "http".

Simple HTTPS provides authentication of the Web service instance by the consumer but not authentication of the consumer by the instance. For many

Page 77

instances this leaves the risk too high to permit interoperation. Including the mutual authentication facility of HTTPS in the Profile permits instances to use the countermeasure of authenticating the consumer. In cases in which authentication of the instance by the consumer is insufficient, this often reduces the risk sufficiently to permit interoperation.

R5010 An INSTANCE MAY require the use of HTTPS with mutual authentication.

Appendix I: Referenced Specifications

The following specifications' requirements are incorporated into the Profile by reference, except where superseded by the Profile:

Simple Object Access Protocol (SOAP) 1.1


RFC2616: Hypertext Transfer Protocol -- HTTP/1.1


Web Services Description Language (WSDL) 1.1







RFC2246: The TLS Protocol Version 1.0

The SSL Protocol Version 3.0

RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile

Appendix II: Extensibility Points

This section identifies extensibility points, as defined in "Scope of the Profile," for the Profile's component specifications.

These mechanisms are out of the scope of the Profile; their use may affect interoperability, and may require private agreement between the parties to a Web service.

In Simple Object Access Protocol (SOAP) 1.1:

Page 78

Header blocks - Header blocks are the fundamental extensibility mechanism in SOAP.

Processing order - The order of processing of a SOAP message's components (e.g., headers) is unspecified, and therefore may need to be negotiated out-of-band.

Use of intermediaries - SOAP Intermediaries is an underspecified mechanism in SOAP 1.1, and their use may require out-of-band negotiation. Their use may also necessitate careful consideration of where Profile conformance is measured.

soap:actor values - The value of the soap:actor attribute is a private agreement between the parties to a Web service.

Fault details - the contents of a Fault's detail element are not prescribed by SOAP 1.1.

In RFC2616: Hypertext Transfer Protocol -- HTTP/1.1:

HTTP Authentication - HTTP authentication allows for extension schemes, arbitrary digest hash algorithms and parameters.

Unspecified Header Fields - HTTP allows arbitrary headers to occur in messages.

Expect-extensions - The Expect/Continue mechanism in HTTP allows for expect-extensions.

Content-Encoding - The set of content-codings allowed by HTTP is open-ended.

Transfer-Encoding - The set of transfer-encodings allowed by HTTP is open-ended.

Upgrade - HTTP allows a connection to change to an arbitrary protocol using the Upgrade header.

In Web Services Description Language (WSDL) 1.1:

WSDL extensions - WSDL allows extension elements in certain places; use of such extensions requires out-of-band negotiation.

Relative URIs - WSDL does not adequately specify the use of relative URIs; their use may require further coordination; see XML Base for more information.

Validation mode - whether the parser used to read WSDL and XML Schema documents performs DTD validation or not.

Page 79

Fetching of external resources - whether the parser used to read WSDL and XML Schema documents fetches external entities and DTDs.

In XML Schema Part 1: Structures:

Schema annotations - XML Schema allows for annotations, which may be used to convey additional information about data structures.

In RFC2246: The TLS Protocol Version 1.0:

TLS Cyphersuite - TLS allows for the use of arbitrary encryption algorithms.

TLS Extensions - TLS allows for extensions during the handshake phase.

In The SSL Protocol Version 3.0:

SSL Cyphersuite - SSL allows for the use of arbitrary encryption algorithms.

In RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile:

Certificate Authority - The choice of the Certificate Authority is a private agreement between parties.

Certificate Extensions - X509 allows for arbitrary certificate extensions.

Appendix III: Acknowledgements

This Profile is the work of the WS-I Basic Profile Working Group, whose members have included:

Mark Allerton (Crystal Decisions Corporation), George Arriola (Talking Blocks, Inc.), Keith Ballinger (Microsoft Corporation), Ilya Beyer (KANA), Rich Bonneau (IONA Technologies), Don Box (Microsoft Corporation), Andrew Brown (Verisign), Heidi Buelow (Quovadx), David Burdett (Commerce One, Inc.), Luis Felipe Cabrera (Microsoft Corporation), Maud Cahuzac (France Telecom), Bhaskar Chakrabarti (United Airlines), Chia Chao (IONA Technologies), Martin Chapman (Oracle Corporation), Richard Chin (Avinon), Roberto Chinnici (Sun Microsystems), Sergio Compean (Avanade, Inc.), Tim Cooke (Onyx Software), Ugo Corda (SeeBeyond Tech), Paul Cotton (Microsoft Corporation), Joseph Curran (Accenture), Ayse Dilber (AT&T), Dave Ehnebuske (IBM), Mark Ericson (Mindreef Inc.), Colleen Evans (Sonic Software), Tim Ewald (Microsoft Corporation), Chuck Fay (FileNet Corporation), Chris Ferris (IBM), Daniel Foody (Actional Corporation), Toru Fujii (NTT), Satoru Fujita (NEC Corporation), Shishir Garg (France Telecom), Yaron Goland (BEA Systems), Hans Granqvist (Verisign), Martin Gudgin (Microsoft Corporation), Marc Hadley (Sun Microsystems), Bob Hall (Unisys Corporation), Scott Hanselman (Corillian), Muir Harding (Autodesk, Inc.), Loren Hart (Verisign), Harry Holstrom (Accenture), Larry Hsiung (Quovadx), Hemant Jain (Tata Consultancy), Steve Jenisch (SAS Institute), Erik Johnson (Epicor Software Corporation), Bill Jones (Oracle Corporation), Menno Jonkers (Tryllian BV), Anish Karmarkar (Oracle

Page 80

Corporation), Takahiro Kawamura (Toshiba), Bhushan Khanal (WRQ, Inc.), Sunil Kunisetty (Oracle Corporation), Canyang Kevin Liu (SAP AG), Jonathan Marsh (Microsoft Corporation), David Meyer (Plumtree Software, Inc.), Jeff Mischkinsky (Oracle Corporation), Tom Moog (Sarvega Inc.), Gilles Mousseau (Hummingbird Ltd.), Richard Nikula (BMC Software, Inc.), Eisaku Nishiyama (Hitachi, Ltd.), Mark Nottingham (BEA Systems), David Orchard (BEA Systems), Jesse Pangburn (Quovadx), TJ Pannu (ContentGuard, Inc.), Eduardo Pelegri-Llopart (Sun Microsystems), Vijay Rajan (Novell), Eric Rajkovic (Oracle Corporation), Graeme Riddell (Bowstreet), Claus von Riegen (SAP AG), Tom Rutt (Fujitsu Limited), Roger Sanborn (Crystal Decisions Corporation), Krishna Sankar (Cisco Systems, Inc.), Don Schricker (Micro Focus), Dave Seidel (Mindreef Inc.), Akira Shimaya (NTT), Yasser Shohoud (Microsoft Corporation), David Smiley (Mercator Software, Inc.), Seumas Soltysik (IONA Technologies), Joseph Stanko (Plumtree Software, Inc.), Keith Stobie (Microsoft Corporation), Yasuo Takemoto (NTT), Nobuyoshi Tanaka (NEC Corporation), Jorgen Thelin (Cape Clear Software), Sameer Vaidya (Talking Blocks, Inc.), William Vambenepe (Hewlett-Packard), Rick Weil (Eastman Kodak Company), Scott Werden (WRQ, Inc.), Ajamu Wesley (IBM), Shannon Wheatley (Kinzan, Inc.), Ian White (Micro Focus), Sue Worthman (Tryllian BV), Prasad Yendluri (webMethods Inc.).

=

Page 81

Basic Profile Version 1.1

Final Material

2004-08-24 This version:

http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html Latest version:

http://www.ws-i.org/Profiles/BasicProfile-1.1.html Errata for this Version:

Editors:

Keith Ballinger, Microsoft (1.0) David Ehnebuske, IBM (1.0) Christopher Ferris, IBM Martin Gudgin, Microsoft (1.0) Canyang Kevin Liu, SAP Mark Nottingham, BEA Systems Prasad Yendluri, webMethods

Administrative contact: [email protected]

Copyright © 2002-2004 by The Web Services-Interoperability Organization (WS-I) and Certain of its Members. All Rights Reserved.

Abstract

This document defines the WS-I Basic Profile 1.1, consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability

Status of this Document

This is a final specification. Please refer to the errata, which may include normative corrections to it.

Notice

The material contained herein is not a license, either expressly or impliedly, to any intellectual property owned or controlled by any of the authors or developers of this material or WS-I. The material contained herein is provided on an "AS IS" basis and to the maximum extent permitted by applicable law, this material is provided AS IS AND WITH ALL FAULTS, and the authors and developers of this material and WS-I hereby disclaim all other warranties and conditions, either

Page 82

express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses, and of lack of negligence. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THIS MATERIAL.

IN NO EVENT WILL ANY AUTHOR OR DEVELOPER OF THIS MATERIAL OR WS-I BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS MATERIAL, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

Feedback

If there are areas in this specification that could be clearer, or if errors or omissions are identified, WS-I would like to be notified in order to provide the best possible interoperability guidance.

By sending email, or otherwise communicating with WS-I, you (on behalf of yourself if you are an individual, and your company if you are providing Feedback on behalf of the company) will be deemed to have granted to WS-I, the members of WS-I, and other parties that have access to your Feedback, a non-exclusive, non-transferable, worldwide, perpetual, irrevocable, royalty-free license to use, disclose, copy, license, modify, sublicense or otherwise distribute and exploit in any manner whatsoever the Feedback you provide regarding the work. You acknowledge that you have no expectation of confidentiality with respect to any Feedback you provide. You represent and warrant that you have rights to provide this Feedback, and if you are providing Feedback on behalf of a company, you represent and warrant that you have the rights to provide Feedback on behalf of your company. You also acknowledge that WS-I is not required to review, discuss, use, consider or in any way incorporate your Feedback into future versions of its work. If WS-I does incorporate some or all of your Feedback in a future version of the work, it may, but is not obligated to include your name (or, if you are identified as acting on behalf of your company, the name of your company) on a list of contributors to the work. If the foregoing is not acceptable to you and any company on whose behalf you are acting, please do not provide any Feedback.

Feedback on this document should be directed to [email protected].

Page 83

Table of Contents

1. Introduction 1.1. Relationships to Other Profiles 1.2. Changes from Basic Profile Version 1.0 1.3. Guiding Principles 1.4. Notational Conventions 1.5. Profile Identification and Versioning 2. Profile Conformance 2.1. Conformance Requirements 2.2. Conformance Targets 2.3. Conformance Scope 2.4. Claiming Conformance 3. Messaging 3.1. SOAP Envelopes 3.1.1. SOAP Envelope Structure 3.1.2. SOAP Envelope Namespace 3.1.3. SOAP Body Namespace Qualification 3.1.4. Disallowed Constructs 3.1.5. SOAP Trailers 3.1.6. SOAP encodingStyle Attribute 3.1.7. SOAP mustUnderstand Attribute 3.1.8. xsi:type Attributes 3.1.9. SOAP1.1 attributes on SOAP1.1 elements 3.2. SOAP Processing Model 3.2.1. Mandatory Headers 3.2.2. Generating mustUnderstand Faults 3.2.3. SOAP Fault Processing 3.3. SOAP Faults 3.3.1. Identifying SOAP Faults 3.3.2. SOAP Fault Structure 3.3.3. SOAP Fault Namespace Qualification 3.3.4. SOAP Fault Extensibility 3.3.5. SOAP Fault Language 3.3.6. SOAP Custom Fault Codes 3.4. Use of SOAP in HTTP 3.4.1. HTTP Protocol Binding 3.4.2. HTTP Methods and Extensions 3.4.3. SOAPAction HTTP Header 3.4.4. HTTP Success Status Codes 3.4.5. HTTP Redirect Status Codes 3.4.6. HTTP Client Error Status Codes 3.4.7. HTTP Server Error Status Codes 3.4.8. HTTP Cookies 4. Service Description 4.1. Required Description 4.2. Document Structure

Page 84

4.2.1. WSDL Schema Definitions 4.2.2. WSDL and Schema Import 4.2.3. WSDL Import location Attribute Structure 4.2.4. WSDL Import location Attribute Semantics 4.2.5. Placement of WSDL import Elements 4.2.6. XML Version Requirements 4.2.7. XML Namespace declarations 4.2.8. WSDL and the Unicode BOM 4.2.9. Acceptable WSDL Character Encodings 4.2.10. Namespace Coercion 4.2.11. WSDL documentation Element 4.2.12. WSDL Extensions 4.3. Types 4.3.1. QName References 4.3.2. Schema targetNamespace Structure 4.3.3. soapenc:Array 4.3.4. WSDL and Schema Definition Target Namespaces 4.4. Messages 4.4.1. Bindings and Parts 4.4.2. Bindings and Faults 4.4.3. Declaration of part Elements 4.5. Port Types 4.5.1. Ordering of part Elements 4.5.2. Allowed Operations 4.5.3. Distinctive Operations 4.5.4. parameterOrder Attribute Construction 4.5.5. Exclusivity of type and element Attributes 4.6. Bindings 4.6.1. Use of SOAP Binding 4.7. SOAP Binding 4.7.1. Specifying the transport Attribute 4.7.2. HTTP Transport 4.7.3. Consistency of style Attribute 4.7.4. Encodings and the use Attribute 4.7.5. Multiple Bindings for portType Elements 4.7.6. Operation Signatures 4.7.7. Multiple Ports on an Endpoint 4.7.8. Child Element for Document-Literal Bindings 4.7.9. One-Way Operations 4.7.10. Namespaces for soapbind Elements 4.7.11. Consistency of portType and binding Elements 4.7.12. Describing headerfault Elements 4.7.13. Enumeration of Faults 4.7.14. Type and Name of SOAP Binding Elements 4.7.15. name Attribute on Faults 4.7.16. Omission of the use Attribute

Page 85

4.7.17. Default for use Attribute 4.7.18. Consistency of Envelopes with Descriptions 4.7.19. Response Wrappers 4.7.20. Part Accessors 4.7.21. Namespaces for Children of Part Accessors 4.7.22. Required Headers 4.7.23. Allowing Undescribed Headers 4.7.24. Ordering Headers 4.7.25. Describing SOAPAction 4.7.26. SOAP Binding Extensions 4.8. Use of XML Schema 5. Service Publication and Discovery 5.1. bindingTemplates 5.2. tModels 6. Security 6.1. Use of HTTPS Appendix A: Referenced Specifications Appendix B: Extensibility Points Appendix C: Defined Terms Appendix D: Acknowledgements

1. Introduction

This document defines the WS-I Basic Profile 1.1 (hereafter, "Profile"), consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability.

Section 1 introduces the Profile, and explains its relationships to other profiles.

Section 2, "Profile Conformance," explains what it means to be conformant to the Profile.

Each subsequent section addresses a component of the Profile, and consists of two parts; an overview detailing the component specifications and their extensibility points, followed by subsections that address individual parts of the component specifications. Note that there is no relationship between the section numbers in this document and those in the referenced specifications.

1.1 Relationships to Other Profiles

This Profile is derived from the Basic Profile 1.0 by incorporating any errata to date and separating out those requirements related to the serialization of envelopes and their representation in messages. Such requirements are now part of the Simple SOAP Binding Profile 1.0, identified with a separate conformance claim. This separation is made to facilitate composability of Basic Profile 1.1 with any profile that specifies envelope serialization, including the Simple SOAP Binding Profile 1.0 and the Attachments Profile 1.0. A combined

Page 86

claim of conformance to both the Basic Profile 1.1 and the Simple SOAP Binding Profile 1.0 is roughly equivalent to a claim of conformance to the Basic Profile 1.0 plus published errata.

This Profile, composed with the Simple SOAP Binding Profile 1.0 supercedes the Basic Profile 1.0. The Attachments Profile 1.0 adds support for SOAP with Attachments, and is intended to be used in combination with this Profile.

1.2 Changes from Basic Profile Version 1.0

This specification is derived from the Basic Profile Version 1.0, and incorporates published errata against that specification. The most notable changes are:

MESSAGE conformance target - Some requirements that had a MESSAGE conformance target in BP1.0 now use a new target, ENVELOPE. This facilitates alternate serialisations of the message, such as that described in the Attachments Profile.

SOAP Binding - Requirements relating to the SOAP binding's serialization of the message have been moved to the Simple SOAP Binding Profile to facilitate other serializations.

1.3 Guiding Principles

The Profile was developed according to a set of principles that, together, form the philosophy of the Profile, as it relates to bringing about interoperability. This section documents these guidelines.

No guarantee of interoperability It is impossible to completely guarantee the interoperability of a particular service. However, the Profile does address the most common problems that implementation experience has revealed to date.

Application semantics Although communication of application semantics can be facilitated by the technologies that comprise the Profile, assuring the common understanding of those semantics is not addressed by it.

Testability When possible, the Profile makes statements that are testable. However, such testability is not required. Preferably, testing is achieved in a non-intrusive manner (e.g., examining artifacts "on the wire").

Strength of requirements The Profile makes strong requirements (e.g., MUST, MUST NOT) wherever feasible; if there are legitimate cases where such a requirement cannot be met, conditional requirements (e.g., SHOULD, SHOULD NOT) are used. Optional and conditional requirements introduce ambiguity and mismatches between implementations.

Restriction vs. relaxation

Page 87

When amplifying the requirements of referenced specifications, the Profile may restrict them, but does not relax them (e.g., change a MUST to a MAY).

Multiple mechanisms If a referenced specification allows multiple mechanisms to be used interchangeably, the Profile selects those that are well-understood, widely implemented and useful. Extraneous or underspecified mechanisms and extensions introduce complexity and therefore reduce interoperability.

Future compatibility When possible, the Profile aligns its requirements with in-progress revisions to the specifications it references. This aids implementers by enabling a graceful transition, and assures that WS-I does not 'fork' from these efforts. When the Profile cannot address an issue in a specification it references, this information is communicated to the appropriate body to assure its consideration.

Compatibility with deployed services Backwards compatibility with deployed Web services is not a goal for the Profile, but due consideration is given to it; the Profile does not introduce a change to the requirements of a referenced specification unless doing so addresses specific interoperability issues.

Focus on interoperability Although there are potentially a number of inconsistencies and design flaws in the referenced specifications, the Profile only addresses those that affect interoperability.

Conformance targets Where possible, the Profile places requirements on artifacts (e.g., WSDL descriptions, SOAP messages) rather than the producing or consuming software's behaviors or roles. Artifacts are concrete, making them easier to verify and therefore making conformance easier to understand and less error-prone.

Lower-layer interoperability The Profile speaks to interoperability at the application layer; it assumes that interoperability of lower-layer protocols (e.g., TCP, IP, Ethernet) is adequate and well-understood. Similarly, statements about application-layer substrate protocols (e.g., SSL/TLS, HTTP) are only made when there is an issue affecting Web services specifically; WS-I does not attempt to assure the interoperability of these protocols as a whole. This assures that WS-I's expertise in and focus on Web services standards is used effectively.

1.4 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Page 88

Normative statements of requirements in the Profile (i.e., those impacting conformance, as outlined in "Conformance Requirements") are presented in the following manner:

RnnnnStatement text here.

where "nnnn" is replaced by a number that is unique among the requirements in the Profile, thereby forming a unique requirement identifier.

Requirement identifiers can be considered to be namespace qualified, in such a way as to be compatible with QNames from Namespaces in XML. If there is no explicit namespace prefix on a requirement's identifier (e.g., "R9999" as opposed to "bp10:R9999"), it should be interpreted as being in the namespace identified by the conformance URI of the document section it occurs in. If it is qualified, the prefix should be interpreted according to the namespace mappings in effect, as documented below.

Some requirements clarify the referenced specification(s), but do not place additional constraints upon implementations. For convenience, clarifications are annotated in the following manner: C

Some requirements are derived from ongoing standardization work on the referenced specification(s). For convenience, such forward-derived statements are annotated in the following manner: xxxx, where "xxxx" is an identifier for the specification (e.g., "WSDL20" for WSDL Version 2.0). Note that because such work was not complete when this document was publiished, the specification that the requirement is derived from may change; this information is included only as a convenience to implementers.

Extensibility points in underlying specifications (see "Conformance Scope") are presented in a similar manner:

EnnnnExtensibility Point Name - Description

where "nnnn" is replaced by a number that is unique among the extensibility points in the Profile. As with requirement statements, extensibility statements can be considered namespace-qualified.

This specification uses a number of namespace prefixes throughout; their associated URIs are listed below. Note that the choice of any namespace prefix is arbitrary and not semantically significant.

soap - "http://schemas.xmlsoap.org/soap/envelope/"

xsi - "http://www.w3.org/2001/XMLSchema-instance"

xsd - "http://www.w3.org/2001/XMLSchema"

soapenc - "http://schemas.xmlsoap.org/soap/encoding/"

Page 89

wsdl - "http://schemas.xmlsoap.org/wsdl/"

soapbind - "http://schemas.xmlsoap.org/wsdl/soap/"

uddi - "urn:uddi-org:api_v2"

1.5 Profile Identification and Versioning

This document is identified by a name (in this case, Basic Profile) and a version number (here, 1.1). Together, they identify a particular profile instance.

Version numbers are composed of a major and minor portion, in the form "major.minor". They can be used to determine the precedence of a profile instance; a higher version number (considering both the major and minor components) indicates that an instance is more recent, and therefore supersedes earlier instances.

Instances of profiles with the same name (e.g., "Example Profile 1.1" and "Example Profile 5.0") address interoperability problems in the same general scope (although some developments may require the exact scope of a profile to change between instances).

One can also use this information to determine whether two instances of a profile are backwards-compatible; that is, whether one can assume that conformance to an earlier profile instance implies conformance to a later one. Profile instances with the same name and major version number (e.g., "Example Profile 1.0" and "Example Profile 1.1") MAY be considered compatible. Note that this does not imply anything about compatibility in the other direction; that is, one cannot assume that conformance with a later profile instance implies conformance to an earlier one.

2 Profile Conformance

Conformance to the Profile is defined by adherence to the set of requirements defined for a specific target, within the scope of the Profile. This section explains these terms and describes how conformance is defined and used.

2.1 Conformance Requirements

Requirements state the criteria for conformance to the Profile. They typically refer to an existing specification and embody refinements, amplifications, interpretations and clarifications to it in order to improve interoperability. All requirements in the Profile are considered normative, and those in the specifications it references that are in-scope (see "Conformance Scope") should likewise be considered normative. When requirements in the Profile and its referenced specifications contradict each other, the Profile's requirements take precedence for purposes of Profile conformance.

Page 90

Requirement levels, using RFC2119 language (e.g., MUST, MAY, SHOULD) indicate the nature of the requirement and its impact on conformance. Each requirement is individually identified (e.g., R9999) for convenience.

For example;

R9999 WIDGETs SHOULD be round in shape.

This requirement is identified by "R9999", applies to the target WIDGET (see below), and places a conditional requirement upon widgets; i.e., although this requirement must be met to maintain conformance in most cases, there are some situations where there may be valid reasons for it not being met (which are explained in the requirement itself, or in its accompanying text).

Each requirement statement contains exactly one requirement level keyword (e.g., "MUST") and one conformance target keyword (e.g., "MESSAGE"). Additional text may be included to illuminate a requirement or group of requirements (e.g., rationale and examples); however, prose surrounding requirement statements must not be considered in determining conformance.

Definitions of terms in the Profile are considered authoritative for the purposes of determining conformance.

None of the requirements in the Profile, regardless of their conformance level, should be interpreted as limiting the ability of an otherwise conforming implementation to apply security countermeasures in response to a real or perceived threat (e.g., a denial of service attack).

2.2 Conformance Targets

Conformance targets identify what artifacts (e.g., SOAP message, WSDL description, UDDI registry data) or parties (e.g., SOAP processor, end user) requirements apply to.

This allows for the definition of conformance in different contexts, to assure unambiguous interpretation of the applicability of requirements, and to allow conformance testing of artifacts (e.g., SOAP messages and WSDL descriptions) and the behavior of various parties to a Web service (e.g., clients and service instances).

Requirements' conformance targets are physical artifacts wherever possible, to simplify testing and avoid ambiguity.

The following conformance targets are used in the Profile:

MESSAGE - protocol elements that transport the ENVELOPE (e.g., SOAP/HTTP messages)

ENVELOPE - the serialization of the soap:Envelope element and its content

Page 91

DESCRIPTION - descriptions of types, messages, interfaces and their concrete protocol and data format bindings, and the network access points associated with Web services (e.g., WSDL descriptions) (from Basic Profile 1.0)

INSTANCE - software that implements a wsdl:port or a uddi:bindingTemplate (from Basic Profile 1.0)

CONSUMER - software that invokes an INSTANCE (from Basic Profile 1.0)

SENDER - software that generates a message according to the protocol(s) associated with it (from Basic Profile 1.0)

RECEIVER - software that consumes a message according to the protocol(s) associated with it (e.g., SOAP processors) (from Basic Profile 1.0)

REGDATA - registry elements that are involved in the registration and discovery of Web services (e.g. UDDI tModels) (from Basic Profile 1.0)

2.3 Conformance Scope

The scope of the Profile delineates the technologies that it addresses; in other words, the Profile only attempts to improve interoperability within its own scope. Generally, the Profile's scope is bounded by the specifications referenced by it.

The Profile's scope is further refined by extensibility points. Referenced specifications often provide extension mechanisms and unspecified or open-ended configuration parameters; when identified in the Profile as an extensibility point, such a mechanism or parameter is outside the scope of the Profile, and its use or non-use is not relevant to conformance.

Note that the Profile may still place requirements on the use of an extensibility point. Also, specific uses of extensibility points may be further restricted by other profiles, to improve interoperability when used in conjunction with the Profile.

Because the use of extensibility points may impair interoperability, their use should be negotiated or documented in some fashion by the parties to a Web service; for example, this could take the form of an out-of-band agreement.

The Profile's scope is defined by the referenced specifications in Appendix A, as refined by the extensibility points in Appendix B.

2.4 Claiming Conformance

Claims of conformance to the Profile can be made using the following mechanisms, as described in Conformance Claim Attachment Mechanisms, when the applicable Profile requirements associated with the listed targets have been met:

Page 92

The CCAM URI may change before final publication.

WSDL 1.1 Claim Attachment Mechanism for Web Service s Instances - MESSAGE DESCRIPTION INSTANCE RECEIVER

WSDL 1.1 Claim Attachment Mechanism for Description Constructs - DESCRIPTION

UDDI Claim Attachment Mechanism for Web Services In stances - MESSAGE DESCRIPTION INSTANCE RECEIVER

UDDI Claim Attachment Mechanism for Web Services Re gistrations - REGDATA

The conformance claim URI for this Profile is "http://ws-i.org/profiles/basic/1.1".

3. Messaging


Simple Object Access Protocol (SOAP) 1.1 Extensibility points:

E0001 - Header blocks - Header blocks are the fundamental extensibility mechanism in SOAP.

E0002 - Processing order - The order of processing of a SOAP envelope's components (e.g., headers) is unspecified, and therefore may need to be negotiated out-of-band.

E0003 - Use of intermediaries - SOAP Intermediaries is an underspecified mechanism in SOAP 1.1, and their use may require out-of-band negotiation. Their use may also necessitate careful consideration of where Profile conformance is measured.

E0004 - soap:actor values - Values of the soap:actor attribute, other than the special uri 'http://schemas.xmlsoap.org/soap/actor/next' , represent a private agreement between parties of the web service.

E0005 - Fault details - the contents of a Fault's detail element are not prescribed by SOAP 1.1.

E0006 - Envelope serialization - The Profile does not constrain some aspects of how the envelope is serialized into the message.

RFC2616: Hypertext Transfer Protocol -- HTTP/1.1 Extensibility points:

Page 93

E0007 - HTTP Authentication - HTTP authentication allows for extension schemes, arbitrary digest hash algorithms and parameters.

E0008 - Unspecified Header Fields - HTTP allows arbitrary headers to occur in messages.

E0009 - Expect-extensions - The Expect/Continue mechanism in HTTP allows for expect-extensions.

E0010 - Content-Encoding - The set of content-codings allowed by HTTP is open-ended and any besides 'gzip', 'compress', or 'deflate' are an extensibility point.

E0011 - Transfer-Encoding - The set of transfer-encodings allowed by HTTP is open-ended.

E0012 - Upgrade - HTTP allows a connection to change to an arbitrary protocol using the Upgrade header.

E0024 - Namespace Attributes - Namespace attributes on soap:Envelope and soap:Header elements

E0025 - Attributes on soap:Body elements - Neither namespaced nor local attributes are constrained by SOAP 1.1.


3.1 SOAP Envelopes

The following specifications (or sections thereof) are referred to in this section of the Profile:

SOAP 1.1, Section 4

SOAP 1.1 defines a structure for composing messages, the envelope. The Profile mandates the use of that structure, and places the following constraints on its use:

3.1.1 SOAP Envelope Structure

R9980 An ENVELOPE MUST conform to the structure specified in SOAP 1.1 Section 4, "SOAP Envelope" (subject to amendment by the Profile).

3.1.2 SOAP Envelope Namespace

SOAP 1.1 states that an envelope with a document element whose namespace name is other than "http://schemas.xmlsoap.org/soap/envelope/" should be discarded. The Profile requires that a fault be generated instead, to assure unambiguous operation.

Page 94

R1015 A RECEIVER MUST generate a fault if they encounter an envelope whose document element is not soap:Envelope.

3.1.3 SOAP Body Namespace Qualification

The use of unqualified element names may cause naming conflicts, therefore qualified names must be used for the children of soap:Body .

R1014 The children of the soap:Body element in an ENVELOPE MUST be namespace qualified.

3.1.4 Disallowed Constructs

XML DTDs and PIs may introduce security vulnerabilities, processing overhead and semantic ambiguity when used in envelopes. As a result, certain XML constructs are disallowed by section 3 of SOAP 1.1.

Although published errata NE05 (see http://www.w3.org/XML/xml-names-19990114-errata) allows the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace" to appear, some older processors considered such a declaration to be an error. These requirements ensure that conformant artifacts have the broadest interoperability possible.

R1008 An ENVELOPE MUST NOT contain a Document Type Declaration. C

R1009 An ENVELOPE MUST NOT contain Processing Instructions. C

R1033 An ENVELOPE SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace". C

R1034 A DESCRIPTION SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace". C

3.1.5 SOAP Trailers

The interpretation of sibling elements following the soap:Body element is unclear. Therefore, such elements are disallowed.

R1011 An ENVELOPE MUST NOT have any element children of soap:Envelope following the soap:Body element.

This requirement clarifies a mismatch between the SOAP 1.1 specification and the SOAP 1.1 XML Schema. For example, INCORRECT: <soap:Envelope xmlns:soap='http://schemas.xmlsoap.o rg/soap/envelope/' >

Page 95

<soap:Body> <p:Process xmlns:p='http://example.org/Operatio ns' /> </soap:Body> <m:Data xmlns:m='http://example.org/information' > Here is some data with the message </m:Data> </soap:Envelope> CORRECT: <soap:Envelope xmlns:soap='http://schemas.xmlsoap.o rg/soap/envelope/' > <soap:Body> <p:Process xmlns:p='http://example.org/Operatio ns' > <m:Data xmlns:m='http://example.org/information' > Here is some data with the message </m:Data> </p:Process> </soap:Body> </soap:Envelope>

3.1.6 SOAP encodingStyle Attribute

The soap:encodingStyle attribute is used to indicate the use of a particular scheme in the encoding of data into XML. However, this introduces complexity, as this function can also be served by the use of XML Namespaces. As a result, the Profile prefers the use of literal, non-encoded XML.

R1005 An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any of the elements whose namespace name is "http://schemas.xmlsoap.org/soap/envelope/".

R1006 An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any element that is a child of soap:Body.

R1007 An ENVELOPE described in an rpc-literal binding MUST NOT contain soap:encodingStyle attribute on any element that is a grandchild of soap:Body.

3.1.7 SOAP mustUnderstand Attribute

The soap:mustUnderstand attribute has a restricted type of "xsd:boolean" that takes only "0" or "1". Therefore, only those two values are allowed.

R1013 An ENVELOPE containing a soap:mustUnderstand attribute MUST only use the lexical forms "0" and "1". C

3.1.8 xsi:type Attributes

In many cases, senders and receivers will share some form of type information related to the envelopes being exchanged.

R1017 A RECEIVER MUST NOT mandate the use of the xsi:type attribute in envelopes except as required in order to

Page 96

indicate a derived type (see XML Schema Part 1: Structures, Section 2.6.1).

3.1.9 SOAP1.1 attributes on SOAP1.1 elements

R1032 The soap:Envelope, soap:Header, and soap:Body elements in an ENVELOPE MUST NOT have attributes in the namespace "http://schemas.xmlsoap.org/soap/envelope/".

3.2 SOAP Processing Model


SOAP 1.1, Section 2

SOAP 1.1 defines a model for the processing of envelopes. In particular, it defines rules for the processing of header blocks and the envelope body. It also defines rules related to generation of faults. The Profile places the following constraints on the processing model:

3.2.1 Mandatory Headers

SOAP 1.1's processing model is underspecified with respect to the processing of mandatory header blocks. Mandatory header blocks are those children of the soap:Header element bearing a soap:mustUnderstand attribute with a value of "1".

R1025 A RECEIVER MUST handle envelopes in such a way that it appears that all checking of mandatory header blocks is performed before any actual processing. SOAP12

This requirement guarantees that no undesirable side effects will occur as a result of noticing a mandatory header block after processing other parts of the message.

3.2.2 Generating mustUnderstand Faults

The Profile requires that receivers generate a fault when they encounter header blocks targeted at them, that they do not understand.

R1027 A RECEIVER MUST generate a "soap:MustUnderstand" fault when an envelope contains a mandatory header block (i.e., one that has a soap:mustUnderstand attribute with the value "1") targeted at the receiver (via soap:actor) that the receiver does not understand.SOAP12

Page 97

3.2.3 SOAP Fault Processing

When a fault is generated, no further processing should be performed. In request-response exchanges, a fault message will be transmitted to the sender of the request, and some application level error will be flagged to the user.

Both SOAP and this Profile use the term 'generate' to denote the creation of a SOAP Fault. It is important to realize that generation of a Fault is distinct from its transmission, which in some cases is not required.

R1028 When a fault is generated by a RECEIVER, further processing SHOULD NOT be performed on the SOAP envelope aside from that which is necessary to rollback, or compensate for, any effects of processing the envelope prior to the generation of the fault. SOAP12

R1029 Where the normal outcome of processing a SOAP envelope would have resulted in the transmission of a SOAP response, but rather a fault is generated instead, a RECEIVER MUST transmit a fault in place of the response. SOAP12

R1030 A RECEIVER that generates a fault SHOULD notify the end user that a fault has been generated when practical, by whatever means is deemed appropriate to the circumstance. SOAP12

3.3 SOAP Faults

3.3.1 Identifying SOAP Faults

Some consumer implementations erroneously use only the HTTP status code to determine the presence of a Fault. Because there are situations where the Web infrastructure changes the HTTP status code, and for general reliability, the Profile requires that they examine the envelope. A Fault is an envelope that has a single child element of the soap:Body element, that element being a soap:Fault element.

R1107 A RECEIVER MUST interpret a SOAP message as a Fault when the soap:Body of the message has a single soap:Fault child.

3.3.2 SOAP Fault Structure

The Profile restricts the content of the soap:Fault element to those elements explicitly described in SOAP 1.1.

R1000 When an ENVELOPE is a Fault, the soap:Fault element MUST NOT have element children other than faultcode, faultstring, faultactor and detail.

Page 98

For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor> <detail>There were <b>lots</b> of elements in the message that I did not understand </detail> <m:Exception xmlns:m='http://example.org/faults/e xceptions' > <m:ExceptionType>Severe</m:ExceptionType> </m:Exception> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor> <detail> <m:msg xmlns:m='http://example.org/faults/exce ptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> <m:Exception xmlns:m='http://example.org/fault s/exceptions'> <m:ExceptionType>Severe</m:ExceptionType> </m:Exception> </detail> </soap:Fault>

3.3.3 SOAP Fault Namespace Qualification

The children of the soap:Fault element are local to that element, therefore namespace qualification is unnecessary.

R1001 When an ENVELOPE is a Fault, the element children of the soap:Fault element MUST be unqualified.

For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <soap:faultcode>soap:Client</soap:faultcode> <soap:faultstring>Invalid message format</soap:fa ultstring> <soap:faultactor>http://example.org/someactor</so ap:faultactor> <soap:detail> <m:msg xmlns:m='http://example.org/faults/exc eptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> </soap:detail> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns='' > <faultcode>soap:Client</faultcode> <faultstring>Invalid message format</faultstring> <faultactor>http://example.org/someactor</faultac tor>

Page 99

<detail> <m:msg xmlns:m='http://example.org/faults/exc eptions'> There were <b>lots</b> of elements in the message that I did not understand </m:msg> </detail> </soap:Fault>

3.3.4 SOAP Fault Extensibility

For extensibility, additional attributes are allowed to appear on the detail element and additional elements are allowed to appear as children of the detail element.

R1002 A RECEIVER MUST accept faults that have any number of elements, including zero, appearing as children of the detail element. Such children can be qualified or unqualified.

R1003 A RECEIVER MUST accept faults that have any number of qualified or unqualified attributes, including zero, appearing on the detail element. The namespace of qualified attributes can be anything other than "http://schemas.xmlsoap.org/soap/envelope/".

3.3.5 SOAP Fault Language

Faultstrings are human-readable indications of the nature of a fault. As such, they may not be in a particular language, and therefore the xml:lang attribute can be used to indicate the language of the faultstring.

Note that this requirement conflicts with the schema for SOAP appearing at its namespace URL. A schema without conflicts can be found at 'http://schemas.xmlsoap.org/soap/envelope/2004-01-21.xsd'.

R1016 A RECEIVER MUST accept faults that carry an xml:lang attribute on the faultstring element.

3.3.6 SOAP Custom Fault Codes

SOAP 1.1 allows custom fault codes to appear inside the faultcode element, through the use of the "dot" notation.

Use of this mechanism to extend the meaning of the SOAP 1.1-defined fault codes can lead to namespace collision. Therefore, its use should be avoided, as doing so may cause interoperability issues when the same names are used in the right-hand side of the "." (dot) to convey different meaning.

Instead, the Profile encourages the use of the fault codes defined in SOAP 1.1, along with additional information in the detail element to convey the nature of the fault.

Page 100

Alternatively, it is acceptable to define custom fault codes in a namespace controlled by the specifying authority.

A number of specifications have already defined custom fault codes using the "." (dot) notation. Despite this, their use in future specifications is discouraged.

R1004 When an ENVELOPE contains a faultcode element, the content of that element SHOULD be either one of the fault codes defined in SOAP 1.1 (supplying additional information if necessary in the detail element), or a Qname whose namespace is controlled by the fault's specifying authority (in that order of preference).

R1031 When an ENVELOPE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to refine the meaning of the fault.

It is recommended that applications that require custom fault codes either use the SOAP1.1 defined fault codes and supply additional information in the detail element, or that they define these codes in a namespace that is controlled by the specifying authority. For example, INCORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns:c='http://example.org/faultcodes' > <faultcode>soap:Server.ProcessingError</faultcode > <faultstring>An error occurred while processing t he message </faultstring> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' xmlns:c='http://example.org/faultcodes' > <faultcode>c:ProcessingError</faultcode> <faultstring>An error occured while processing th e message </faultstring> </soap:Fault> CORRECT: <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/ soap/envelope/' > <faultcode>soap:Server</faultcode> <faultstring>An error occured while processing th e message </faultstring> </soap:Fault>

3.4 Use of SOAP in HTTP


SOAP 1.1, Section 6

HTTP/1.1

Page 101

HTTP State Management Mechanism

SOAP 1.1 defines a single protocol binding, for HTTP. The Profile mandates the use of that binding, and places the following constraints on its use:

3.4.1 HTTP Protocol Binding

Several versions of HTTP are defined. HTTP/1.1 has performance advantages, and is more clearly specified than HTTP/1.0.

R1141 A MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0.

R1140 A MESSAGE SHOULD be sent using HTTP/1.1.

Note that support for HTTP/1.0 is implied in HTTP/1.1, and that intermediaries may change the version of a message; for more information about HTTP versioning, see RFC2145, "Use and Interpretation of HTTP Version Numbers."

3.4.2 HTTP Methods and Extensions

The SOAP1.1 specification defined its HTTP binding such that two possible methods could be used, the HTTP POST method and the HTTP Extension Framework's M-POST method. The Profile requires that only the HTTP POST method be used and precludes use of the HTTP Extension Framework.

R1132 A HTTP request MESSAGE MUST use the HTTP POST method.

R1108 A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774).

The HTTP Extension Framework is an experimental mechanism for extending HTTP in a modular fashion. Because it is not deployed widely and also because its benefits to the use of SOAP are questionable, the Profile does not allow its use.

3.4.3 SOAPAction HTTP Header

Testing has demonstrated that requiring the SOAPAction HTTP header field-value to be quoted increases interoperability of implementations. Even though HTTP allows unquoted header field-values, some SOAP implementations require that they be quoted.

SOAPAction is purely a hint to processors. All vital information regarding the intent of a message is carried in soap:Envelope .

R1109 The value of the SOAPAction HTTP header field in a HTTP request MESSAGE MUST be a quoted string. C

Page 102

R1119 A RECEIVER MAY respond with a fault if the value of the SOAPAction HTTP header field in a message is not quoted. C

R1127 A RECEIVER MUST NOT rely on the value of the SOAPAction HTTP header to correctly process the message.SOAP12

For example, CORRECT:



results in a message with a SOAPAction HTTP header field of:

SOAPAction: "foo"

CORRECT:



or



SOAPAction: ""

3.4.4 HTTP Success Status Codes

HTTP uses the 2xx series of status codes to communicate success. In particular, 200 is the default for successful messages, but 202 can be used to indicate that a message has been submitted for processing. Additionally, other 2xx status codes may be appropriate, depending on the nature of the HTTP interaction.

R1124 An INSTANCE MUST use a 2xx HTTP status code on a response message that indicates the successful outcome of a HTTP request.

R1111 An INSTANCE SHOULD use a "200 OK" HTTP status code on a response message that contains an envelope that is not a fault.

R1112 An INSTANCE SHOULD use either a "200 OK" or "202 Accepted" HTTP status code for a response message that does not contain a SOAP envelope but indicates the successful outcome of a HTTP request.

Page 103

Despite the fact that the HTTP 1.1 assigns different meanings to response status codes "200" and "202", in the context of the Profile they should be considered equivalent by the initiator of the request. The Profile accepts both status codes because some SOAP implementations have little control over the HTTP protocol implementation and cannot control which of these response status codes is sent.

3.4.5 HTTP Redirect Status Codes

There are interoperability problems with using many of the HTTP redirect status codes, generally surrounding whether to use the original method, or GET. The Profile mandates "307 Temporary Redirect", which has the semantic of redirection with the same HTTP method, as the correct status code for redirection. For more information, see the 3xx status code descriptions in RFC2616.

R1130 An INSTANCE MUST use the "307 Temporary Redirect" HTTP status code when redirecting a request to a different endpoint.

R1131 A CONSUMER MAY automatically redirect a request when it encounters a "307 Temporary Redirect" HTTP status code in a response.

RFC2616 notes that user-agents should not automatically redirect requests; however, this requirement was aimed at browsers, not automated processes (which many Web services will be). Therefore, the Profile allows, but does not require, consumers to automatically follow redirections.

3.4.6 HTTP Client Error Status Codes

HTTP uses the 4xx series of status codes to indicate failure due to a client error. Although there are a number of situations that may result in one of these codes, the Profile highlights those when the HTTP request does not have the proper media type, and when the anticipated method ("POST") is not used.

R1125 An INSTANCE MUST use a 4xx HTTP status code for a response that indicates a problem with the format of a request.

R1113 An INSTANCE SHOULD use a "400 Bad Request" HTTP status code, if a HTTP request message is malformed.

R1114 An INSTANCE SHOULD use a "405 Method not Allowed" HTTP status code if a HTTP request message's method is not "POST".

R1115 An INSTANCE SHOULD use a "415 Unsupported Media Type" HTTP status code if a HTTP request message's Content-Type header field-value is not permitted by its WSDL description.

Page 104

Note that these requirements do not force an instance to respond to requests. In some cases, such as Denial of Service attacks, an instance may choose to ignore requests.

3.4.7 HTTP Server Error Status Codes

HTTP uses the 5xx series of status codes to indicate failure due to a server error.

R1126 An INSTANCE MUST return a "500 Internal Server Error" HTTP status code if the response envelope is a Fault.

3.4.8 HTTP Cookies

The HTTP State Management Mechanism ("Cookies") allows the creation of stateful sessions between Web browsers and servers. Being designed for hypertext browsing, Cookies do not have well-defined semantics for Web services, and, because they are external to the envelope, are not accommodated by either SOAP 1.1 or WSDL 1.1. However, there are situations where it may be necessary to use Cookies; e.g., for load balancing between servers, or for integration with legacy systems that use Cookies. For these reasons, the Profile limits the ways in which Cookies can be used, without completely disallowing them.

R1120 An INSTANCE MAY use the HTTP state mechanism ("Cookies").

R1122 An INSTANCE using Cookies SHOULD conform to RFC2965.

R1121 An INSTANCE SHOULD NOT require consumer support for Cookies in order to function correctly.

R1123 The value of the cookie MUST be considered to be opaque by the CONSUMER.

The Profile recommends that cookies not be required by instances for proper operation; they should be a hint, to be used for optimization, without materially affecting the execution of the Web service. However, they may be required in legacy integration and other exceptional use cases, so requiring them does not make an instance non-conformant. While Cookies thus may have meaning to the instance, they should not be used as an out-of-bound data channel between the instance and the consumer. Therefore, interpretation of Cookies is not allowed at all by the consumer - it is required to treat them as opaque (i.e., have no meaning to the consumer).

4. Service Description

The Profile uses Web Services Description Language (WSDL) to enable the description of services as sets of endpoints operating on messages.

Page 105



Namespaces in XML 1.0

XML Schema Part 1: Structures Extensibility points:

E0017 - Schema annotations - XML Schema allows for annotations, which may be used to convey additional information about data structures.


Web Services Description Language (WSDL) 1.1 Extensibility points:

E0013 - WSDL extensions - WSDL allows extension elements in certain places; use of such extensions requires out-of-band negotiation.

E0014 - Validation mode - whether the parser used to read WSDL and XML Schema documents performs DTD validation or not.

E0015 - Fetching of external resources - whether the parser used to read WSDL and XML Schema documents fetches external entities and DTDs.

E0016 - Relative URIs - WSDL does not adequately specify the use of relative URIs for the following: soapbind:body/@namespace, soapbind:address/@location, wsdl:import/@location, xsd:schema/@targetNamespace and xsd:import/@schemaLocation. Their use may require further coordination; see XML Base for more information.

4.1 Required Description

An instance of a Web service is required to make the contract that it operates under available in some fashion.

R0001 Either an INSTANCE's WSDL 1.1 description, its UDDI binding template, or both MUST be available to an authorized consumer upon request.

This means that if an authorized consumer requests a service description of a conformant service instance, then the service instance provider must make the WSDL document, the UDDI binding template, or both available to that consumer. A service instance may provide run-time access to WSDL documents from a

Page 106

server, but is not required to do so in order to be considered conformant. Similarly, a service instance provider may register the instance provider in a UDDI registry, but is not required to do so to be considered conformant. In all of these scenarios, the WSDL contract must exist, but might be made available through a variety of mechanisms, depending on the circumstances.

4.2 Document Structure



WSDL 1.1 defines an XML-based structure for describing Web services. The Profile mandates the use of that structure, and places the following constraints on its use:

4.2.1 WSDL Schema Definitions

The normative schemas for WSDL appearing in Appendix 4 of the WSDL 1.1 specification have inconsistencies with the normative text of the specification. The Profile references new schema documents that have incorporated fixes for known errors.

R2028 A DESCRIPTION using the WSDL namespace (prefixed "wsdl" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd".

R2029 A DESCRIPTION using the WSDL SOAP binding namespace (prefixed "soapbind" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd".

Although the Profile requires WSDL descriptions to be Schema valid, it does not require consumers to validate WSDL documents. It is the responsibility of a WSDL document's author to assure that it is Schema valid.

4.2.2 WSDL and Schema Import

Some examples in WSDL 1.1 incorrectly show the WSDL import statement being used to import XML Schema definitions. The Profile clarifies use of the import mechanisms to keep them consistent and confined to their respective domains. Imported schema documents are also constrained by XML version and encoding requirements consistent to those of the importing WSDL documents.

R2001 A DESCRIPTION MUST only use the WSDL "import" statement to import another WSDL description.

Page 107

R2803 In a DESCRIPTION, the namespace attribute of the wsdl:import MUST NOT be a relative URI.

R2002 To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema "import" statement.

R2003 A DESCRIPTION MUST use the XML Schema "import" statement only within the xsd:schema element of the types section.

R2004 In a DESCRIPTION the schemaLocation attribute of an xsd:import element MUST NOT resolve to any document whose root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".

R2009 An XML Schema directly or indirectly imported by a DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).

R2010 An XML Schema directly or indirectly imported by a DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.

R2011 An XML Schema directly or indirectly imported by a DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

For example, INCORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/d efinitions" xmlns:xsd1="http://example.com/stockquote/schema s" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /schemas" location="http://example.com/stockquote/ stockquote.xsd"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceR equest"/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/d efinitions" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /definitions" location="http://example.com/stockquote/ stockquote.wsdl"/> <message name="GetLastTradePriceInput">

Page 108

<part name="body" element="..."/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquote/" xmlns:xsd1="http://example.com/stockquote/schema s" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /definitions" location="http://example.com/stockquote/sto ckquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="xsd1:TradePriceReq uest"/> </message> ... </definitions>

4.2.3 WSDL Import location Attribute Structure

WSDL 1.1 is not clear about whether the location attribute of the wsdl:import statement is required, or what its content is required to be.

R2007 A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.

Although the wsdl:import statement is modeled after the xsd:import statement, the location attribute is required by wsdl:import while the corresponding attribute on xsd:import , schemaLocation is optional. Consistent with location being required, its content is not intended to be empty.

4.2.4 WSDL Import location Attribute Semantics

WSDL 1.1 is unclear about whether WSDL processors must actually retrieve and process the WSDL document from the URI specified in the location attribute on the wsdl:import statements it encounters.

R2008 A CONSUMER MAY, but need not, retrieve a WSDL description from the URI specified in the location attribute on a wsdl:import element. C

The value of the location attribute of a wsdl:import element is a hint. A WSDL processor may have other ways of locating a WSDL description for a given namespace.

4.2.5 Placement of WSDL import Elements

Example 3 in WSDL 1.1 Section 3.1 causes confusion regarding the placement of wsdl:import .

Page 109

R2022 When they appear in a DESCRIPTION, wsdl:import elements MUST precede all other elements from the WSDL namespace except wsdl:documentation.

R2023 When they appear in a DESCRIPTION, wsdl:types elements MUST precede all other elements from the WSDL namespace except wsdl:documentation and wsdl:import.

For example, INCORRECT: <definitions name="StockQuote" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <import namespace="http://example.com/stockquote /definitions" location="http://example.com/stockquote/st ockquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" type="tns:TradePriceReques t"/> </message> ... <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:Stoc kQuoteSoap"> .... </port> </service> <types> <schema targetNamespace="http://example.com/s tockquote/schemas" xmlns="http://www.w3.org/2001/XMLSch ema"> ....... </schema> </types> </definitions> CORRECT: <definitions name="StockQuote" targetNamespace="http://example.com/stockquot e/definitions"> <import namespace="http://example.com/stockquo te/base" location="http://example.com/stockquote/stoc kquote.wsdl"/> <message name="GetLastTradePriceInput"> <part name="body" element="..."/> </message> ... </definitions> CORRECT: <definitions name="StockQuote" ... xmlns="http://schemas.xmlsoap.org/wsdl/"> <types> <schema targetNamespace="http://example.com/st ockquote/schemas" xmlns="http://www.w3.org/2001/XMLSchema"> .......

Page 110

</schema> </types> <message name="GetLastTradePriceInput"> <part name="body" element="tns:TradePriceRe quest"/> </message> ... <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:Stoc kQuoteSoap"> .... </port> </service> </definitions>

4.2.6 XML Version Requirements

Neither WSDL 1.1 nor XML Schema 1.0 mandate a particular version of XML. For interoperability, WSDL documents and the schemas they import expressed in XML must use version 1.0.

R4004 A DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

4.2.7 XML Namespace declarations

Although published errata NE05 (see http://www.w3.org/XML/xml-names-19990114-errata) allows this namespace declaration to appear, some older processors considered such a declaration to be an error. This requirement ensures that conformant artifacts have the broadest interoperability possible.

R4005 A DESCRIPTION SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace".C

4.2.8 WSDL and the Unicode BOM

XML 1.0 allows documents that use the UTF-8 character encoding to include a BOM; therefore, description processors must be prepared to accept them.

R4002 A DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).C

4.2.9 Acceptable WSDL Character Encodings

The Profile consistently requires either UTF-8 or UTF-16 encoding for both SOAP and WSDL.

R4003 A DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.

Page 111

4.2.10 Namespace Coercion

Namespace coercion on wsdl:import is disallowed by the Profile.

R2005 The targetNamespace attribute on the wsdl:definitions element of a description that is being imported MUST have same the value as the namespace attribute on the wsdl:import element in the importing DESCRIPTION.

4.2.11 WSDL documentation Element

The WSDL 1.1 schema and the WSDL 1.1 specification are inconsistent with respect to where wsdl:documentation elements may be placed.

R2030 In a DESCRIPTION the wsdl:documentation element MAY be present as the first child element of wsdl:import, wsdl:part and wsdl:definitions in addition to the elements cited in the WSDL1.1 specification.WSDL20

4.2.12 WSDL Extensions

Requiring support for WSDL extensions that are not explicitly specified by this or another WS-I Profile can lead to interoperability problems with development tools that have not been instrumented to understand those extensions.

R2025 A DESCRIPTION containing WSDL extensions MUST NOT use them to contradict other requirements of the Profile.

R2026 A DESCRIPTION SHOULD NOT include extension elements with a wsdl:required attribute value of "true" on any WSDL construct (wsdl:binding, wsdl:portType, wsdl:message, wsdl:types or wsdl:import) that claims conformance to the Profile.

R2027 If during the processing of a description, a consumer encounters a WSDL extension element that has a wsdl:required attribute with a boolean value of "true" that the consumer does not understand or cannot process, the CONSUMER MUST fail processing.

Development tools that consume a WSDL description and generate software for a Web service instance might not have built-in understanding of an unknown WSDL extension. Hence, use of required WSDL extensions should be avoided. Use of a required WSDL extension that does not have an available specification for its use and semantics imposes potentially insurmountable interoperability concerns for all but the author of the extension. Use of a required WSDL extension that has an available specification for its use and semantics reduces, but does not eliminate the interoperability concerns that lead to this refinement.

Page 112

For the purposes of the Profile, all elements in the "http://schemas.xmlsoap.org/wsdl/" namespace are extensible via element as well as attributes. As a convenience, WS-I has published a version of the WSDL1.1 schema that reflects this capability at: http://ws-i.org/profiles/basic/1.1/wsdl11.xsd

4.3 Types



The wsdl:types element of WSDL 1.1 encloses data type definitions that are relevant to the Web service described. The Profile places the following constraints pertinent to those portions of the content of the wsdl:types element that are referred to by WSDL elements that make Profile conformance claims:

4.3.1 QName References

XML Schema requires each QName reference to use either the target namespace, or an imported namespace (one marked explicitly with an xsd:import element). QName references to namespaces represented only by nested imports are not allowed.

WSDL 1.1 is unclear as to which schema target namespaces are suitable for QName references from a WSDL element. The Profile allows QName references from WSDL elements both to the target namespace defined by the xsd:schema element, and to imported namespaces. QName references to namespaces that are only defined through a nested import are not allowed.

R2101 A DESCRIPTION MUST NOT use QName references to WSDL components in namespaces that have been neither imported, nor defined in the referring WSDL document.

R2102 A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in the targetNamespace attribute on the xsd:schema element, or to a namespace defined in the namespace attribute on an xsd:import element within the xsd:schema element.

4.3.2 Schema targetNamespace Structure

Requiring a targetNamespace on all xsd:schema elements that are children of wsdl:types is a good practice, places a minimal burden on authors of WSDL documents, and avoids the cases that are not as clearly defined as they might be.

Page 113

R2105 All xsd:schema elements contained in a wsdl:types element of a DESCRIPTION MUST have a targetNamespace attribute with a valid and non-null value, UNLESS the xsd:schema element has xsd:import and/or xsd:annotation as its only child element(s).

4.3.3 soapenc:Array

The recommendations in WSDL 1.1 Section 2.2 for declaration of array types have been interpreted in various ways, leading to interoperability problems. Further, there are other clearer ways to declare arrays.

R2110 In a DESCRIPTION, declarations MUST NOT extend or restrict the soapenc:Array type.

R2111 In a DESCRIPTION, declarations MUST NOT use wsdl:arrayType attribute in the type declaration.

R2112 In a DESCRIPTION, elements SHOULD NOT be named using the convention ArrayOfXXX.

R2113 An ENVELOPE MUST NOT include the soapenc:arrayType attribute.

For example, INCORRECT:

Given the WSDL Description: <xsd:element name="MyArray2" type="tns:MyArray2Type "/> <xsd:complexType name="MyArray2Type" xmlns:soapenc="http://schemas.xmlsoap.org/soap/enc oding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" > <xsd:complexContent> <xsd:restriction base="soapenc:Array"> <xsd:sequence> <xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="tns:MyArray2Type[]"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType>

The envelope would serialize as (omitting namespace declarations for clarity): <MyArray2 soapenc:arrayType="tns:MyArray2Type[]" > <x>abcd</x> <x>efgh</x> </MyArray2> CORRECT:

Given the WSDL Description: <xsd:element name="MyArray1" type="tns:MyArray1Type "/>

Page 114

<xsd:complexType name="MyArray1Type"> <xsd:sequence> <xsd:element name="x" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType>

The envelope would serialize as (omitting namespace declarations for clarity): <MyArray1> <x>abcd</x> <x>efgh</x> </MyArray1>

4.3.4 WSDL and Schema Definition Target Namespaces

The names defined by schemas and the names assigned to WSDL definitions are in separate symbol spaces.

R2114 The target namespace for WSDL definitions and the target namespace for schema definitions in a DESCRIPTION MAY be the same.WSDL20

4.4 Messages



In WSDL 1.1, wsdl:message elements are used to represent abstract definitions of the data being transmitted. It uses wsdl:binding elements to define how the abstract definitions are bound to a specific message serialization. The Profile places the following constraints on wsdl:message elements and on how conformant wsdl:binding elements may use wsdl:message element(s).

In this section the following definitions are used to make the requirements more compact and easier to understand.

Definition: rpc-literal binding


An "rpc-literal operation" is a wsdl:operation child element of wsdl:binding whose soapbind:body descendant elements specify the use attribute with the value "literal", and either:

The style attribute with the value "rpc" is specified on the child soapbind:operation element; or

Page 115

The style attribute is not present on the child soapbind:operation element, and the soapbind:binding element in the enclosing wsdl:binding specifies the style attribute with the value "rpc".

Definition: document-literal binding


A "document-literal operation" is a wsdl:operation child element of wsdl:binding whose soapbind:body descendent elements specifies the use attribute with the value "literal" and, either:

The style attribute with the value "document" is specified on the child soapbind:operation element; or

The style attribute is not present on the child soapbind:operation element, and the soapbind:binding element in the enclosing wsdl:binding specifies the style attribute with the value "document"; or

The style attribute is not present on both the child soapbind:operation element and the soapbind:binding element in the enclosing wsdl:binding .

4.4.1 Bindings and Parts

There are various interpretations about how many wsdl:part elements are permitted or required for document-literal and rpc-literal bindings and how they must be defined.

R2201 A document-literal binding in a DESCRIPTION MUST, in each of its soapbind:body element(s), have at most one part listed in the parts attribute, if the parts attribute is specified.

R2209 A wsdl:binding in a DESCRIPTION SHOULD bind every wsdl:part of a wsdl:message in the wsdl:portType to which it refers with a binding extension element.

R2210 If a document-literal binding in a DESCRIPTION does not specify the parts attribute on a soapbind:body element, the corresponding abstract wsdl:message MUST define zero or one wsdl:parts.

R2202 A wsdl:binding in a DESCRIPTION MAY contain soapbind:body element(s) that specify that zero parts form the soap:Body.

R2203 An rpc-literal binding in a DESCRIPTION MUST refer, in its soapbind:body element(s), only to wsdl:part element(s) that have been defined using the type attribute.

Page 116

R2211 An ENVELOPE described with an rpc-literal binding MUST NOT have the xsi:nil attribute with a value of "1" or "true" on the part accessors.

R2207 A wsdl:message in a DESCRIPTION MAY contain wsdl:parts that use the elements attribute provided those wsdl:parts are not referred to by a soapbind:body in an rpc-literal binding.

R2204 A document-literal binding in a DESCRIPTION MUST refer, in each of its soapbind:body element(s), only to wsdl:part element(s) that have been defined using the element attribute.

R2208 A binding in a DESCRIPTION MAY contain soapbind:header element(s) that refer to wsdl:parts in the same wsdl:message that are referred to by its soapbind:body element(s).

R2212 An ENVELOPE MUST contain exactly one part accessor element for each of the wsdl:part elements bound to the envelope's corresponding soapbind:body element.

R2213 In a doc-literal description where the value of the parts attribute of soapbind:body is an empty string, the corresponding ENVELOPE MUST have no element content in the soap:Body element.

R2214 In a rpc-literal description where the value of the parts attribute of soapbind:body is an empty string, the corresponding ENVELOPE MUST have no part accessor elements.

Use of wsdl:message elements with zero parts is permitted in Document styles to permit operations that can send or receive envelopes with empty soap:Body s. Use of wsdl:message elements with zero parts is permitted in RPC styles to permit operations that have no (zero) parameters and/or a return value.

For document-literal bindings, the Profile requires that at most one part, abstractly defined with the element attribute, be serialized into the soap:Body element.

When a wsdl:part element is defined using the type attribute, the serialization of that part in a message is equivalent to an implicit (XML Schema) qualification of a minOccurs attribute with the value "1", a maxOccurs attribute with the value "1" and a nillable attribute with the value "false".

It is necessary to specify the equivalent implicit qualification because the wsdl:part element does not allow one to specify the cardinality and nillability rules. Specifying the cardinality and the nillability rules facilitates interoperability between implementations. The equivalent implicit qualification for nillable

Page 117

attribute has a value of "false" because if it is specified to be "true" one cannot design a part whereby the client is always required to send a value. For applications that want to allow the wsdl:part to to be nillable, it is expected that applications will generate a complexType wrapper and specify the nillability rules for the contained elements of such a wrapper.

4.4.2 Bindings and Faults

There are several interpretations for how wsdl:part elements that describe soapbind:fault , soapbind:header , and soapbind:headerfault may be defined.

R2205 A wsdl:binding in a DESCRIPTION MUST refer, in each of its soapbind:header, soapbind:headerfault and soapbind:fault elements, only to wsdl:part element(s) that have been defined using the element attribute.

Because faults and headers do not contain parameters, soapbind:fault , soapbind:header and soapbind:headerfault assume, per WSDL 1.1, that the value of the style attribute is "document". R2204 requires that all wsdl:part elements with a style attribute whose value is "document" that are bound to soapbind:body be defined using the element attribute. This requirement does the same for soapbind:fault , soapbind:header and soapbind:headerfault elements.

4.4.3 Declaration of part Elements

Examples 4 and 5 in WSDL 1.1 Section 3.1 incorrectly show the use of XML Schema types (e.g. "xsd:string") as a valid value for the element attribute of a wsdl:part element.

R2206 A wsdl:message in a DESCRIPTION containing a wsdl:part that uses the element attribute MUST refer, in that attribute, to a global element declaration.

For example, INCORRECT: <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string "/> <part name="time" element="xsd:timeInstant"/> </message> INCORRECT: <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string "/> </message> CORRECT: <message name="GetTradePriceInput"> <part name="body" element="tns:SubscribeToQuo tes"/> </message>

4.5 Port Types

Page 118



In WSDL 1.1, wsdl:portType elements are used to group a set of abstract operations. The Profile places the following constraints on conformant wsdl:portType element(s):

4.5.1 Ordering of part Elements

Permitting the use of parameterOrder helps code generators in mapping between method signatures and messages on the wire.

R2301 The order of the elements in the soap:body of an ENVELOPE MUST be the same as that of the wsdl:parts in the wsdl:message that describes it.

R2302 A DESCRIPTION MAY use the parameterOrder attribute of an wsdl:operation element to indicate the return value and method signatures as a hint to code generators.

4.5.2 Allowed Operations

Solicit-Response and Notification operations are not well defined by WSDL 1.1; furthermore, WSDL 1.1 does not define bindings for them.

R2303 A DESCRIPTION MUST NOT use Solicit-Response and Notification type operations in a wsdl:portType definition.

4.5.3 Distinctive Operations

Operation name overloading in a wsdl:portType is disallowed by the Profile.

R2304 A wsdl:portType in a DESCRIPTION MUST have operations with distinct values for their name attributes.

Note that this requirement applies only to the wsdl:operation s within a given wsdl:portType . A wsdl:portType may have wsdl:operation s with names that are the same as those found in other wsdl:portType s.

4.5.4 parameterOrder Attribute Construction

WSDL 1.1 does not clearly state how the parameterOrder attribute of the wsdl:operation element (which is the child of the wsdl:portType element) should be constructed.

R2305 A wsdl:operation element child of a wsdl:portType element in a DESCRIPTION MUST be constructed so that the

Page 119

parameterOrder attribute, if present, omits at most 1 wsdl:part from the output message.

If a wsdl:part from the output message is omitted from the list of wsdl:part s that is the value of the parameterOrder attribute, the single omitted wsdl:part is the return value. There are no restrictions on the type of the return value. If no part is omitted, there is no return value.

4.5.5 Exclusivity of type and element Attributes

WSDL 1.1 does not clearly state that both type and element attributes cannot be specified to define a wsdl:part in a wsdl:message .

R2306 A wsdl:message in a DESCRIPTION MUST NOT specify both type and element attributes on the same wsdl:part.

4.6 Bindings



In WSDL 1.1, the wsdl:binding element supplies the concrete protocol and data format specifications for the operations and messages defined by a particular wsdl:portType . The Profile places the following constraints on conformant binding specifications:

4.6.1 Use of SOAP Binding

The Profile limits the choice of bindings to the well-defined and most commonly used SOAP binding.

R2401 A wsdl:binding element in a DESCRIPTION MUST use WSDL SOAP Binding as defined in WSDL 1.1 Section 3.

Note that this places a requirement on the construction of conformant wsdl:binding elements. It does not place a requirement on descriptions as a whole; in particular, it does not preclude WSDL documents from containing non-conformant wsdl:binding elements. Also, a binding may have WSDL extensibility elements present which change how messages are serialized.

4.7 SOAP Binding



Page 120

WSDL 1.1 defines a binding for SOAP 1.1 endpoints. The Profile mandates the use of SOAP binding as defined in WSDL 1.1, and places the following constraints on its use:

4.7.1 Specifying the transport Attribute

There is an inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding the transport attribute. The WSDL 1.1 specification requires it; however, the schema shows it to be optional.

R2701 The wsdl:binding element in a DESCRIPTION MUST be constructed so that its soapbind:binding child element specifies the transport attribute.

4.7.2 HTTP Transport

The profile limits the underlying transport protocol to HTTP.

R2702 A wsdl:binding element in a DESCRIPTION MUST specify the HTTP transport protocol with SOAP binding. Specifically, the transport attribute of its soapbind:binding child MUST have the value "http://schemas.xmlsoap.org/soap/http".

Note that this requirement does not prohibit the use of HTTPS; See R5000.

4.7.3 Consistency of style Attribute

The style , "document" or "rpc", of an interaction is specified at the wsdl:operation level, permitting wsdl:binding s whose wsdl:operation s have different style s. This has led to interoperability problems.

R2705 A wsdl:binding in a DESCRIPTION MUST either be a rpc-literal binding or a document-literal binding.

4.7.4 Encodings and the use Attribute

The Profile prohibits the use of encodings, including the SOAP encoding.

R2706 A wsdl:binding in a DESCRIPTION MUST use the value of "literal" for the use attribute in all soapbind:body, soapbind:fault, soapbind:header and soapbind:headerfault elements.

4.7.5 Multiple Bindings for portType Elements

The Profile explicitly permits multiple bindings for the same portType.

R2709 A wsdl:portType in a DESCRIPTION MAY have zero or more wsdl:bindings that refer to it, defined in the same or other WSDL documents.

Page 121

4.7.6 Operation Signatures

Definition: operation signature

The profile defines the "operation signature" to be the fully qualified name of the child element of SOAP body of the SOAP input message described by an operation in a WSDL binding.


An endpoint that supports multiple operations must unambiguously identify the operation being invoked based on the input message that it receives. This is only possible if all the operations specified in the wsdl:binding associated with an endpoint have a unique operation signature.

R2710 The operations in a wsdl:binding in a DESCRIPTION MUST result in operation signatures that are different from one another.

4.7.7 Multiple Ports on an Endpoint

When input messages destined for two different wsdl:port s at the same network endpoint are indistinguishable on the wire, it may not be possible to determine the wsdl:port being invoked by them. This may cause interoperability problems. However, there may be situations (e.g., SOAP versioning, application versioning, conformance to different profiles) where it is desirable to locate more than one port on an endpoint; therefore, the Profile allows this.

R2711 A DESCRIPTION SHOULD NOT have more than one wsdl:port with the same value for the location attribute of the soapbind:address element.

4.7.8 Child Element for Document-Literal Bindings

WSDL 1.1 is not completely clear what, in document-literal style bindings, the child element of soap:Body is.

R2712 A document-literal binding MUST be serialized as an ENVELOPE with a soap:Body whose child element is an instance of the global element declaration referenced by the corresponding wsdl:message part.

4.7.9 One-Way Operations

There are differing interpretations of how HTTP is to be used when performing one-way operations.

Page 122

R2714 For one-way operations, an INSTANCE MUST NOT return a HTTP response that contains an envelope. Specifically, the HTTP response entity-body must be empty.

R2750 A CONSUMER MUST ignore an envelope carried in a HTTP response message in a one-way operation.

R2727 For one-way operations, a CONSUMER MUST NOT interpret a successful HTTP response status code (i.e., 2xx) to mean the message is valid or that the receiver would process it.

One-way operations do not produce SOAP responses. Therefore, the Profile prohibits sending a SOAP envelope in response to a one-way operation. This means that transmission of one-way operations can not result in processing level responses or errors. For example, a "500 Internal Server Error" HTTP response that contains a fault can not be returned in this situation.

The HTTP response to a one-way operation indicates the success or failure of the transmission of the message. Based on the semantics of the different response status codes supported by the HTTP protocol, the Profile specifies that "200" and "202" are the preferred status codes that the sender should expect, signifying that the one-way message was received. A successful transmission does not indicate that the SOAP processing layer and the application logic has had a chance to validate the envelope or have committed to processing it.

4.7.10 Namespaces for soapbind Elements

There is confusion about what namespace is associated with the child elements of various children of soap:Envelope , which has led to interoperability difficulties. The Profile defines these.

R2716 A document-literal binding in a DESCRIPTION MUST NOT have the namespace attribute specified on contained soapbind:body, soapbind:header, soapbind:headerfault and soapbind:fault elements.

R2717 An rpc-literal binding in a DESCRIPTION MUST have the namespace attribute specified, the value of which MUST be an absolute URI, on contained soapbind:body elements.

R2726 An rpc-literal binding in a DESCRIPTION MUST NOT have the namespace attribute specified on contained soapbind:header, soapbind:headerfault and soapbind:fault elements.

In a document-literal SOAP binding, the serialized element child of the soap:Body gets its namespace from the targetNamespace of the schema that defines the element. Use of the namespace attribute of the soapbind:body element would override the element's namespace. This is not allowed by the Profile.

Page 123

Conversely, in a rpc-literal SOAP binding, the serialized child element of the soap:Body element consists of a wrapper element, whose namespace is the value of the namespace attribute of the soapbind:body element and whose local name is either the name of the operation or the name of the operation suffixed with "Response". The namespace attribute is required, as opposed to being optional, to ensure that the children of the soap:Body element are namespace-qualified.

4.7.11 Consistency of portType and binding Elements

The WSDL description must be consistent at both wsdl:portType and wsdl:binding levels.

R2718 A wsdl:binding in a DESCRIPTION MUST have the same set of wsdl:operations as the wsdl:portType to which it refers. C

4.7.12 Describing headerfault Elements

There is inconsistency between WSDL specification text and the WSDL schema regarding soapbind:headerfault s.

R2719 A wsdl:binding in a DESCRIPTION MAY contain no soapbind:headerfault elements if there are no known header faults.

The WSDL 1.1 schema makes the specification of soapbind:headerfault element mandatory on wsdl:input and wsdl:output elements of an operation, whereas the WSDL 1.1 specification marks them optional. The specification is correct.

4.7.13 Enumeration of Faults

A Web service description should include all faults known at the time the service is defined. There is also need to permit generation of new faults that had not been identified when the Web service was defined.

R2740 A wsdl:binding in a DESCRIPTION SHOULD contain a soapbind:fault describing each known fault.

R2741 A wsdl:binding in a DESCRIPTION SHOULD contain a soapbind:headerfault describing each known header fault.

R2742 An ENVELOPE MAY contain fault with a detail element that is not described by a soapbind:fault element in the corresponding WSDL description.

R2743 An ENVELOPE MAY contain the details of a header processing related fault in a SOAP header block that is not

Page 124

described by a soapbind:headerfault element in the corresponding WSDL description.

4.7.14 Type and Name of SOAP Binding Elements

The WSDL 1.1 schema disagrees with the WSDL 1.1 specification about the name and type of an attribute of the soapbind:header and soapbind:headerfault elements.

R2720 A wsdl:binding in a DESCRIPTION MUST use the part attribute with a schema type of "NMTOKEN" on all contained soapbind:header and soapbind:headerfault elements.

R2749 A wsdl:binding in a DESCRIPTION MUST NOT use the parts attribute on contained soapbind:header and soapbind:headerfault elements.

The WSDL Schema gives the attribute's name as "parts" and its type as "NMTOKENS". The schema is incorrect since each soapbind:header and soapbind:headerfault element references a single wsdl:part . For example, CORRECT: <binding name="StockQuoteSoap" type="tns:StockQuote PortType"> <soapbind:binding style="document" transport="http://schemas.xmlsoap.o rg/soap/http"/> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"> <soapbind:body parts="body" use="literal"/> <soapbind:header message="tns:SubscribeToQu otes" part="subscribeheader" use="literal" /> </input> </operation> </binding>

4.7.15 name Attribute on Faults

There is inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema, which does not list the name attribute.

R2721 A wsdl:binding in a DESCRIPTION MUST have the name attribute specified on all contained soapbind:fault elements.

R2754 In a DESCRIPTION, the value of the name attribute on a soapbind:fault element MUST match the value of the name attribute on its parent wsdl:fault element.

4.7.16 Omission of the use Attribute

There is inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding the use attribute.

Page 125

R2722 A wsdl:binding in a DESCRIPTION MAY specify the use attribute on contained soapbind:fault elements. C

R2723 If in a wsdl:binding in a DESCRIPTION the use attribute on a contained soapbind:fault element is present, its value MUST be "literal".

WSDL 1.1 Section 3.6 indicates that the use attribute of soapbind:fault is required while in the schema the use attribute is defined as optional. The Profile defines it as optional, to be consistent with soapbind:body .

Since the use attribute is optional, the Profile identifies the default value for the attribute when omitted.

Finally, to assure that the Profile is self-consistent, the only permitted value for the use attribute is "literal".

4.7.17 Default for use Attribute

There is an inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding whether the use attribute is optional on soapbind:body , soapbind:header , and soapbind:headerfault , and if so, what omitting the attribute means.

R2707 A wsdl:binding in a DESCRIPTION that contains one or more soapbind:body, soapbind:fault, soapbind:header or soapbind:headerfault elements that do not specify the use attribute MUST be interpreted as though the value "literal" had been specified in each case.

4.7.18 Consistency of Envelopes with Descriptions

These requirements specify that when an instance receives an envelope that does not conform to the WSDL description, a fault should be generated unless the instance takes it upon itself to process the envelope regardless of this.

As specified by the SOAP processing model, (a) a "VersionMismatch" faultcode must be generated if the namespace of the "Envelope" element is incorrect, (b) a "MustUnderstand" fault must be generated if the instance does not understand a SOAP header block with a value of "1" for the soap:mustUnderstand attribute. In all other cases where an envelope is inconsistent with its WSDL description, a fault with a "Client" faultcode should be generated.

R2724 If an INSTANCE receives an envelope that is inconsistent with its WSDL description, it SHOULD generate a soap:Fault with a faultcode of "Client", unless a "MustUnderstand" or "VersionMismatch" fault is generated.

Page 126

R2725 If an INSTANCE receives an envelope that is inconsistent with its WSDL description, it MUST check for "VersionMismatch", "MustUnderstand" and "Client" fault conditions in that order.

4.7.19 Response Wrappers

WSDL 1.1 Section 3.5 could be interpreted to mean the RPC response wrapper element must be named identical to the name of the wsdl:operation .

R2729 An ENVELOPE described with an rpc-literal binding that is a response MUST have a wrapper element whose name is the corresponding wsdl:operation name suffixed with the string "Response".

4.7.20 Part Accessors

For rpc-literal envelopes, WSDL 1.1 is not clear what namespace, if any, the accessor elements for parameters and return value are a part of. Different implementations make different choices, leading to interoperability problems.

R2735 An ENVELOPE described with an rpc-literal binding MUST place the part accessor elements for parameters and return value in no namespace.

R2755 The part accessor elements in a MESSAGE described with an rpc-literal binding MUST have a local name of the same value as the name attribute of the corresponding wsdl:part element.

Settling on one alternative is crucial to achieving interoperability. The Profile places the part accessor elements in no namespace as doing so is simple, covers all cases, and does not lead to logical inconsistency.

4.7.21 Namespaces for Children of Part Accessors

For rpc-literal envelopes, WSDL 1.1 is not clear on what the correct namespace qualification is for the child elements of the part accessor elements when the corresponding abstract parts are defined to be of types from a different namespace than the targetNamespace of the WSDL description for the abstract parts.

R2737 An ENVELOPE described with an rpc-literal binding MUST namespace qualify the descendents of part accessor elements for the parameters and the return value, as defined by the schema in which the part accessor types are defined.

WSDL 1.1 Section 3.5 states: "The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content not explicitly defined by the abstract types."

Page 127

However, it does not explicitly state that the element and attribute content of the abstract (complexType) types is namespace qualified to the targetNamespace in which those elements and attributes were defined. WSDL 1.1 was intended to function in much the same manner as XML Schema. Hence, implementations must follow the same rules as for XML Schema. If a complexType defined in targetNamespace "A" were imported and referenced in an element declaration in a schema with targetNamespace "B", the element and attribute content of the child elements of that complexType would be qualified to namespace "A" and the element would be qualified to namespace "B". For example, CORRECT:

Given this WSDL, which defines some schema in the "http://example.org/foo/" namespace in the wsdl:types section contained within a wsdl:definitions that has a targetNamespace attribute with the value "http://example.org/bar/" (thus, having a type declared in one namespace and the containing element defined in another); <definitions xmlns="http://schemas.xmlsoap.org/wsdl /" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soa p/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:bar="http://example.org/bar/" targetNamespace="http://example.org/bar/" xmlns:foo="http://example.org/foo/"> <types> <xsd:schema targetNamespace="http://example.org/ foo/" xmlns:tns="http://example.org/foo/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xsd:complexType name="fooType"> <xsd:sequence> <xsd:element ref="tns:bar"/> <xsd:element ref="tns:baf"/> </xsd:sequence> </xsd:complexType> <xsd:element name="bar" type="xsd:string"/> <xsd:element name="baf" type="xsd:integer"/> </xsd:schema> </types> <message name="BarMsg"> <part name="BarAccessor" type="foo:fooType"/> </message> <portType name="BarPortType"> <operation name="BarOperation"> <input message="bar:BarMsg"/> </operation> </portType> <binding name="BarSOAPBinding" type="bar:BarPortTyp e"> <soapbind:binding transport="http://schemas.xmlsoap.org/soap/http /" style="rpc"/>

Page 128

<operation name="BarOperation"> <input message="bar:BarMsg"> <soapbind:body use="literal" namespace="http://example.org/bar/"/> </input> </operation> </binding> <service name="serviceName"> <port name="BarSOAPPort" binding="bar:BarSOAPBind ing"> <soapbind:address location="http://example.org/ myBarSOAPPort"/> </port> </service> </definitions>

The resulting envelope for BarOperation is: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soa p/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc e" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:foo="http://example.org/foo/"> <s:Header/> <s:Body> <m:BarOperation xmlns:m="http://example.org/b ar/"> <BarAccessor> <foo:bar>String</foo:bar> <foo:baf>0</foo:baf> </BarAccessor> </m:BarOperation> </s:Body> </s:Envelope>

4.7.22 Required Headers

WSDL 1.1 does not clearly specify whether all soapbind:header s specified on the wsdl:input or wsdl:output elements of a wsdl:operation element in the SOAP binding section of a WSDL description must be included in the resultant envelopes when they are transmitted. The Profile makes all such headers mandatory, as there is no way in WSDL 1.1 to mark a header optional.

R2738 An ENVELOPE MUST include all soapbind:headers specified on a wsdl:input or wsdl:output of a wsdl:operation of a wsdl:binding that describes it.

4.7.23 Allowing Undescribed Headers

Headers are SOAP's extensibility mechanism. Headers that are not defined in the WSDL description may need to be included in the envelopes for various reasons.

R2739 An ENVELOPE MAY contain SOAP header blocks that are not described in the wsdl:binding that describes it.

Page 129

R2753 An ENVELOPE containing SOAP header blocks that are not described in the appropriate wsdl:binding MAY have the mustUnderstand attribute on such SOAP header blocks set to '1'.

4.7.24 Ordering Headers

There is no correlation between the order of soapbind:header s in the description and the order of SOAP header blocks in the envelope. Similarly, more than one instance of each specified SOAP header block may occur in the envelope.

R2751 The order of soapbind:header elements in soapbind:binding sections of a DESCRIPTION MUST be considered independent of the order of SOAP header blocks in the envelope.

R2752 An ENVELOPE MAY contain more than one instance of each SOAP header block for each soapbind:header element in the appropriate child of soapbind:binding in the corresponding description.

4.7.25 Describing SOAPAction

Interoperability testing has demonstrated that requiring the SOAPAction HTTP header field-value to be quoted increases interoperability of implementations. Even though HTTP allows for header field-values to be unquoted, some implementations require that the value be quoted.

The SOAPAction header is purely a hint to processors. All vital information regarding the intent of a message is carried in the envelope.

R2744 A HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation, if present in the corresponding WSDL description.

R2745 A HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted empty string value, if in the corresponding WSDL description, the soapAction of soapbind:operation is either not present, or present with an empty string as its value.

See also R1119 and related requirements for more discussion of SOAPAction. For example, CORRECT:



Page 130


SOAPAction: "foo"

CORRECT:



or



SOAPAction: ""

4.7.26 SOAP Binding Extensions

The wsdl:required attribute has been widely misunderstood and used by WSDL authors sometimes to incorrectly indicate the optionality of soapbind:header s. The wsdl:required attribute, as specified in WSDL1.1, is an extensibility mechanism aimed at WSDL processors. It allows new WSDL extension elements to be introduced in a graceful manner. The intent of wsdl:required is to signal to the WSDL processor whether the extension element needs to be recognized and understood by the WSDL processor in order that the WSDL description be correctly processed. It is not meant to signal conditionality or optionality of some construct that is included in the envelopes. For example, a wsdl:required attribute with the value "false" on a soapbind:header element must not be interpreted to signal to the WSDL processor that the described SOAP header block is conditional or optional in the envelopes generated from the WSDL description. It is meant to be interpreted as "in order to send a envelope to the endpoint that includes in its description the soapbind:header element, the WSDL processor MUST understand the semantic implied by the soapbind:header element."

The default value for the wsdl:required attribute for WSDL 1.1 SOAP Binding extension elements is "false". Most WSDL descriptions in practice do not specify the wsdl:required attribute on the SOAP Binding extension elements, which could be interpreted by WSDL processors to mean that the extension elements may be ignored. The Profile requires that all WSDL SOAP 1.1 extensions be understood and processed by the consumer, irrespective of the presence or the value of the wsdl:required attribute on an extension element.

R2747 A CONSUMER MUST understand and process all WSDL 1.1 SOAP Binding extension elements, irrespective of the presence or absence of the wsdl:required attribute on an

Page 131

extension element; and irrespective of the value of the wsdl:required attribute, when present.

R2748 A CONSUMER MUST NOT interpret the presence of the wsdl:required attribute on a soapbind extension element with a value of "false" to mean the extension element is optional in the envelopes generated from the WSDL description.

4.8 Use of XML Schema




WSDL 1.1 uses XML Schema as one of its type systems. The Profile mandates the use of XML Schema as the type system for WSDL descriptions of Web Services.

R2800 A DESCRIPTION MAY use any construct from XML Schema 1.0.

R2801 A DESCRIPTION MUST use XML Schema 1.0 Recommendation as the basis of user defined datatypes and structures.

5. Service Publication and Discovery

When publication or discovery of Web services is required, UDDI is the mechanism the Profile has adopted to describe Web service providers and the Web services they provide. Business, intended use, and Web service type descriptions are made in UDDI terms; detailed technical descriptions are made in WSDL terms. Where the two specifications define overlapping descriptive data and both forms of description are used, the Profile specifies that the descriptions must not conflict.

Registration of Web service instances in UDDI registries is optional. By no means do all usage scenarios require the kind of metadata and discovery UDDI provides, but where such capability is needed, UDDI is the sanctioned mechanism.

Note that the Web services that constitute UDDI V2 are not fully conformant with the Profile 1.0 because they do not accept messages whose envelopes are encoded in both UTF-8 and UTF-16 as required by the Profile. (They accept UTF-8 only.) That there should be such a discrepancy is hardly surprising given that UDDI V2 was designed and, in many cases, implemented before the Profile

Page 132

was developed. UDDI's designers are aware of UDDI V2's nonconformance and will take it into consideration in their future work.





5.1 bindingTemplates



UDDI represents Web service instances as uddi:bindingTemplate elements. The uddi:bindingTemplate plays a role that is the rough analog of the wsdl:port , but provides options that are not expressible in WSDL. To keep the WSDL description of an instance and its UDDI description consistent, the Profile places the following constraints on how uddi:bindingTemplate elements may be constructed.

WSDL's soapbind:address element requires the network address of the instance to be directly specified. In contrast, UDDI V2 provides two alternatives for specifying the network address of instances it represents. One, the uddi:accessPoint , mirrors the WSDL mechanism by directly specifying the address. The other, the uddi:hostingRedirector , provides a Web service-based indirection mechanism for resolving the address, and is inconsistent with the WSDL mechanism.

R3100 REGDATA of type uddi:bindingTemplate representing a conformant INSTANCE MUST contain the uddi:accessPoint element.

For example, INCORRECT: <bindingTemplate bindingKey="..."> <description xml:lang="EN">BarSOAPPort</descript ion> <hostingRedirector bindingKey="..."/> <tModelInstanceDetails> ... </tModelInstanceDetails> </bindingTemplate> CORRECT: <bindingTemplate bindingKey="..."> <description xml:lang="EN">BarSOAPPort</descript ion> <accessPoint>http://example.org/myBarSOAPPort</a ccessPoint> <tModelInstanceDetails>

Page 133

... </tModelInstanceDetails> </bindingTemplate>

5.2 tModels



UDDI represents Web service types as uddi:tModel elements. (See UDDI Data Structures section 8.1.1.) These may, but need not, point (using a URI) to the document that contains the actual description. Further, UDDI is agnostic with respect to the mechanisms used to describe Web service types. The Profile cannot be agnostic about this because interoperation is very much complicated if Web service types do not have descriptions or if the descriptions can take arbitrary forms.

The UDDI API Specification, appendix I.1.2.1.1 allows but does not require uddi:tModel elements that use WSDL to describe the Web service type they represent to state that they use WSDL as the description language. Not doing so leads to interoperability problems because it is then ambiguous what description language is being used.

Therefore the Profile places the following constraints on how uddi:tModel elements that describe Web service types may be constructed:

The Profile chooses WSDL as the description language because it is by far the most widely used such language.

R3002 REGDATA of type uddi:tModel representing a conformant Web service type MUST use WSDL as the description language.

To specify that conformant Web service types use WSDL, the Profile adopts the UDDI categorization for making this assertion.

R3003 REGDATA of type uddi:tModel representing a conformant Web service type MUST be categorized using the uddi:types taxonomy and a categorization of "wsdlSpec".

For the uddi:overviewURL in a uddi:tModel to resolve to a wsdl:binding , the Profile must adopt a convention for distinguishing among multiple wsdl:binding s in a WSDL document. The UDDI Best Practice for Using WSDL in a UDDI Registry specifies the most widely recognized such convention.

R3010 REGDATA of type uddi:tModel representing a conformant Web service type MUST follow V1.08 of the UDDI Best Practice for Using WSDL in a UDDI Registry.

Page 134

It would be inconsistent if the wsdl:binding that is referenced by the uddi:tModel does not conform to the Profile.

R3011 The wsdl:binding that is referenced by REGDATA of type uddi:tModel MUST itself conform to the Profile.

6. Security

As is true of all network-oriented information technologies, the subject of security is a crucial one for Web services. For Web services, as for other information technologies, security consists of understanding the potential threats an attacker may mount and applying operational, physical, and technological countermeasures to reduce the risk of a successful attack to an acceptable level. Because an "acceptable level of risk" varies hugely depending on the application, and because costs of implementing countermeasures is also highly variable, there can be no universal "right answer" for securing Web services. Choosing the absolutely correct balance of countermeasures and acceptable risk can only be done on a case by case basis.

That said, there are common patterns of countermeasures that experience shows reduce the risks to acceptable levels for many Web services. The Profile adopts, but does not mandate use of, the most widely used of these: HTTP secured with either TLS 1.0 or SSL 3.0 (HTTPS). That is, conformant Web services may use HTTPS; they may also use other countermeasure technologies or none at all.

HTTPS is widely regarded as a mature standard for encrypted transport connections to provide a basic level of confidentiality. HTTPS thus forms the first and simplest means of achieving some basic security features that are required by many real-world Web service applications. HTTPS may also be used to provide client authentication through the use of client-side certificates.



RFC2246: The TLS Protocol Version 1.0 Extensibility points:

E0019 - TLS Cyphersuite - TLS allows for the use of arbitrary encryption algorithms.

E0020 - TLS Extensions - TLS allows for extensions during the handshake phase.

The SSL Protocol Version 3.0 Extensibility points:

Page 135

E0021 - SSL Cyphersuite - SSL allows for the use of arbitrary encryption algorithms.

RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile Extensibility points:

E0022 - Certificate Authority - The choice of the Certificate Authority is a private agreement between parties.

E0023 - Certificate Extensions - X509 allows for arbitrary certificate extensions.

6.1 Use of HTTPS

HTTPS is such a useful, widely understood basic security mechanism that the Profile needs to allow it.

R5000 An INSTANCE MAY require the use of HTTPS.

R5001 If an INSTANCE requires the use of HTTPS, the location attribute of the soapbind:address element in its wsdl:port description MUST be a URI whose scheme is "https"; otherwise it MUST be a URI whose scheme is "http".

Simple HTTPS provides authentication of the Web service instance by the consumer but not authentication of the consumer by the instance. For many instances this leaves the risk too high to permit interoperation. Including the mutual authentication facility of HTTPS in the Profile permits instances to use the countermeasure of authenticating the consumer. In cases in which authentication of the instance by the consumer is insufficient, this often reduces the risk sufficiently to permit interoperation.

R5010 An INSTANCE MAY require the use of HTTPS with mutual authentication.

Appendix A: Referenced Specifications

The following specifications' requirements are incorporated into the Profile by reference, except where superseded by the Profile:

Simple Object Access Protocol (SOAP) 1.1

RFC2616: Hypertext Transfer Protocol -- HTTP/1.1



Namespaces in XML 1.0


Page 136


Web Services Description Language (WSDL) 1.1





RFC2246: The TLS Protocol Version 1.0

The SSL Protocol Version 3.0

RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile

Appendix B: Extensibility Points

This section identifies extensibility points, as defined in "Scope of the Profile," for the Profile's component specifications.

These mechanisms are out of the scope of the Profile; their use may affect interoperability, and may require private agreement between the parties to a Web service.

In Simple Object Access Protocol (SOAP) 1.1:

E0001 - Header blocks - Header blocks are the fundamental extensibility mechanism in SOAP.

E0002 - Processing order - The order of processing of a SOAP envelope's components (e.g., headers) is unspecified, and therefore may need to be negotiated out-of-band.

E0003 - Use of intermediaries - SOAP Intermediaries is an underspecified mechanism in SOAP 1.1, and their use may require out-of-band negotiation. Their use may also necessitate careful consideration of where Profile conformance is measured.

E0004 - soap:actor values - Values of the soap:actor attribute, other than the special uri 'http://schemas.xmlsoap.org/soap/actor/next' , represent a private agreement between parties of the web service.

E0005 - Fault details - the contents of a Fault's detail element are not prescribed by SOAP 1.1.

E0006 - Envelope serialization - The Profile does not constrain some aspects of how the envelope is serialized into the message.

Page 137

In RFC2616: Hypertext Transfer Protocol -- HTTP/1.1:

E0007 - HTTP Authentication - HTTP authentication allows for extension schemes, arbitrary digest hash algorithms and parameters.

E0008 - Unspecified Header Fields - HTTP allows arbitrary headers to occur in messages.

E0009 - Expect-extensions - The Expect/Continue mechanism in HTTP allows for expect-extensions.

E0010 - Content-Encoding - The set of content-codings allowed by HTTP is open-ended and any besides 'gzip', 'compress', or 'deflate' are an extensibility point.

E0011 - Transfer-Encoding - The set of transfer-encodings allowed by HTTP is open-ended.

E0012 - Upgrade - HTTP allows a connection to change to an arbitrary protocol using the Upgrade header.

E0024 - Namespace Attributes - Namespace attributes on soap:Envelope and soap:Header elements

E0025 - Attributes on soap:Body elements - Neither namespaced nor local attributes are constrained by SOAP 1.1.

In XML Schema Part 1: Structures:

E0017 - Schema annotations - XML Schema allows for annotations, which may be used to convey additional information about data structures.

In Web Services Description Language (WSDL) 1.1:

E0013 - WSDL extensions - WSDL allows extension elements in certain places; use of such extensions requires out-of-band negotiation.

E0014 - Validation mode - whether the parser used to read WSDL and XML Schema documents performs DTD validation or not.

E0015 - Fetching of external resources - whether the parser used to read WSDL and XML Schema documents fetches external entities and DTDs.

E0016 - Relative URIs - WSDL does not adequately specify the use of relative URIs for the following: soapbind:body/@namespace, soapbind:address/@location, wsdl:import/@location, xsd:schema/@targetNamespace and xsd:import/@schemaLocation. Their use may require further coordination; see XML Base for more information.

In RFC2246: The TLS Protocol Version 1.0:

Page 138

E0019 - TLS Cyphersuite - TLS allows for the use of arbitrary encryption algorithms.

E0020 - TLS Extensions - TLS allows for extensions during the handshake phase.

In The SSL Protocol Version 3.0:

E0021 - SSL Cyphersuite - SSL allows for the use of arbitrary encryption algorithms.

In RFC2459: Internet X.509 Public Key Infrastructure Certificate and CRL Profile:

E0022 - Certificate Authority - The choice of the Certificate Authority is a private agreement between parties.

E0023 - Certificate Extensions - X509 allows for arbitrary certificate extensions.

Appendix C: Defined Terms

The following list of terms have specific definitions that are authoritative for this profile:

rpc-literal binding


An "rpc-literal operation" is a wsdl:operation child element of wsdl:binding whose soapbind:body descendant elements specify the use attribute with the value "literal", and either:

The style attribute with the value "rpc" is specified on the child soapbind:operation element; or

The style attribute is not present on the child soapbind:operation element, and the soapbind:binding element in the enclosing wsdl:binding specifies the style attribute with the value "rpc".

document-literal binding


A "document-literal operation" is a wsdl:operation child element of wsdl:binding whose soapbind:body descendent elements specifies the use attribute with the value "literal" and, either:

The style attribute with the value "document" is specified on the child soapbind:operation element; or

Page 139

The style attribute is not present on the child soapbind:operation element, and the soapbind:binding element in the enclosing wsdl:binding specifies the style attribute with the value "document"; or

The style attribute is not present on both the child soapbind:operation element and the soapbind:binding element in the enclosing wsdl:binding .

operation signature

The profile defines the "operation signature" to be the fully qualified name of the child element of SOAP body of the SOAP input message described by an operation in a WSDL binding.


Appendix D: Acknowledgements

This document is the work of the WS-I Basic Profile Working Group, whose members have included:

Mark Allerton (Crystal Decisions Corp), Steve Anderson (OpenNetwork), George Arriola (Talking Blocks, Inc.), Siddharth Bajaj (Verisign), Keith Ballinger (Microsoft Corp.), David Baum (Kantega AS), Ilya Beyer (KANA), Rich Bonneau (IONA Technologies), Don Box (Microsoft Corp.), Andrew Brown (Verisign), Heidi Buelow (Quovadx), David Burdett (Commerce One, Inc.), Luis Felipe Cabrera (Microsoft Corp.), Maud Cahuzac (France Telecom), Mike Chadwick (Kaiser Permanente), Martin Chapman (Oracle Corporation), Richard Chennault (Kaiser Permanente), Roberto Chinnici (Sun Microsystems), Dipak Chopra (SAP AG), Jamie Clark (OASIS), David Cohen (Merrill Lynch), Ugo Corda (SeeBeyond Tech), Paul Cotton (Microsoft Corp.), Joseph Curran (Accenture), Alex Deacon (Verisign), Mike DeNicola (Fujitsu Limited), Paul Downey (BT Group), Jacques Durand (Fujitsu Limited), Aladin Eajani (Hummingbird, Ltd.), Michael Eder (Nokia), Dave Ehnebuske (IBM), Mark Ericson (Mindreef Inc), Colleen Evans (Microsoft Corp.), Tim Ewald (Microsoft Corp.), Chuck Fay (FileNET Corp.), Chris Ferris (IBM), Daniel Foody (Actional Corporation), Satoru Fujita (NEC Corporation), Shishir Garg (France Telecom), Yaron Goland (BEA Systems Inc), Marc Goodner (SAP AG), Pierre Goyette (Hummingbird, Ltd.), Hans Granqvist (Verisign), Martin Gudgin (Microsoft Corp.), Marc Hadley (Sun Microsystems), Norma Hale (Webify Solutions Inc), Bob Hall (Unisys Corporation), Scott Hanselman (Corillian), Muir Harding (Autodesk Inc.), Loren Hart (Verisign), Andrew Hately (IBM), Harry Holstrom (Accenture), Lawrence Hsiung (Quovadx), Hemant Jain (Tata Consultancy), Steve Jenisch (SAS Institute), Erik Johnson (Epicor Software), Bill Jones (Oracle Corporation), Anish Karmarkar (Oracle Corporation), Dana Kaufman (Forum Systems), Takahiro Kawamura (Toshiba),

Page 140

Oldre Kepka (Systinet), Bhushan Khanal (WRQ Inc.), Sandy Khaund (Microsoft Corp.), Jacek Kopecky (Systinet), Sanjay Krishnamurthi (Informatica), Sundar Krishnamurthy (Verisign), Eva Kuiper (Hewlett-Packard), Sunil Kunisetty (Oracle Corporation), Christopher Kurt (Microsoft Corp.), Lars Laakes (Microsoft Corp.), Canyang Kevin Liu (SAP AG), Ted Liu (webMethods Inc.), Donna Locke (Oracle Corporation), Brad Lund (Intel), Michael Mahan (Nokia), Ron Marchi (EDS), Jonathan Marsh (Microsoft Corp.), Eric Matland (Hummingbird, Ltd.), Barbara McKee (IBM), Derek Medland (Hummingbird, Ltd.), David Meyer (Plumtree Software Inc.), Jeff Mischkinsky (Oracle Corporation), Ray Modeen (MITRE Corp.), Tom Moog (Sarvega Inc.), Gilles Mousseau (Hummingbird, Ltd.), Greg Mumford (MCI), Jim Murphy (Mindreef Inc), Bryan Murray (Hewlett-Packard), Richard Nikula (BMC Software, Inc.), Eisaku Nishiyama (Hitachi, Ltd.), Mark Nottingham (BEA Systems Inc), David Orchard (BEA Systems Inc), Vivek Pandey (Sun Microsystems), Jesse Pangburn (Quovadx), Eduardo Pelegri-Llopart (Sun Microsystems), Mike Perham (Webify Solutions Inc), Eric Rajkovic (Oracle Corporation), Shaan Razvi (MITRE Corp.), Rimas Rekasius (IBM), Mark Richards (Fidelity), Graeme Riddell (Bowstreet), Sam Ruby (IBM), Tom Rutt (Fujitsu Limited), Saikat Saha (Commerce One, Inc.), Roger Sanborn (Crystal Decisions Corp), Matt Sanchez (Webify Solutions Inc), Krishna Sankar (Cisco Systems Inc.), Jeffrey Schlimmer (Microsoft Corp.), Don Schricker (Micro Focus), Dave Seidel (Mindreef Inc), AKIRA SHIMAYA (NTT), David Shoaf (Hewlett-Packard), Yasser Shohoud (Microsoft Corp.), David Smiley (Ascential Software), Seumas Soltysik (IONA Technologies), Joseph Stanko (Plumtree Software Inc.), Andrew Stone (Accenture), Julie Surer (MITRE Corp.), YASUO TAKEMOTO (NTT), Nobuyoshi Tanaka (NEC Corporation), Jorgen Thelin (Microsoft Corp.), Sameer Vaidya (Talking Blocks, Inc.), William Vambenepe (Hewlett-Packard), Claus von Riegen (SAP AG), Rick Weil (Eastman Kodak Company), Scott Werden (WRQ Inc.), Ajamu Wesley (IBM), Ian White (Micro Focus), Dave Wilkinson (Vignette), Mark Wood (Eastman Kodak Company), Prasad Yendluri (webMethods Inc.), and Brandon Zhu (NetManage Inc).