WS-I

Basic Profile Version 1.1

Working Group Draft

Date: 2003/12/06 07:48:25

This revision:

http://www.ws-i.org/Profiles/Basic/2003-12/BasicProfile-1.1.htm

Editors:

Keith Ballinger, Microsoft (1.0)

David Ehnebuske, IBM (1.0)

Martin Gudgin, Microsoft (1.0)

Mark Nottingham, BEA Systems

Prasad Yendluri, webMethods (1.0)

Administrative contact:

secretary@ws-i.org

Copyright © 2002-2003 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 and amendments to those specifications which promote interoperability.

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.

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. Notational Conventions
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.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. SOAP Fault Structure
3.3.2. SOAP Fault Namespace Qualification
3.3.3. SOAP Fault Extensibility
3.3.4. SOAP Fault Language
3.3.5. SOAP Custom Fault Codes
3.3.6. Identifying SOAP Faults
3.4. Use of SOAP in HTTP
3.4.1. HTTP Protocol Binding
3.4.2. HTTP Methods and Extensions
3.4.3. SOAPAction Header Syntax
3.4.4. HTTP and TCP Ports
3.4.5. HTTP Success Status Codes
3.4.6. HTTP Redirect Status Codes
3.4.7. HTTP Client Error Status Codes
3.4.8. HTTP Server Error Status Codes
3.4.9. HTTP Cookies
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. WSDL and the Unicode BOM
4.2.8. Acceptable WSDL Character Encodings
4.2.9. Namespace Coercion
4.2.10. WSDL documentation Element
4.2.11. 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. 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. Default for use Attribute
4.7.6. Multiple Bindings for portType Elements
4.7.7. Wire Signatures for Operations
4.7.8. Multiple Ports on an Endpoint
4.7.9. Child Element for Document-Literal Bindings
4.7.10. One-Way Operations
4.7.11. Namespaces for soapbind Elements
4.7.12. Consistency of portType and binding Elements
4.7.13. Describing headerfault Elements
4.7.14. Enumeration of Faults
4.7.15. Type and Name of SOAP Binding Elements
4.7.16. name Attribute on Faults
4.7.17. Omission of the use Attribute
4.7.18. Consistency of Envelopes with Descriptions
4.7.19. Response Wrappers
4.7.20. Namespace for 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 I: Referenced Specifications
Appendix II: Extensibility Points
Appendix III: 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 to 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, 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, so that a profile for attachments could be composed with the Basic Profile 1.1.

This Profile is intended to supersede Basic Profile 1.0.

The manner in which this profile supersedes BP 1.0 is currently under discussion.

A combined claim of conformance to both the Basic Profile 1.1 and the Simple SOAP Binding Profile 1.0 should be equivalent to a claim of conformance to 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 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). 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.

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 the Profile defines conformance. See the Profile Conformance Framework for more information about conformance to WS-I profiles.

2.1 Conformance Requirements

Requirements state the criteria for conformance to the Profile. They typically refer to an existing specification and embody refinements, 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 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 has exactly one conformance target and one requirement level, to avoid ambiguity. Additional text may be included to illuminate requirements or group of requirements (e.g., rationale and examples); however, requirement statements alone should be considered in determining conformance.

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.

This Profile defines the following conformance targets:

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. The Profile's scope is initially 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 by the Profile as an extensibility point, such a mechanism or parameter is outside the Profile's scope, and its use or non-use is not relevant to conformance.

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. Also, specific uses of extensibility points may be further restricted by other profiles, to improve interoperability when used in conjunction.

This Profile's scope is defined by the referenced specifications in Appendix I, as refined by the extensibility points in Appendix II.

2.4 Claiming Conformance

Claims of conformance to the Profile can be made using the mechanisms described in the Profile Conformance Framework. Specifically, claims can be made using the following conformance attachment mechanisms, as long as the requirements in this profile associated with the listed targets have been met:

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

Generally, 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).

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.

Editors' note:There is still a need to turn the implied requirements in this section into actual Requirements.

3. Messaging

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

3.1 SOAP Envelopes

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

SOAP 1.1 defines a structure for transmitting 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.

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, these XML constructs are disallowed by section 3 of SOAP 1.1.

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

R1009 An ENVELOPE MUST NOT contain Processing Instructions. 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.org/soap/envelope/' >

  <soap:Body>

    <p:Process xmlns:p='http://example.org/Operations' />

  </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.org/soap/envelope/' >

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

  </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 elements are grandchildren 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. 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 envelopes except as required in order to indicate a derived type (see XML Schema Part 1: Structures, Section 2.6.1).

3.2 SOAP Processing Model

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

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 that they do not understand targeted at them.

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.

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.

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.

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.

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.

3.3 SOAP Faults

3.3.1 SOAP Fault Structure

A fault is an envelope 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 an ENVELOPE 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</faultactor>

  <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/exceptions' >

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

  <detail>

     <m:msg xmlns:m='http://example.org/faults/exceptions'>

         There were <b>lots</b> of elements in the message that I did not understand

     </m:msg>

     <m:Exception xmlns:m='http://example.org/faults/exceptions'>

       <m:ExceptionType>Severe</m:ExceptionType>

     </m:Exception>

   </detail>

</soap:Fault>

3.3.2 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 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:faultstring>

  <soap:faultactor>http://example.org/someactor</soap:faultactor>

  <soap:detail>

      <m:msg xmlns:m='http://example.org/faults/exceptions'>

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

  <detail>

      <m:msg xmlns:m='http://example.org/faults/exceptions'>

          There were <b>lots</b> of elements in the message that

          I did not understand

      </m:msg>

  </detail>

</soap:Fault>

3.3.3 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.4 SOAP Fault Language

Faultstrings are human-readable indications of the n ature 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.

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

3.3.5 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 one of the fault codes defined in SOAP 1.1 or a namespace qualified fault code.

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

  </faultstring>

</soap:Fault>

3.3.6 Identifying SOAP Faults

Some consumer implementations 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.

R1107 A RECEIVER MUST interpret an envelope containing only a soap:Fault element as a fault.

3.4 Use of SOAP in HTTP

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

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

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 in a message 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:

A WSDL Description that has:

<soapbind:operation />

or

<soapbind:operation soapAction="" />

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

SOAPAction: ""

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

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

3.4.6 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.7 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 a response that indicates a problem with the format of a request.

R1114 An INSTANCE SHOULD use a "405 Method not Allowed" HTTP status code if a HTTP request message's method is not "POST".

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.8 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.9 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.

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