WS-I

Basic Profile Version 1.2

Working Group Draft

2009-12-02

This revision:
http://mp.ws-i.org/apps/org/workgroup/bpwg/download.php/BasicProfile-1.2-WGD.html?versionID=$Revision: 1.10 $
Latest revision:
http://mp.ws-i.org/apps/org/workgroup/bpwg/download.php/BasicProfile-1.2-WGD.html
Editors:
Robert Chumbley , IBM
Jacques Durand , Fujitsu
Micah Hainline , Asynchrony Solutions
Gilbert Pilz , Oracle
Tom Rutt , Fujitsu
Administrative contact:
secretary@ws-i.org

Abstract

This document defines the WS-I Basic Profile 1.2, consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability. It also contains a set of executable test assertions for assessing the conformance to the profile.

Status of this Document

This document is a Working Group Draft; it has been accepted by the Working Group as reflecting the current state of discussions. It is a work in progress, and should not be considered authoritative or final; other documents may supersede this document.

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 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

The Web Services-Interoperability Organization (WS-I) would like to receive input, suggestions and other feedback ("Feedback") on this work from a wide variety of industry participants to improve its quality over time.

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 wsbasic_comment@ws-i.org.

Table of Contents

1. Introduction
1.1. Relationships to Other Profiles
1.2. Guiding Principles
1.3. Test Assertions
1.4. Compatibility with Basic Profile 1.1
1.5. Notational Conventions
1.6. 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. Message Serialization
3.1.1. XML Envelope Serialization
3.1.2. Unicode BOMs
3.1.3. XML Declarations
3.1.4. Character Encodings
3.2. SOAP Envelopes
3.2.1. SOAP Envelope Structure
3.2.2. SOAP Envelope Namespace
3.2.3. SOAP Body Namespace Qualification
3.2.4. Disallowed Constructs
3.2.5. SOAP Trailers
3.2.6. SOAP encodingStyle Attribute
3.2.7. SOAP mustUnderstand Attribute
3.2.8. xsi:type Attributes
3.2.9. SOAP 1.1 attributes on SOAP 1.1 elements
3.3. SOAP Processing Model
3.3.1. Mandatory Headers
3.3.2. Generating mustUnderstand Faults
3.3.3. SOAP Fault Processing
3.4. SOAP Faults
3.4.1. Identifying SOAP Faults
3.4.2. SOAP Fault Structure
3.4.3. SOAP Fault Namespace Qualification
3.4.4. SOAP Fault Extensibility
3.4.5. SOAP Fault Language
3.4.6. SOAP Custom Fault Codes
3.5. Use of SOAP in HTTP
3.5.1. HTTP Protocol Binding
3.5.2. HTTP Methods and Extensions
3.5.3. SOAPAction HTTP Header
3.5.4. HTTP Success Status Codes
3.5.5. HTTP Redirect Status Codes
3.5.6. HTTP Client Error Status Codes
3.5.7. HTTP Server Error Status Codes
3.5.8. HTTP Cookies
3.5.9. Non-Addressable Consumers and Instances
3.6. WS-Addressing Support
3.6.1. Requiring WS-Addressing SOAP headers
3.6.2. NotUnderstood block in MustUnderstand Fault on WS-Addressing SOAP headers
3.6.3. Use of wsa:Action and WS-Addressing 1.0 - Metadata
3.6.4. Valid Values for SOAPAction When WS-Addressing is Used
3.6.5. SOAP Defined Faults Action URI
3.6.6. Understanding WS-Addressing SOAP Header Blocks
3.6.7. Ignored or Absent WS-Addressing MAPs
3.6.8. Present and Understood WS-Addressing MAPs
3.6.9. SOAP MustUnderstand or VersionMismatch fault Transmission
3.6.10. Faulting Behavior with Present and Understood WS-Addressing MAPs
3.6.11. [message id] and One-Way Operations
3.6.12. Refusal to Honor WS-Addressing MAPs
3.6.13. Use of Non-Anonymous Response EPRs
3.6.14. Optionality of the wsa:To header
3.6.15. Extending WSDL Endpoints with an EPR
3.6.16. Combining Synchronous and Asynchronous Operations
3.6.17. Conflicting Addressing Policies
4. Service Description
4.1. Required Description
4.2. Document Structure
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.3.5. Multiple GED Definitions with the same QName
4.3.6. Multiple Type Definitions with the same QName
4.4. Messages
4.4.1. Bindings and Parts
4.4.2. Bindings and Faults
4.4.3. Unbound portType Element Contents
4.4.4. 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 wsoap11 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
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
4.9. WS-Addressing 1.0 - Metadata
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: Normative References
Appendix D: Defined Terms
Appendix E: Acknowledgements

1. Introduction

This document defines the WS-I Basic Profile 1.2 (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.1 by incorporating any errata to date and including those requirements related to the serialization of envelopes and their representation in messages from the Simple SOAP Binding Profile 1.0 .

This Profile is NOT intended to be composed with the Simple SOAP Binding 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 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
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.3 Test Assertions

This profile document contains embedded Test Assertions (TA) that are associated with each normative profile requirement. In the HTML rendering of this document, these test assertions are accessible via a toggle link at the end of each requirement. When clicking on such a link, a table pops up that displays the TA parts. At the end of this table is another toggle link ("help-glossary") that displays an explanation glossary for the TA structure. In other formats of this document, the test assertions are grouped in an appendix not controlled by any link, in order to facilitate the printing of hard copies. The resulting set of test assertions embedded in this document represents a conformance test suite for the profile.

Release notes related to the test material included in this document are available here:

TESTING-RELEASE-NOTES

1.4 Compatibility with Basic Profile 1.1

There are a few requirements in the Basic Profile 1.2 that may present compatibility issues with clients, services and their artifacts that have been engineered for Basic Profile 1.1 conformance. However, in general, the Basic Profile WG members have tried to preserve as much forwards and backwards compatibility with the Basic Profile 1.1 as possible so as not to disenfranchise clients, services and their artifacts that have been deployed in conformance with the Basic Profile 1.1.

We use the term 'backward compatible' to mean that an artifact, client or service that is conformant to the Basic Profile 1.1 will behave consistently with an implementation that is conformant with the Basic Profile 1.2. We use the term 'forward compatible' to mean that an artifact, client or service that is conformant with the Basic Profile 1.2 specification will be consistent with that of an implementation that is conformant with the Basic Profile 1.1.

We have attempted to capture all known potential backwards and forwards compatibility issues below:

The list above is not meant to be authoritative.

As noted above, some requirements may present issues of a forward or backward compatible nature with previously published versions of the profile. For convenience, such requirements and associated definitions are annotated in the following manner: Compat

1.5 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 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.

Note: in this working group draft the requirements have not yet been fully namespace qualified - this is still a task to be completed before the Profile is completed.

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 published, the specification that the requirement is derived from may change; this information is included only as a convenience to implementers.

As noted above, some requirements may present compatibility issues (whether forwards or backwards) with previously published versions of the profile. For convenience, such requirements are annotated in the following manner: Compat

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 Profile supports multiple conformance targets. Requirements or sections specific to the use of a particular conformance target are annotated in the following manner: TARGET.

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.

1.6 Profile Identification and Versioning

This document is identified by a name (in this case, Basic Profile) and a version number (here, 1.2). 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.

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 Any WIDGET 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"). The conformance target keyword appears in bold text (e.g. " MESSAGE"). Other conformance targets appearing in non-bold text are being used strictly for their definition and NOT as a conformance target. 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:

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:

Claims of conformance for the Basic Profile 1.2 encompass the transport-independent and HTTP-specific requirements. Claims are separated into two disjoint parts and an aggregated claim for the complete Basic Profile: "CORE", "HTTP-TRANSPORT", and "COMPLETE". The Basic Profile 1.2 conformance claim URI(s) are:

The union of the requirements tagged as "HTTP-TRANSPORT" and "CORE" requirements comprise "BP 1.2 Complete".

3. Messaging

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

3.1 Message Serialization

The profile is intended to compose with mechanisms currently under development to describe whether messages are encoded as SIMPLE_SOAP_MESSAGEs or XOP_ENCODED_MESSAGEs. As such it does not mandate that both of those encodings be supported for any given operation. Indeed, neither of these encodings need be supported if an alternate encoding such as that described in the Attachments Profile 1.0 is used.

SOAP 1.1 defines an XML structure for transmitting messages, the envelope. The Profile places the following constraints on the use and serialization of the soap11:Envelope element and its content:

As this Profile allows for the use of protocol bindings other than HTTP, the transport is responsible for defining how encoding is handled in Section 3.1. Section 2.2 identifies the use of Simple SOAP and XOP encoded messages using HTTP. For HTTP, transport protocol constraints are identified in RFC 3023 .

This section of the Profile incorporates the following specifications by reference:

3.1.1 XML Envelope Serialization

R9701 An ENVELOPE MUST be serialized as XML 1.0. CORE TESTABLE BP1019

3.1.2 Unicode BOMs

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

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

3.1.3 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 with envelopes that contain an XML Declaration. C CORE TESTABLE BP1015

3.1.4 Character Encodings

The Profile requires XML processors to 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") on envelopes, the "charset" parameter must always be present on the envelope's content-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".

The "charset" parameter of Content-Type HTTP header field must be used to determine the correct character encoding of the message, in absence of a "charset" parameter, the default value for charset (which is "us-ascii") must be used.

R1012 An ENVELOPE MUST be serialized using either UTF-8 or UTF-16 character encoding. CORE TESTABLE BP1018

R1018 A SIMPLE_SOAP_MESSAGE MUST indicate the correct character encoding, using the "charset" parameter. C CORE TESTABLE BP1018

R1019 A RECEIVER MUST ignore the encoding pseudo-attribute of the envelope's XML declaration. CORE NOT_TESTABLE

3.2 SOAP Envelopes

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

3.2.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). CORE TESTABLE BP1600

R9981 An ENVELOPE MUST have exactly zero or one child elements of the soap11:Body element. CORE TESTABLE BP1881

While the combination of R2201 and R2210 (below) clearly imply that there may be at most one child element of the soap11:Body , there is no explicit requirement in the Profile that articulates this constraint, leading to some confusion.

3.2.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.

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

3.2.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 soap11:Body .

R1014 The children of the soap11:Body element in an ENVELOPE MUST be namespace qualified. CORE TESTABLE BP1202

3.2.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 CORE TESTABLE BP1007

R1009 An ENVELOPE MUST NOT contain Processing Instructions. C CORE TESTABLE BP1208

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

3.2.5 SOAP Trailers

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

R1011 An ENVELOPE MUST NOT have any element children of soap11:Envelope following the soap11:Body element. CORE TESTABLE BP1263

This requirement clarifies a mismatch between the SOAP 1.1 specification and the SOAP 1.1 XML Schema.

For example,

INCORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <p:Process xmlns:p="http://example.org/Operations"/>
  </soap11:Body>
  <m:Data xmlns:m='http://example.org/information' >
    Here is some data with the message
  </m:Data>
</soap11:Envelope>

CORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <p:Process xmlns:p="http://example.org/Operations">
      <m:Data xmlns:m="http://example.org/information">
        Here is some data with the message
      </m:Data>
    </p:Process>
  </soap11:Body>
</soap11:Envelope>

3.2.6 SOAP encodingStyle Attribute

The soap11: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 soap11:encodingStyle attributes on any of the elements whose namespace name is "http://schemas.xmlsoap.org/soap/envelope/". CORE TESTABLE BP2005

R1006 An ENVELOPE MUST NOT contain soap11:encodingStyle attributes on any element that is a child of soap11:Body . CORE TESTABLE BP2005

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

3.2.7 SOAP mustUnderstand Attribute

The soap11: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 soap11:mustUnderstand attribute MUST only use the lexical forms "0" and "1". C CORE TBD

3.2.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 indicate a derived type (see XML Schema Part 1: Structures, Section 2.6.1). CORE NOT_TESTABLE

3.2.9 SOAP 1.1 attributes on SOAP 1.1 elements

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

3.3 SOAP Processing Model

SOAP 1.1, Section 2 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.3.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 soap11:Header element bearing a soap11: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 CORE TBD

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.3.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 "soap11:MustUnderstand" fault when an envelope contains a mandatory header block (i.e., one that has a soap11:mustUnderstand attribute with the value "1") targeted at the receiver (via soap11:actor) that the receiver does not understand. SOAP12 CORE TBD

3.3.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 CORE TBD

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, the RECEIVER MUST NOT transmit the non-faulting response. Whether or not the fault is transmitted (and not just generated) will be goverened by R1030. CORE NOT_TESTABLE

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. CORE NOT_TESTED

Note that there may be valid reasons (such as security considerations) why a fault may not be transmitted.

3.4 SOAP Faults

3.4.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 soap11:Body element, that element being the soap11:Fault element.

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

3.4.2 SOAP Fault Structure

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

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

For example,

INCORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault>
      <faultcode>soap11:Client</faultcode>
      <faultstring>Invalid message format</faultstring>
      <faultactor>http://example.org/someactor</faultactor>
      <detail>There were lots of elements in the message that I did not understand.</detail>
      <m:Exception xmlns:m="http://example.org/faults/exceptions">
        <m:ExceptionType>Severe</m:ExceptionType>
      </m:Exception>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

CORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
      <faultcode>soap11:Client</faultcode>
      <faultstring>Invalid message format</faultstring>
      <faultactor>http://example.org/someactor</faultactor>
      <detail xmlns:m="http://example.org/faults/exceptions">
        <m:msg>There were lots of elements in the message that I did not understand.</m:msg>
        <m:Exception>
          <m:ExceptionType>Severe</m:ExceptionType>
        </m:Exception>
      </detail>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

3.4.3 SOAP Fault Namespace Qualification

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

R1001 When an ENVELOPE is a Fault, the element children of the soap11:Fault element MUST be unqualified. CORE TESTABLE BP1261

For example,

INCORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault>
      <soap11:faultcode>soap11:Client</soap11:faultcode>
      <soap11:faultstring>Invalid message format</soap11:faultstring>
      <soap11:faultactor>http://example.org/someactor</soap11:faultactor>
      <soap11:detail>
        <m:msg xmlns:m="http://example.org/faults/exceptions">
          There were lots of elements in the message that I did not understand.
        </m:msg>
      </soap11:detail>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

CORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault>
      <faultcode>soap11:Client</faultcode>
      <faultstring>Invalid message format</faultstring>
      <faultactor>http://example.org/someactor</faultactor>
      <detail>
        <m:msg xmlns:m="http://example.org/faults/exceptions">
          There were lots of elements in the message that I did not understand.
       </m:msg>
      </detail>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

3.4.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. CORE TBD

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/". CORE TBD

3.4.5 SOAP Fault Language

Faultstrings are human-readable indications of the nature of a fault. As such, they may 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://ws-i.org/profiles/basic/1.1/soap-envelope-2004-01-21.xsd ".

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

3.4.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.

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). CORE TBD

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. CORE TBD

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: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault>
      <faultcode>soap11:Server.ProcessingError</faultcode>
      <faultstring>An error occurred while processing the message</faultstring>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

CORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault xmlns:c="http://example.org/faultcodes">
      <faultcode>c:ProcessingError</faultcode>
      <faultstring>An error occured while processing the message</faultstring>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

CORRECT: 

<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
  <soap11:Header/>
  <soap11:Body>
    <soap11:Fault>
      <faultcode>soap11:Server</faultcode>
      <faultstring>An error occured while processing the message</faultstring>
    </soap11:Fault>
  </soap11:Body>
</soap11:Envelope>

3.5 Use of SOAP in HTTP

This section of the Profile incorporates the following specifications by reference:

While SOAP itself is not transport specific, this Profile focuses on its use with HTTP and makes no requirements on the use of any other transport. Other profiles might be developed to focus on the particulars of other transports, but that is out of scope for this Profile. With respect to compliance to this Profile, any requirement that mentions the HTTP transport applies only when HTTP is being used. Any requirement that is not specific to HTTP (i.e. does not mention HTTP specifically) applies toward conformance regardless of the transport mechanism being used.

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

For this section, the conformance criteria for the use of HTTP as a transport protocol are specified in Section 2.3 .

3.5.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 When HTTP is used as the transport, a MESSAGE MUST be sent using either HTTP/1.1 or HTTP/1.0. HTTP-TRANSPORT TESTABLE BP1002

R1140 When HTTP is used as the transport, a MESSAGE SHOULD be sent using HTTP/1.1. HTTP-TRANSPORT TESTABLE BP1001

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.5.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. HTTP-TRANSPORT TESTABLE BP1264

R1108 A MESSAGE MUST NOT use the HTTP Extension Framework (RFC2774). HTTP-TRANSPORT TESTABLE BP1262

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.5.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 soap11:Envelope .

R1109 If present, the values of the following parameters - type, start-info, SOAPAction, and boundary - on the Content-Type MIME header field-value in a request MESSAGE MUST be a quoted string. C HTTP-TRANSPORT TESTABLE BP1006

R1119 A RECEIVER MAY respond with a fault if the applicable parameters on the Content-Type MIME header field-value in a message are not quoted. C HTTP-TRANSPORT NOT_TESTED

R1127 A RECEIVER MUST NOT rely on the value of the SOAPAction HTTP header to correctly process the message. SOAP12 HTTP-TRANSPORT NOT_TESTABLE

For example,

CORRECT:

A WSDL Description that has:

<wsoap11:operation soapAction="http://example.org/foo"/>

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

SOAPAction: "http://example.org/foo"

CORRECT:

A WSDL Description that has:

<wsoap11:operation/>

or

<wsoap11:operation soapAction=""/>

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

SOAPAction: ""

3.5.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. HTTP-TRANSPORT NOT_TESTABLE

R1111 An INSTANCE SHOULD use a "200 OK" HTTP status code on a response message that contains an envelope that is not a fault. HTTP-TRANSPORT TESTABLE BP1100