Copyright © 2002-2007 by The Web Services-Interoperability Organization (WS-I) and Certain of its Members. All Rights Reserved.
This document defines the WS-I Basic Profile 2.0, consisting of a set of non-proprietary Web services specifications, along with clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability
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.
Note: The working group believes that the technical work related to the prose aspects of the profile is complete (barring any feedback). However, the technical work on the in-lined test assertions is still very much a work in progress.
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.
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.
1. Introduction
1.1. Relationships to Other Profiles
1.2. Guiding Principles
1.3. Compatibility with Basic Profile 1.1 and 1.2
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. Message Serialization
3.1.1. XML Envelope Serialization
3.1.2. Unicode BOMs
3.1.3. XML Declarations
3.1.4. Character Encodings
3.1.5. XOP Encoded Messages
3.2. SOAP Envelopes
3.2.1. SOAP Envelope Structure
3.2.2. SOAP Body Namespace Qualification
3.2.3. Disallowed Constructs
3.2.4. xsi:type Attributes
3.2.5. SOAP 1.2 attributes on SOAP 1.2 elements
3.3. SOAP Processing Model
3.3.1. SOAP Fault Processing
3.4. SOAP Faults
3.4.1. Identifying SOAP Faults
3.4.2. SOAP Defined Faults Action URI
3.4.3. SOAP MustUnderstand or VersionMismatch fault Transmission
3.5. Treatment of URIs in SOAP
3.5.1. Comparison of URI values of SOAP Information Items
3.6. Support for WS-Addressing
3.6.1. Requiring WS-Addressing SOAP headers
3.6.2. NotUnderstood block in MustUnderstand Fault on WS-Addressing SOAP headers
3.7. Use of WS-Addressing MAPs
3.7.1. Use of wsa:Action and WS-Addressing 1.0 - Metadata
3.7.2. Understanding WS-Addressing SOAP Header Blocks
3.7.3. Valid Values for action Parameter on the Content-Type MIME header When WS-Addressing is Used
3.8. Use of SOAP in HTTP
3.8.1. HTTP Protocol Binding
3.8.2. Parameters on the Content-Type MIME Header
3.8.3. HTTP Success Status Codes
3.8.4. HTTP Redirect Status Codes
3.8.5. HTTP Cookies
3.8.6. Use of Non-Anonymous Reponse EPR in a Request-Response Operation
3.9. Use of URIs in SOAP
3.9.1. Use of SOAP-defined URIs
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 wsoap12 Elements
4.7.11. Consistency of portType and binding Elements
4.7.12. Enumeration of Faults
4.7.13. Type and Name of SOAP Binding Elements
4.7.14. name Attribute on Faults
4.7.15. Omission of the use Attribute
4.7.16. Default for use Attribute
4.7.17. Consistency of Envelopes with Descriptions
4.7.18. Response Wrappers
4.7.19. Part Accessors
4.7.20. Namespaces for Children of Part Accessors
4.7.21. Required Headers
4.7.22. Allowing Undescribed Headers
4.7.23. Ordering Headers
4.7.24. Describing action Parameter on the Content-Type MIME Header
4.7.25. SOAPAction HTTP Header
4.7.26. SOAP Binding Extensions
4.8. Use of @soapActionRequired in WSDL 1.1 SOAP 1.2 Binding
4.9. Use of XML Schema
4.10. WS-Addresing 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
This document defines the WS-I Basic Profile 2.0 (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.
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.
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.
The Basic Profile 2.0 is the first version of the WS-I Basic Profile that changes the version of SOAP in the profile scope from SOAP 1.1 to the W3C SOAP 1.2 Recommendation. As such, clients, servers and the artifacts that comprise a Basic Profile 1.0, 1.1 or 1.2 conformant application are inherently incompatible with an application that is conformant with the Basic Profile 2.0. However, in general, the Basic Profile WG members have tried to preserve in the Basic Profile 2.0 as much consistency with the guidance and constraints of the Basic Profile 1.0, 1.1 and 1.2 as possible. This has been in part facilitated by the fact that the WG tried to remain consistent in the guidance and constraints of the original Basic Profile with the decisions that were being made in the context of the W3C XML Protocols WG as they were concurrently working on the SOAP 1.2 specificatons. For the most part, issues that were resolved in the context of the development of the Basic Profile 1.0, 1.1 and 1.2 were not revisited.
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.
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 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.
This document is identified by a name (in this case, Basic Profile) and a version number (here, 2.0). 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.
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.
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).
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:
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.
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:
The conformance claim URI for this Profile is " http://ws-i.org/profiles/basic/2.0 " .
This section of the Profile incorporates the following specifications by reference, and defines extensibility points within them:
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.2 defines an XML structure for transmitting messages, the envelope. The Profile places the following constraints on the use and serialization of the soap:Envelope element and its content:
R9701 An ENVELOPE MUST be serialized as XML 1.0. TESTABLE_NOT_XPATH BP1019
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 NOT_TESTABLE BP3999
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 NOT_TESTABLE BP3999
The Profile requires XML processors to support the "UTF-8" and "UTF-16" character encodings, in order to aid interoperability.
To improve interoperabilitry, the "charset" parameter of Content-Type HTTP header field must be used to determine the correct character encoding of the message.
R1012 An ENVELOPE MUST be serialized using either UTF-8 or UTF-16 character encoding. TESTABLE BP1018
R1018 A SIMPLE_SOAP_MESSAGE MUST indicate the correct character encoding, using the "charset" parameter. C TESTABLE BP1018
R1019 A RECEIVER MUST ignore the encoding pseudo-attribute of the envelope's XML declaration. NOT_TESTABLE BP3999
There is pervasive implementation that is apparently encoding the action parameter as a separate parameter of the enclosing MIME multipart/related
entity body's Content-Type header. The multipart/related media type specification does not include an action parameter, though it does permit
extensibility. Thus, the action parameter on the multipart/related
Content-Type header has no defined semantic. The correct encoding is to include
the action parameter inside the start-info parameter of the enclosing MIME multipart/related entity body as well as inside the type parameter of the root part.
R1020
A XOP_ENCODED_MESSAGE MUST include the start-info parameter in the
Content-Type header of the enclosing multipart/related MIME entity body.
R1021
A XOP_ENCODED_MESSAGE SHOULD include the full value of the type parameter
from the root entity body part inside the start-info parameter of the enclosing
multipart/related MIME entity body part's Content-Type header.
R1022
A RECEIVER MUST accept a XOP encoded message that has the action parameter,
associated with the SOAP message, encoded inside the
start-info parameter on the Content-Type header of the enclosing multipart/related
MIME entity body.
R1023
A RECEIVER MAY accept a XOP encoded message that has the action parameter,
associated with the SOAP message, encoded as a separate parameter on the
Content-Type header of the enclosing multipart/related
MIME entity body.
INCORRECT:
MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
type="application/xop+xml";
start="<mymessage.xml@example.org>";
start-info="application/soap+xml"; action="ProcessData"
--MIME_boundary
Content-Type: application/xop+xml;
charset=UTF-8;
type="application/soap+xml; action=\"ProcessData\""
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>
[...]
CORRECT:
MIME-Version: 1.0
Content-Type: Multipart/Related;boundary=MIME_boundary;
type="application/xop+xml";
start="<mymessage.xml@example.org>";
start-info="application/soap+xml; action=\"ProcessData\""
Content-Description: A SOAP message with my pic and sig in it
--MIME_boundary
Content-Type: application/xop+xml;
charset=UTF-8;
type="application/soap+xml; action=\"ProcessData\""
Content-Transfer-Encoding: 8bit
Content-ID: <mymessage.xml@example.org>
[...]
This section of the Profile incorporates the following specifications by reference:
SOAP 1.2 defines a structure for composing messages, the envelope. The Profile mandates the use of that structure, and places the following constraints on its use:
R9980 An ENVELOPE MUST conform to the structure specified in SOAP Version 1.2 Part 1, Section 5, "SOAP Envelope" (subject to amendment by the Profile). TESTABLE BP1600
R9981
An ENVELOPE MUST have exactly zero or one child elements of
the
soap:Body
element.
TESTABLE
BP9991
While the combination of R2201 and R2210 (below) clearly
imply that there may be at most one child element of the
soap:Body
, there is no explicit requirement in the Profile that
articulates this constraint, leading to some confusion.
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.
TESTABLE
BP1202
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 5 of SOAP 1.2.
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 TESTABLE BP1007
R1009 An ENVELOPE MUST NOT contain Processing Instructions. C TESTABLE BP1208
R1033 An ENVELOPE SHOULD NOT contain the namespace declaration xmlns:xml="http://www.w3.org/XML/1998/namespace". C TESTABLE BP1033
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).
NOT_TESTABLE
BP3999
R1032
The
soap:Envelope
,
soap:Header
, and
soap:Body
elements in an ENVELOPE MUST NOT have attributes in the
namespace
"http://www.w3.org/2003/05/soap-envelope"
.
TESTABLE
BP1032
This section of the Profile incorporates the following specifications by reference:
SOAP 1.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:
Note that there may be valid reasons (such as security considerations) why a fault might not be transmitted.
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.
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. NOT_TESTABLE feedme
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. NOT_TESTABLE BP3999
Note that there may be valid reasons (such as security considerations) why a fault may not be transmitted.
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.
TESTABLE
BP3999
WS-Addressing provides the URI http://www.w3.org/2005/08/addressing/soap/fault for "SOAP defined faults". However, it only recommends, rather than mandate its use for the SOAP 1.2 defined MustUnderstand and VersionMismatch faults. This Profile mandates the use of the WS-Addressing defined wsa:Action value for SOAP 1.2 defined MustUnderstand and VersionMismatch faults, for interoperability.
R1035
An ENVELOPE MUST use the
http://www.w3.org/2005/08/addressing/soap/fault URI as the
value for the
wsa:Action
element when present, for either of the SOAP 1.2 defined
VersionMismatch and MustUnderstand faults.
TESTABLE
BP1035
WS-Addressing does not violate the SOAP processing model, but in fact plays within the rules defined by the SOAP processing model. Thus, regardless of the value of the wsa:ReplyTo or wsa:FaultTo, should a message generate either a SOAP MustUnderstand or VersionMismatch fault, that fault SHOULD be transmitted to the sender of the message generating such fault on the HTTP response message.
Note that this is a SHOULD requirement, as there may be valid reasons why the fault is not transmitted at all.
R1036 A RECEIVER that receives a SOAP envelope that generates either a SOAP MustUnderstand or VersionMismatch fault SHOULD transmit such a fault on the HTTP response message, regardless of the value of the wsa:ReplyTo or wsa:FaultTo SOAP headers present in the message. TESTABLE BP3999
R1037 A RECEIVER, for the purposes of comparison of URI values of information items defined by the SOAP 1.2 specification, MUST treat the computed absolute URI values as strings (see RFC3986). TESTABLE feedme
WS-Addressing is a part of core Web services infrastructure. To facilitate interoperability and to provide a common baseline, this profile requires compliant clients and services to provide support for WS-Addressing Core, WS-Addressing SOAP Binding and WS-Addressing Metadata.
Support for WS-Addressing by a specific "service" is optional. However, a service may require the use of WS-Addressing, in which case, for successful interaction with that service, a client will need to support it.
R1040 If an endpoint requires use of WS-Addressing by use of a wsam:Addressing policy assertion, an ENVELOPE sent by a SENDER MUST carry all required WS-Addressing SOAP headers. TESTABLE feedme
R1041 An ENVELOPE that is a MustUnderstand SOAP fault, sent from an endpoint that has a policy alternative containing the wsam:Addressing assertion attached to its WSDL endpoint subject, MUST NOT contain a NotUnderstood SOAP header block with the qname attribute value that identifies a WS-Addressing defined SOAP header block. TESTABLE feedme
This section of the Profile incorporates the following specifications by reference:
When using WS-Addressing, the Profile requires conformance to WS-Addressing 1.0 - Core, WS-Addressing 1.0 - SOAP Binding and WS-Addressing 1.0 Metadata, Section 5.1 and places the following additional constraints.
WS-Addressing 1.0 - Metadata, Section 5.1 defines additional constraints on the cardinality of WS-Adressing Message Addressing Properties defined in WS-Addressing 1.0 - Core. These constraints are defined for every message involved in WSDL 1.1 transmission primitives. The Profile requires conformance to this section when WS-Addressing is used in conjunction with WSDL 1.1 description.
R1142 An ENVELOPE that includes a wsa:Action SOAP header block and which is described using WSDL 1.1 description MUST conform to WS-Addressing 1.0 - Metadata, Section 5.1. C TESTABLE BP1142
WS-Addressing 1.0 -- SOAP Binding defines multiple SOAP header blocks (wsa:To, wsa:From, wsa:ReplyTo, wsa:FaultTo, wsa:Action, wsa:MessageID, and wsa:RelatesTo). These SOAP header blocks are part of the same module. A SOAP node that conforms to the Profile understands all of these SOAP header blocks (when it understands WS-Addressing) or none at all (when it does not understand WS-Addressing).
R1143 When a message contains multiple WS-Addressing SOAP header blocks with at least one of those header blocks containing a soap:mustUnderstand='1' attribute, then a RECEIVER MUST understand all the WS-Addressing SOAP header blocks or none of them. C Compat NOT_TESTABLE BP3999
There may be some confusion as regards to the range of
valid values for the
action
parameter on the
Content-Type
MIME header when WS-Addressing is used.
When composed with WS-Addressing, the value of the
action
parameter, if present, is limited to the absolute URI that
matches the value specified for
wsa:Action
. The
action
parameter is optional and is therefore not required to be
present on the header. This is useful, for example, when
the value of
wsa:Action
is sensitive and is therefore encrypted.
R1144
When
wsa:Action
MAP is present in an envelope, the value of the
action
parameter, if present, on the
Content-Type
MIME header of the MESSAGE MUST be an absolute URI that has
the same value as the value of the
wsa:Action
MAP.
TESTABLE
BP1144
This section of the Profile incorporates the following specifications by reference:
SOAP 1.2 defines a single protocol binding, for HTTP. The Profile mandates the use of that binding, and places the following constraints on its use:
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. TESTABLE BP1002
R1140 A MESSAGE SHOULD be sent using HTTP/1.1. TESTABLE feedme
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."
Testing has demonstrated that requiring parameters on the
Content-Type
MIME 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.
R1109
Parameters on the
Content-Type
MIME header field-value in a request MESSAGE MUST be a
quoted string.
C
TESTABLE
BP1006
R1119
A RECEIVER MAY respond with a fault if the parameters on the
Content-Type
MIME header field-value in a message is not quoted.
C
NOT_TESTABLE
BP1999
R1127
A RECEIVER MUST NOT rely on the value of the
action
parameter on the
Content-Type
MIME header field-value to correctly process the message.
NOT_TESTABLE
BP1999
CORRECT:
A WSDL Description that has:
<wsoap12:operation
soapAction="http://example.org/foo"/>
results in a message with an action parameter on the Content-Type MIME header field-value set to:
"http://example.org/foo"
CORRECT:
A WSDL Description that has:
<wsoap12:operation />
Or
<wsoap12:operation soapAction="" />
must not results in a message with an action parameter on the Content-Type MIME header field-value.
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. NOT_TESTABLE BP1999
R1111 An INSTANCE SHOULD use a "200 OK" HTTP status code on a response message that contains an envelope that is not a fault. TESTABLE BP1100
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. TESTABLE BP1101
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.
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. NOT_TESTABLE BP1999
R1131 A CONSUMER MAY automatically redirect a request when it encounters a "307 Temporary Redirect" HTTP status code in a response. NOT_TESTABLE BP1999
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.
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.2 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"). NOT_TESTABLE BP1999
R1122 An INSTANCE using Cookies SHOULD conform to RFC2965. NOT_TESTABLE BP1999
R1121 An INSTANCE SHOULD NOT require consumer support for Cookies in order to function correctly. NOT_TESTABLE BP1999
R1123 The value of the cookie MUST be considered to be opaque by the CONSUMER. NOT_TESTABLE BP1999
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).
WS-Addressing response EPR (
wsa:FaultTo
and
wsa:ReplyTo
) values affect how and where the response message is sent
in a Request-Response WSDL transmission primitive.
Specifically:
wsa:Address
property, the response is sent in the entity body of the
HTTP response message.
wsa:Address
property:
wsa:FaultTo
for faults and
wsa:ReplyTo
for non-fault messages) response EPR. Both the HTTP
connections, for the request message and response
message as described by the WSDL Request-Response
operation, use the SOAP 1.2 Request-Response MEP and
the SOAP HTTP binding. SOAP 1.2 Request-Response MEP
does not require that the SOAP MEP Response be a
SOAP envelope, it can be a binding-specific message.
Such an optional response is indicated in the SOAP
HTTP binding using the HTTP status 202. The HTTP
response in this case may or may not contain a SOAP
envelope. If an envelope is present in the HTTP
response with a status code of 202, it is not
considered to be the WSDL-level response. The
request message and the response message, as
described by the WSDL Request-Response operation,
are sent in the entity-body of the HTTP request in
two separate connections.
R1150 If an INSTANCE sends a MustUnderstand or VersionMismatch fault generated as a result of an invocation of a Request-Response WSDL operation, it MUST send that fault in the entity body of HTTP response using the same HTTP connection as the request message of that operation. TESTABLE BP1150
R1151
If an INSTANCE sends a response which is neither a
MustUnderstand nor VersionMismatch fault as a result of an
invocation of a Request-Response WSDL operation and the
response EPR has a non-anonymous
wsa:Address
value, then the response MUST be sent in the entity body of
an HTTP request in a separate HTTP connection specified by
the response EPR using the SOAP 1.2 HTTP binding.
TESTABLE
BP1151
This section of the Profile incorporates the following specifications by reference:
SOAP 1.2 uses URIs as identifiers. For example, the
role
attribute value is a URI that identify the SOAP node to
which a particular header block is targeted. The Profile
places the following constraints on the use of such URI
values:
A SOAP 1.2 defined URI, such as the role value "http://www.w3.org/2003/05/soap-envelope/role/next", in SOAP 1.2, is a simple formatted string.
R1160 A RECEIVER, for the purposes of comparison of URI values of information items defined by the SOAP 1.2 specification, MUST treat the computed absolute URI values as strings (see RFC3986). NOT_TESTABLE BP1999
The Profile uses Web Services Description Language (WSDL) to enable the description of services as sets of endpoints operating on messages.
This section of the Profile incorporates the following specifications by reference, and defines extensibility points within them: