SOAP Binding

The SOAP extensibility elements for binding abstract WSDL messages to SOAP messages fall into several sections. Each section signifies how the binding should occur. At the binding level, the configuration applies to the entire port type. At the operation level, the configuration applies only to the operation. At the message level, the configuration applies to that particular message, regardless of whether the message is input or output.

The SOAP Binding Element

The purpose of the SOAP binding element is to indicate that the binding is bound to the SOAP protocol format: Envelope, Header and Body. This element makes no claim as to the encoding or format of the message (e.g. that it necessarily follows section 5 of the SOAP 1.1 specification).

The SOAP Binding Element Attributes

Property Description Required or Optional Example transport   Indicates to which transport of SOAP this binding corresponds. Optional http://schemas.xmlsoap.org/soap/http style   Indicates the default style of this particular SOAP binding. Optional rpc

The SOAP binding element MUST be present when using the SOAP binding. The following example illustrates the use of the SOAP binding element:

<definitions .... >
    <binding .... >
        <soap:binding transport="uri"? style="rpc|document"?>
    </binding>
</definitions>

The style attribute value is the default style attribute for each contained operation. If the style attribute is omitted, it is assumed to be "document".

The value of the required transport attribute indicates the transport to use to deliver SOAP messages. The URI value http://schemas.xmlsoap.org/soap/http corresponds to the HTTP binding in the SOAP specification. Other URIs may be used here to indicate other transports (such as SMTP, FTP, and so forth).

The SOAP Operation Element

The purpose of the SOAP operation element is to provide binding information from the abstract operation to the concrete SOAP operation.

The SOAP Operation Element Attributes

Property Description Required or Optional Example soapAction Indicates the soapAction that should be put into the HTTP header. Optional urn:someSoapAction style  Indicates the default style of this particular SOAP operation. Optional rpc

The following example illustrates the use of the SOAP operation element:

<definitions .... >
    <binding .... >
        <operation .... >
           <soap:operation soapAction="uri"? style="rpc|document"?>?
        </operation>
    </binding>
</definitions>

The style attribute indicates whether the operation is RPC-oriented (messages containing parameters and return values) or document-oriented (messages containing documents). This information may be used to select an appropriate programming model. The value of this attribute also affects the way in which the body of the SOAP message is constructed. If the attribute is not specified, it defaults to the value specified in the soap:binding element. If the soap:binding element does not specify a style, it is assumed to be "document".

The soapAction attribute specifies the value of the SOAPAction header for this operation. This URI value should be used directly as the value for the SOAPAction header. No attempt should be made to make a relative URI value absolute when making the request. For the HTTP protocol binding of SOAP, this value is required (it has no default value). For other SOAP protocol bindings, it MUST NOT be specified, and the soap:operation element can be omitted.

The SOAP Body Element

The purpose of the SOAP body element is to provide binding information from the abstract operation to the concrete SOAP operation.

The SOAP Body Element Attributes

Property Description Required or Optional Example parts Indicates the parts from the WSDL message that will be included in the body element. Optional part1 use Indicates how message parts are encoded in the SOAP body. Optional literal encodingStyle Indicates a particular encoding style to use. Optional http://someencodingstyle namespace Indicates the namespace of the wrapper element for RPC style messages. Optional urn:someNamespace

The following example illustrates the SOAP body element:

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </input>
           <output>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </output>
        </operation>
    </binding>
</definitions>

The optional parts attribute of type nmtokens indicates which parts appear somewhere within the SOAP Body portion of the message (other parts of a message may appear in other portions of the message, such as when SOAP is used in conjunction with the multipart/related MIME binding). If the parts attribute is omitted, then all parts defined by the message are assumed to be included in the SOAP Body portion.

The required use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message.

If use is encoded, then each message part references an abstract type using the type attribute. These abstract types are used to produce a concrete message by applying an encoding that is specified by the encodingStyle attribute. The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content that is not explicitly defined by the abstract types. If the referenced encoding style allows variations in its format (as does the SOAP encoding), then all variations MUST be supported ("reader makes right").

If use is literal, then each part references a concrete schema definition using either the element or type attribute. In the first case, the element referenced by the part will appear directly under the Body element (for document style bindings) or under an accessor element named after the message part (in RPC style). In the second, the type referenced by the part becomes the schema type of the enclosing element (Body for document style or part accessor element for RPC style).

For an example that illustrates "defining the contents of a composite Body using a type", see section 2.3.1. The value of the encodingStyle attribute may be used when the use is literal, to indicate that the concrete format was derived using a particular encoding (such as the SOAP encoding), but that only the specified variation is supported ("writer makes right").

The value of the encodingStyle attribute is a list of URIs, each separated by a single space. The URI's represent encodings used within the message, in order of most restrictive to least restrictive (exactly like the encodingStyle attribute defined in the SOAP specification).

The SOAP Fault Element

The fault element specifies the contents of SOAP Fault Details element. It is patterned after the body element.

The SOAP Fault Element Attributes

Property Description Required or Optional Example name Indicates the name of the part from the WSDL message that will be included in the fault element. Required part1 use Indicates how message parts will be encoded in the SOAP fault. Required literal encodingStyle Indicates a particular encoding style to use. Optional http://someencodingstyle namespace Indicates the namespace of the wrapper element for RPC style messages. Optional urn:someNamespace

The following example illustrates the SOAP fault element:

<definitions .... >
    <binding .... >
        <operation .... >
           <fault>*
               <soap:fault name="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?>
           </fault>
        </operation>
    </binding>
</definitions>

The name attribute relates the soap:fault to the wsdl:fault defined for the operation. The fault message MUST have a single part.

The use, encodingStyle and namespace attributes are all used in the same way as with Body, only style="document" is assumed, since faults do not contain parameters.

The SOAP Header and Headerfault Elements

The header and headerfault elements allow headers to be defined that are transmitted inside the Header element of the SOAP Envelope. It is not necessary to exhaustively list all headers that appear in the SOAP Envelope using header. For example, extensions to WSDL may imply specific headers should be added to the actual payload and it is not required to list those headers here.

The SOAP Header Element Attributes

Property Description Required or Optional Example message Indicates WSDL message that will be used in binding to the header element. Required part1 part Indicates the parts from the WSDL message that will be included in the header element. Required part1 use Indicates how message parts will be encoded in the SOAP header. Required literal encodingStyle Indicates a particular encoding style to use. Optional http://someencodingstyle namespace Indicates the namespace of the wrapper element for RPC style messages. Optional urn:someNamespace

The SOAP Headerfault Element Attributes

Property Description Required or Optional Example name Indicates WSDL message that will be used in binding to the headerfault element. Required part1 part Indicates the parts from the WSDL message that will be included in the headerfault element. Required part1 use Indicates how message parts will be encoded in the SOAP headerfault. Required literal encodingStyle Indicates a particular encoding style to use. Optional http://someencodingstyle namespace Indicates the namespace of the wrapper element for RPC style messages. Optional urn:someNamespace

The following example illustrates the SOAP header and headerfault elements:

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
             <soap:header message="qname" part="nmtoken" use="literal|encoded"
                          encodingStyle="uri-list"? namespace="uri"?>*
               <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?/>*
             <soap:header>                                
           </input>
           <output>
               <soap:header message="qname" part="nmtoken" use="literal|encoded"
                            encodingStyle="uri-list"? namespace="uri"?>*
                 <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                   encodingStyle="uri-list"? namespace="uri"?/>*
               <soap:header>                                
           </output>
        </operation>
    </binding>
</definitions>

The use, encodingStyle and namespace attributes are all used in the same way as with Body, only style="document" is assumed since headers do not contain parameters.

Together, the message attribute (of type QName) and the part attribute (of type nmtoken) reference the message part that defines the header type.

The optional headerfault elements which appear inside the header and have the same syntax as the header, allow specification of the header types used to transmit error information pertaining to the header, and defined by the header. The SOAP specification states that errors pertaining to headers must be returned in the headers. This mechanism allows specification of the format of such headers.