1. Introduction
The Web Services Description Language WSDL Version 2.0 (WSDL)
[WSDL 2.0 Core Language]
defines an XML language for describing network services as
collections of communication endpoints capable of exchanging
messages. WSDL service definitions provide documentation for
distributed systems and serve as a recipe for automating the
details involved in applications communication. This document
defines extensions for the WSDL 2.0 language:
WSDL 2.0 Primer [WSDL 2.0
Primer] is a non-normative document intended to provide
an easily understandable tutorial on the features of the WSDL
Version 2.0 specifications.
The Core Language [WSDL 2.0 Core
Language] of the WSDL 2.0 specification describes the
core elements of the WSDL language.
1.1 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
[IETF RFC 2119].
This specification uses a number of namespace prefixes
throughout; they are listed in Table 1-1.
Note that the choice of any namespace prefix is arbitrary and not
semantically significant (see [XML
Information Set]).
Namespace names of the general form "http://example.org/..." and
"http://example.com/..." represent application or context-dependent
URIs [IETF RFC 3986].
All parts of this specification are normative, with the
EXCEPTION of pseudo-schemas, examples, and sections explicitly
marked as "Non-Normative". Pseudo-schemas are provided for each
component, before the description of this component. They provide
visual help for the XML [XML 1.0]
serialization.
2. Predefined Message Exchange
Patterns
A node is an agent (section
2.3.2.2 Agent of the Web Services Architecture [Web Services Architecture]) that can transmit
and/or receive message(s) described in WSDL description(s) and
process them.
Note:
A node may be accessible via more than one physical address or
transport.
Web Services Description Language (WSDL) message exchange
patterns (hereafter simply 'patterns') define the sequence and of
abstract messages listed in an operation. Message exchange patterns
also define which other nodes send messages to, and receive
messages from, the service implementing the operation. WSDL message
exchange patterns describe the interaction at the abstract
(interface) level, which may be distinct from the pattern used by
the underlying protocol binding (e.g. SOAP Message Exchange
Patterns; section 5.11.3 Default
Binding Rules contains the default binding rules for the
selection of a SOAP 1.2 message exchange pattern based on the WSDL
message exchange pattern in use for the SOAP binding extension
defined in this specification in section 5. WSDL SOAP Binding Extension).
By design, WSDL message exchange patterns abstract out specific
message types. Patterns identify placeholders for messages, and
placeholders are associated with specific message types by the
operation using the pattern.
Unless explicitly stated otherwise, WSDL message exchange
patterns also abstract out binding-specific information like timing
between messages, whether the pattern is synchronous or
asynchronous, and whether the message are sent over a single or
multiple channels.
Like interfaces and operations, WSDL message exchange patterns
do not exhaustively describe the set of messages exchanged between
a service and other nodes; by some prior agreement, another node
and/or the service may send other messages (to each other or to
other nodes) that are not described by the pattern. For instance,
even though a pattern may define a single message sent from a
service to one other node, the Web Service may multicast that
message to other nodes.
To maximize reuse, WSDL message exchange patterns identify a
minimal contract between other parties and Web Services, and
contain only information that is relevant to both the Web Service
and another party.
This specification defines several message exchange patterns for
use with WSDL Version 2.0 Part 1: Core Language
[WSDL 2.0 Core
Language].
2.1 Template for
Message Exchange Patterns
New Message Exchange Patterns may be defined by any organization
able and willing to do so. It is recommended that the patterns use
the general template provided here, after examination of existing
predefined patterns.
2.1.1
Pattern Name
This pattern consists of [number] message[s, in order] as
follows:
[enumeration, specifying, for each message] A[n optional]
message:
-
indicated by a
Interface Message Reference component whose {message
label} is "[label]" and direction is "[direction]"
-
[received from|sent to] ['some' if first mention] node [node
identifier]
This pattern uses the rule [fault ruleset reference].
An operation using this message exchange pattern has a {message
exchange pattern} property with the value "[pattern IRI]".
Note: In the template, the bracketed items indicate a
replacement operation. Substitute the correct terms for each
bracketed item.
Note: the "received from" and "sent to" are always from the
point of view of the service, and participating nodes other than
the service are implicitly identified as the originators of or
destinations for messages in the exchange.
2.2 Fault
Propagation Rules
WSDL patterns specify their fault propagation model using
standard rulesets to indicate where faults may occur. The most
common patterns for fault propagation are defined here, and
referenced by patterns later in the document. "Propagation" is
defined as a best-effort attempt to transmit the fault message to
its designated recipient.
WSDL patterns specify propagation of faults, not their
generation. Nodes which generate a fault MUST attempt to propagate
the faults in accordance with the governing ruleset, but it is
understood that any delivery of a network message is best effort,
not guaranteed. The rulesets establish the direction of the fault
message and the fault recipient, they do not provide reliability or
other delivery guarantees. When a fault is generated, the
generating node MUST attempt to propagate the fault, and MUST do so
in the direction and to the recipient specified by the ruleset.
However, extensions or binding extensions MAY modify these
rulesets. For example, WS-Addressing [WSA
1.0 Core] defines a "FaultTo" address for messages,
which is used in lieu of the recipient nominated by the
ruleset.
Generation of a fault, regardless of ruleset, terminates the
exchange.
Binding extensions, features, or extension specifications may
override the semantics of a fault propagation ruleset, but this
practice is strongly discouraged.
2.2.1
Fault Replaces Message
Any message after the first in the pattern MAY be replaced with
a fault message, which MUST have identical direction. The fault
message MUST be delivered to the same target node as the message it
replaces, unless otherwise specified by an extension or binding
extension. If there is no path to this node, the fault MUST be
discarded.
2.2.2 Message
Triggers Fault
Any message, including the first in the pattern, MAY trigger a
fault message, which MUST have opposite direction. The fault
message MUST be delivered to the originator of the triggering
message, unless otherwise specified by an extension of binding
extension. Any node MAY propagate a fault message, and MUST not do
so more than once for each triggering message. If there is no path
to the originator, the fault MUST be discarded.
2.2.3 No Faults
No faults may be propagated.
2.3 Message Exchange
Patterns
WSDL patterns are described in terms of the WSDL component
model, specifically the
Interface Message Reference and
Interface Fault Reference components.
2.3.1 In-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.2.3 No
Faults.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/in-only".
2.3.2 Robust
In-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.2.2
Message Triggers Fault.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/robust-in-only".
2.3.3 In-Out
This pattern consists of exactly two messages, in order, as
follows:
-
A message:
-
A message:
This pattern uses the rule 2.2.1
Fault Replaces Message.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/in-out".
2.3.4
In-Optional-Out
This pattern consists of one or two messages, in order, as
follows:
-
A message:
-
An optional message:
This pattern uses the rule 2.2.2
Message Triggers Fault.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/in-opt-out".
2.3.5 Out-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.2.3 No
Faults.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/out-only".
2.3.6 Robust
Out-Only
This pattern consists of exactly one message as follows:
-
message:
This pattern uses the rule 2.2.2
Message Triggers Fault.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/robust-out-only".
2.3.7 Out-In
This pattern consists of exactly two messages, in order, as
follows:
-
A message:
-
A message:
This pattern uses the rule 2.2.1
Fault Replaces Message.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/out-in".
2.3.8
Out-Optional-In
This pattern consists of one or two messages, in order, as
follows:
-
A message:
-
An optional message:
This pattern uses the rule 2.2.2
Message Triggers Fault.
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/2005/08/wsdl/out-opt-in".
2.4 Security
Considerations
Note that many of the message exchange patterns defined above
describe responses to an initial message (either a normal response
message or a fault.)
Such responses may be used in attempts to disrupt, attack, or
map a network, host, or services. When such responses are directed
to an address other than that originating the initial message, the
source of an attack may be obscured, or blame laid on a third
party, or may enable or exacerbate denial-of-service attacks.
Security mechanisms addressing such attacks may prevent the
delivery of response messages to the receiving node. Conformance to
the message exchange pattern is measured prior to the application
of these security mechanisms.
4. Predefined Operation
Styles
This section defines
operation styles used by serialization formats to place
constraints on Interface Operations bound.
4.1 RPC Style
The RPC style is selected by assigning to an
Interface Operation component's {style}
property the value "http://www.w3.org/2005/08/wsdl/style/rpc".
In order to conform with the specification for the RPC style, an
Interface Operation component MUST obey the constraints listed
below. Furthermore, if the wrpc:signature extension is
used, the corresponding attribute information item MUST be
valid according to the schema for the extension and additionally
MUST obey the constraints listed in 4.1.1
wrpc:signature Extension and 4.1.2 XML
Representation of the wrpc:signature Extension.
The RPC style MUST NOT be used for
Interface Operation components whose {message
exchange pattern} property has a value other than
"http://www.w3.org/2005/08/wsdl/in-only" or
"http://www.w3.org/2005/08/wsdl/in-out".
The RPC style places restrictions for Remote Procedure
Call-types of interactions. When this value is used, the associated
messages MUST conform to the rules below, described using XML
Schema [XML Schema
Structures]. Note that operations containing messages
described by other type systems may also indicate use of the RPC
style, as long as they are constructed in such a way as to follow
these rules.
If the
Interface Operation component uses a {message
exchange pattern} for which there is no output element, i.e.
"http://www.w3.org/2005/08/wsdl/in-only", then the conditions
stated below that refer to output elements MUST be considered to be
implicitly satisfied.
-
The content model of input and output {element
declaration} elements MUST be defined using a complex type that
contains a sequence from XML Schema.
-
The input sequence MUST only contain elements and element
wildcards. It MUST NOT contain other structures such as xs:choice.
The input sequence MUST NOT contain more than one element wildcard.
The element wildcard, if present, MUST appear after any
elements.
-
The output sequence MUST only contain elements. It MUST NOT
contain other structures such as xs:choice.
-
The sequence MUST contain only local element children. Note that
these child elements MAY contain the following attributes:
nillable, minOccurs and maxOccurs.
-
The local name of input element's QName MUST be the same as the
Interface Operation component's name.
-
Input and output elements MUST both be in the same
namespace.
-
The complex type that defines the body of an input or an output
element MUST NOT contain any local attributes. Extension attributes
are allowed for purposes of managing the message infrastructure
(e.g. adding identifiers to facilitate digitally signing the
contents of the message). They must not be considered as part of
the application data that is conveyed by the message. Therefore,
they are never included in an RPC signature (see 4.1.1
wrpc:signature Extension).
-
If elements with the same qualified name appear as children of
both the input and output elements, then they MUST both be declared
using the same named type.
-
The input or output sequence MUST NOT contain multiple children
elements declared with the same name.
4.1.1
wrpc:signature Extension
The wrpc:signature extension attribute
information item MAY be used in conjunction with the RPC style
to describe the exact signature of the function represented by an
operation that uses the RPC style.
When present, the wrpc:signature extension
contributes the following property to the
Interface Operation component it is applied to:
-
{rpc signature}
REQUIRED. A list of pairs (q, t) whose first component is
of type xs:QName and whose second component is of type
xs:token. Values for the second component MUST be chosen
among the following four: "#in", "#out", "#inout" "#return".
The value of the {rpc signature}
property MUST satisfy the following conditions:
-
The value of the first component of each pair (q, t)
MUST be unique within the list.
-
For each child element of the input and output messages of the
operation, a pair (q, t) whose first component q
is equal to the qualified name of that element MUST be present in
the list, with the caveat that elements that appear with
cardinality greater than one MUST be treated as a single
element.
-
For each pair (q, #in), there MUST be a child element
of the input element with a name of q and there MUST NOT
be a child element of the output element with the same name.
-
For each pair (q, #out), there MUST be a child element
of the output element with a name of q and there MUST NOT
be a child element of the input element with the same name.
-
For each pair (q, #inout), there MUST be a child
element of the input element with a name of q and there
MUST be a child element of the output element with the same name.
Furthermore, those two elements MUST have the same type.
-
For each pair (q, #return), there MUST be a child
element of the output element with a name of q and there
MUST NOT be a child element of the input element with the same
name.
The function signature defined by a wrpc:signature
extension is determined as follows:
-
Start with the value of the {rpc signature}
property, a (possibly empty) list of pairs of this form:
[(q0, t0), (q1, t1), ...]
-
Filter the elements of this list into two lists, the first one
(L1) comprising pairs whose t component is one of
{#in, #out, #inout}, the second (L2) pairs whose
t component is #return. During the composition of
L1 and L2, the relative order of members in the
original list MUST be preserved.
For ease of visualization, let's denote the two lists as
(L1) [(a0,
u0), (a1, u1),...]
and
(L2) [(r0,
#return), (r1, #return),...]
respectively.
-
Then, if the input sequence ends with an element wildcard, the
formal signature of the function is
f([d0] a0, [d1] a1, ..., rest) =>
(r0, r1, ...)
where rest is a formal parameter representing the
elements in the input message matched by the element wildcard.
Otherwise the formal signature of the function is
f([d0] a0, [d1] a1, ...) => (r0,
r1, ...)
i.e.
-
the list of formal arguments to the function is [a0, a1,
...];
-
the direction d of each formal argument a is
one of [in], [out], [inout], determined
according to the value of its corresponding u token;
-
the list of formal return parameters of the function is [r0,
r1, ...];
-
each formal argument and formal return parameter is typed
according to the type of the child element identified by it (unique
per the conditions given above).
Note:
The wrpc:signature extension allows the
specification of multiple return values for an operation. Several
popular programming languages support multiple return values for a
function. Moreover, for languages who do not, the burden on
implementors should be small, as typically multiple return values
will be mapped to a single return value of a structure type (or its
closest language-specific equivalent).
4.1.2 XML
Representation of the wrpc:signature Extension
The XML representation for the RPC signature extension is an
attribute information item with the following Infoset
properties:
The type of the name attribute information
item is a list type whose item type is the union of the
xs:QName type and the subtype of the xs:token
type restricted to the following four values: "#in", "#out",
"#inout", "#return". See Example
4-1 for a definition of this type.
Additionally, each even-numbered item (0, 2, 4, ...) in the list
MUST be of type xs:QName and each odd-numbered item (1, 3,
5, ...) in the list MUST be of the subtype of xs:token
described in the previous paragraph.
Example
4-1. Definition of the wrpc:signature extension
<xs:attribute name="signature" type="wrpc:signatureType"/>
<xs:simpleType name="signatureType">
<xs:list itemType="wrpc:signatureItemType"/>
</xs:simpleType>
<xs:simpleType name="signatureItemType">
<xs:union memberTypes="wrpc:directionToken xs:QName"/>
</xs:simpleType>
<xs:simpleType name="directionToken">
<xs:restriction base="xs:token">
<xs:enumeration value="#in"/>
<xs:enumeration value="#out"/>
<xs:enumeration value="#inout"/>
<xs:enumeration value="#return"/>
</xs:restriction>
</xs:simpleType>
4.1.3
wrpc:signature Extension Mapping To Properties of an
Interface Operation component
A wrpc:signature extension attribute
information item is mapped to the following property of the
Interface Operation component defined by its [owner].
Table 4-1. Mapping of a wrpc:signature
Extension to Interface Operation component Properties
| Property |
Value |
| {rpc signature} |
A list of (xs:QName, xs:token)
pairs formed by grouping the items present in the actual value of
the wrpc:signature attribute information item
in the order in which they appear there. |
4.2 IRI Style
The IRI style may be used for
Interface Operation components using a message exchange pattern
with an initial message.
The IRI style is selected by assigning the
Interface Operation component's {style}
property the value "http://www.w3.org/2005/08/wsdl/style/iri".
Use of this value indicates that XML Schema [XML Schema Structures] was used to define
the schema of the {element
declaration} property of the
Interface Message Reference component of the
Interface Operation component corresponding to the initial
message of the message exchange pattern. This schema MUST adhere to
the rules below:
-
The content model of this element is defined using a complex
type that contains a sequence from XML Schema.
-
The sequence MUST only contain elements. It MUST NOT contain
other structures such as xs:choice.
-
The sequence MUST contain only local element children. These
child elements MAY contain the nillable attribute, and
the attributes minOccurs and maxOccurs
MUST have a value 0 or 1.
-
The localPart of the element's QName MUST be the same as the
Interface Operation component's name.
-
The complex type that defines the body of the element or its
children elements MUST NOT contain any attributes.
-
The sequence MUST NOT contain multiple children elements
declared with the same local name.
-
If the children elements of the sequence are defined using an
XML Schema type, they MUST derive from xs:simpleType,
and MUST NOT be of the type or derive from xs:QName,
xs:NOTATION, xs:hexBinary or
xs:base64Binary.
4.3 Multipart
style
The Multipart style may be used for
Interface Operation components using a message exchange pattern
with an initial message.
The Multipart style is selected by assigning the
Interface Operation component's {style}
property the value
"http://www.w3.org/2005/08/wsdl/style/multipart".
Use of this value indicates that XML Schema [XML Schema Structures] was used to define
the schema of the {element
declaration} property of the
Interface Message Reference component of the
Interface Operation component corresponding to the initial
message of the message exchange pattern. This schema MUST adhere to
the rules below:
-
The content model of this element is defined using a complex
type that contains a sequence from XML Schema.
-
The sequence MUST only contain elements. It MUST NOT contain
other structures such as xs:choice.
-
The sequence MUST contain only local element children. These
child elements MAY contain the nillable attribute, and
the attributes minOccurs and maxOccurs
MUST have a value 1.
-
The localPart of the element's QName MUST be the same as the
Interface Operation component's name.
-
The complex type that defines the body of the element or its
children elements MUST NOT contain any attributes.
-
The sequence MUST NOT contain multiple children element declared
with the same local name.
5. WSDL SOAP
Binding Extension
The SOAP binding extension described in this section is SOAP
version independent ("1.2" as well as other versions) and an
extension for [WSDL 2.0 Core
Language] to enable Web Services applications to use
SOAP. This binding extension extends WSDL 2.0 by adding properties
to the Binding
component as defined in [WSDL 2.0
Core Language]. In addition, an XML Infoset
representation for these additional properties is provided, along
with a mapping from that representation to the various component
properties.
As allowed in [WSDL 2.0 Core
Language], a Binding
component MAY exist without indicating a specific Interface
component that it applies to. In this case, there MUST NOT be any
Binding Operation or
Binding Fault components present in the Binding
component.
The SOAP binding extension is designed with the objective of
minimizing what needs to be explicitly declared for common cases.
This is achieved by defining a set of default rules which apply for
all
Interface Operation components of an Interface
component, unless specifically overidden on a per Interface
Operation basis. Thus, if a given
Interface Operation component is not referred to specifically,
then all the default rules apply for that component. That is, per
the requirements of [WSDL 2.0 Core
Language], all operations of an Interface
component are bound according to this binding extension.
Notice that there are no default binding rules defined for
Interface
Fault components by this binding extension, as no reasonable
default is applicable to all cases. Thus, if a given Interface
component has any
Interface Fault components, then such Interface
components MUST be bound via Binding
components which indicate a specific interface and contain as many
Binding Fault components as there are
Interface Fault components in the Interface
component.
A subset of the HTTP properties specified in the HTTP binding
extension defined in section 6. WSDL
HTTP Binding Extension may be expressed in a SOAP binding
when the SOAP binding uses HTTP as the underlying protocol, for
example, when the value of the {soap underlying
protocol} property of the Binding
component is "http://www.w3.org/2003/05/soap/bindings/HTTP/". The
properties that are allowed are the ones that describe the
underlying protocol:
5.1 XML Syntax
Summary (Non-Normative)
<description>
<binding name="xs:NCName" interface="xs:QName"?
type="http://www.w3.org/2005/08/wsdl/soap"
whttp:version="xs:string"??
whttp:transferCodingDefault="xs:string"??
wsoap:version="xs:string"?
wsoap:protocol="xs:anyURI"
wsoap:mepDefault="xs:anyURI"? >
<documentation />*
<wsoap:module ref="xs:anyURI" required="xs:boolean"? >
<documentation />*
</wsoap:module>*
<fault ref="xs:QName"
wsoap:code="union of xs:QName, xs:token"?
wsoap:subcodes="list of xs:QName"? >
<documentation />*
<wsoap:module ... />*
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?>
<documentation />*
</wsoap:header>*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</fault>*
<operation ref="xs:QName"
whttp:location="xs:anyURI"??
whttp:transferCodingDefault="xs:string"?? >
wsoap:mep="xs:anyURI"?
wsoap:action="xs:anyURI"? >
<documentation />*
<wsoap:module ... />*
<input messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</input>*
<output messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</output>*
<infault ref="xs:QName"
messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
[ <feature /> | <property /> ]*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
[ <feature /> | <property /> ]*
</outfault>*
[ <feature /> | <property /> ]*
</operation>*
[ <feature /> | <property /> ]*
</binding>
<service>
<endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"?
whttp:authenticationType="xs:string"??
whttp:authenticationRealm="xs:string"?? >
<documentation />*
[ <feature /> | <property /> ]*
</endpoint>
[ <feature /> | <property /> ]*
</service>
</description>
Note:
The double question marks ("??") after the
attributes in the whttp namespace indicates that those
optional attributes only make sense when the SOAP binding uses HTTP
as the underlying protocol, for example, when the value of the
wsoap:protocol attribute is
"http://www.w3.org/2003/05/soap/bindings/HTTP/".
5.2
Identifying the use of the SOAP Binding
A Binding
component (defined in [WSDL 2.0 Core
Language]) is identified as a SOAP binding by assigning
the value "http://www.w3.org/2005/08/wsdl/soap" to the {type}
property of the Binding
component.
5.3 Default
Binding Rules
-
Payload Construction. When formulating the SOAP
envelope to be transmitted the contents of the payload (i.e., the
contents of the SOAP Body element information item of the
SOAP envelope) MUST be what is defined by the corresponding
Interface Message Reference component. This is subject to
optimization by a feature that is in use which may affect
serialization, such as MTOM [SOAP Message
Transmission Optimization Mechanism]. The following
default binding rules MUST be adhered to:
Note:
This SOAP binding extension only allows one single element in
SOAP body.
-
SOAP Header Construction. If the {soap headers}
property as defined in section 5.10
Declaring SOAP Header Blocks exists and is not empty in a
Binding Message Reference or
Binding Fault component, element information item
conforming to the element declaration of a SOAP Header Block component's
{element} property,
in the {soap headers}
property, MUST be turned into a SOAP header block for the
corresponding message.
And, if the SOAP Header
Block component's {mustUnderstand}
property is present and its value is "true", that particular SOAP
header block should be marked with a mustUnderstand
attribute information item with a value of "true" or "1"
as per the SOAP specification.
SOAP header blocks other than the ones declared in the {soap headers}
property may be present at run-time, such as the SOAP header blocks
resulting from SOAP modules declared as explained in section
5.9 Declaring SOAP
Modules.
5.4 Specifying the
SOAP Version
5.4.1 Description
Every SOAP binding MUST indicate what version of SOAP is in use
for the operations of the interface that this binding applies
to.
By default, SOAP 1.2 [SOAP 1.2
Part 1: Messaging Framework] is used.
5.4.2 Relationship to WSDL Component
Model
The SOAP protocol specification adds the following property to
the WSDL component model (as defined in [WSDL 2.0 Core Language]):
5.4.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:version="xs:string"? >
...
</binding>
</description>
The XML representation for specifying the SOAP version is an
optional attribute information item with the following
Infoset properties:
5.4.4 Mapping from XML
Representation to Component properties
See Table 5-1.
Table 5-1. Mapping from XML Representation to Binding
component Extension Properties
| Property |
Value |
| {soap version} |
The actual value of the
wsoap:version attribute information item if
present, otherwise "1.2". |
5.5 Specifying
the SOAP Underlying Protocol
5.5.1 Description
Every SOAP binding MUST indicate what underlying protocol is in
use.
5.5.2 Relationship to WSDL Component
Model
The SOAP protocol specification adds the following property to
the WSDL component model (as defined in [WSDL 2.0 Core Language]):
5.5.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:protocol="xs:anyURI" >
...
</binding>
</description>
The XML representation for specifying the SOAP protocol is a
REQUIRED attribute information item with the following
Infoset properties:
5.5.4 Mapping from XML
Representation to Component Properties
See Table 5-2.
Table 5-2. Mapping from XML Representation to Binding
component Extension Properties
| Property |
Value |
| {soap underlying
protocol} |
The actual value of the
wsoap:protocol attribute information
item. |
5.6 Specifying the Default SOAP
MEP
5.6.1 Description
Every
Binding Operation component of a SOAP binding MUST indicate the
SOAP Message Exchange Pattern (MEP) to be used for that operation.
This binding extension specification allows the user to indicate a
default SOAP MEP to be used for all
Binding Operation components of this Binding
component.
5.6.2 Relationship to WSDL
Component Model
The default SOAP MEP specification is a syntactic convenience
and does not affect the underlying component model.
5.6.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:protocol="xs:anyURI"
wsoap:mepDefault="xs:anyURI ?" >
...
</binding>
</description>
The XML representation for specifying the default SOAP MEP is an
OPTIONAL attribute information item with the following
Infoset properties:
5.7 Binding
Faults
5.7.1 Description
For every
Interface Fault component contained in an Interface
component, a mapping to a SOAP Fault must be described. This
binding extension specification allows the user to indicate the
SOAP fault code and subcodes that are transmitted for a given
Interface Fault component.
5.7.2 Relationship to WSDL Component
Model
The SOAP Fault binding extension adds the following properties
to the WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{soap fault code}
OPTIONAL. A xs:QName, to the
Binding Fault component. The value of this property identifies
a possible SOAP fault for the operations in scope. If this property
is empty, no assertion is made about the value of the SOAP fault
code.
-
{soap fault subcodes}
OPTIONAL. A list of xs:QName, to the
Binding Fault component. The value of this property identifies
one or more subcodes for this SOAP fault.
5.7.3 XML Representation
<description>
<binding >
<fault ref="xs:QName"
wsoap:code="union of xs:QName, xs:token"?
wsoap:subcodes="list of xs:QName"? >
<documentation />*
[ <feature /> | <property /> ]*
</fault>*
</binding>
</description>
The XML representation for binding a SOAP Fault are two
attribute information items with the following Infoset
properties:
5.7.4 Mapping XML Representation to
Component Properties
See Table 5-3.
Table 5-3. Mapping from XML Representation to SOAP Fault
component Properties
| Property |
Value |
| {soap fault code} |
The actual value of the
code attribute information item if present
and if its value is not "#any"; otherwise empty. |
| {soap fault
subcodes} |
The actual value of the
subcodes attribute information item, if
present; otherwise empty. |
5.8
Binding Operations
5.8.1 Description
For every
Interface Operation component contained in an Interface
component, in addition to the default binding rules (for SOAP 1.2,
see 5.11.3 Default Binding
Rules), there may be additional binding information to be
specified. This binding extension specification allows the user to
indicate the SOAP Message Exchange Pattern (MEP) and a value for
the SOAP Action Feature on a per-operation basis.
5.8.2 Relationship to WSDL
Component Model
The SOAP Operation binding extension specification adds the
following property to the WSDL component model (as defined in
[WSDL 2.0 Core
Language]):
-
{soap mep} REQUIRED. A
xs:anyURI, which is an absolute IRI as defined by
[IETF RFC 3987], to the
Binding Operation component. The value of this property
identifies the SOAP Message Exchange Pattern (MEP) for this
specific operation. If no specific value is assigned, then the
value assigned by the default rules apply (for SOAP 1.2, see
5.11.3 Default Binding
Rules). It is an error for this property to not have a
value (which MAY happen if the default rules are not
applicable).
-
{soap action} OPTIONAL. A
xs:anyURI, which is an absolute IRI as defined by
[IETF RFC 3987], to the
Binding Operation component. The value of this property
identifies the value of the SOAP Action Feature (as defined for
this specific operation), as specified in the binding rules of
bindings to specific versions of SOAP (see 5.11.3 Default Binding Rules for the
SOAP 1.2 binding when the value of the {soap version} property of the
Binding
component is "1.2").
5.8.3 XML Representation
<description>
<binding >
<operation ref="xs:QName"
wsoap:mep="xs:anyURI"?
wsoap:action="xs:anyURI"? >
</operation>
</binding>
</description>
The XML representation for binding an Operation are two
attribute information items with the following Infoset
properties:
5.8.4 Mapping from XML
Representation to Component Properties
See Table 5-4.
Table 5-4. Mapping from XML Representation to SOAP
Operation Component Properties
| Property |
Value |
| {soap mep} |
The actual value of the
wsoap:mep attribute information item, if
present. If not, the actual value of the
wsoap:mepDefault attribute information item
of the parent wsdl:binding element information
item, if present. If not the value as defined by the default
SOAP binding rules (for SOAP 1.2, see 5.11.3 Default Binding Rules), if
applicable. |
| {soap action} |
The actual value of the
action attribute information item, if any;
otherwise empty. |
5.9
Declaring SOAP Modules
5.9.1 Description
In SOAP, it is permissible for specification interaction to
engage one or more additional features (typically implemented as
one or more SOAP header blocks), as defined by SOAP Modules (see
[SOAP 1.2 Part 1: Messaging
Framework]). This binding extension specification allows
users to indicate which SOAP Modules are in use across an entire
binding, on a per operation basis or on a per message basis.
5.9.3 SOAP Module component
The SOAP Module component
identifies a SOAP module that is in use.
The properties of the SOAP Module component are as
follows:
-
{ref} REQUIRED. A xs:anyURI,
which is an absolute IRI as defined by [IETF RFC 3987]. The value of this property
identifies the specific SOAP module that is in use.
-
{required} REQUIRED. A
xs:boolean indicating if the SOAP module is required.
5.9.4 XML Representation
<description>
<binding >
<wsoap:module ref="anyURI"
required="boolean"? >
<documentation ... />*
</wsoap:module>
<fault>
<wsoap:module ... />*
</fault>
<operation>
<wsoap:module ... />*
<input>
<wsoap:module ... />*
</input>
<output>
<wsoap:module ... />*
</output>
<infault>
<wsoap:module ... />*
</infault>
<outfault>
<wsoap:module ... />*
</outfault>
</operation>
</binding>
</description>
The XML representation for a SOAP Module component is an element
information item with the following Infoset properties:
-
A [local name] of module
-
A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"
-
One or more attribute information items amongst its
[attributes] as follows:
-
A REQUIRED ref attribute information item
with the following Infoset properties:
-
An OPTIONAL required attribute information
item with the following Infoset properties:
-
Zero or more namespace qualified attribute information
items. The [namespace name] of such attribute information
items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST
NOT be "http://www.w3.org/2005/08/wsdl/soap".
-
Zero or more element information item amongst its
[children], in order, as follows:
-
Zero or more documentation element information
items as defined in [WSDL 2.0 Core
Language].
-
Zero or more namespace-qualified element information
items amongst its [children]. The [namespace name] of such
element information items MUST NOT be
"http://www.w3.org/2005/08/wsdl" and MUST NOT be
"http://www.w3.org/2005/08/wsdl/soap".
5.9.5 Mapping from XML
Representation to Component Properties
See Table 5-5.
Table 5-5. Mapping from XML Representation to SOAP Module
component Properties
| Property |
Value |
| {soap modules} |
The set of SOAP Module components corresponding to
all the module element information item in
the [children] of the binding , operation
, fault , input , output ,
infault , outfault element
information items, if any. |
| {ref} |
The actual value of the
ref attribute information item. |
| {required} |
The actual value of the
required attribute information item if
present, otherwise "false". |
5.10
Declaring SOAP Header Blocks
5.10.1 Description
SOAP allows the use of header blocks in the header part of the
message. This binding extension allows users to declare the SOAP
header blocks in use on a per message ond on a per fault basis.
5.10.2 Relationship to WSDL
Component Model
The SOAP Header Blocks binding extension specification adds the
following property to the WSDL component model (as defined in
[WSDL 2.0 Core
Language]):
5.10.3 SOAP Header Block
component
A SOAP Header Block
component describes an abstract piece of header data (message
headers) that is associated with the exchange of messages between
the communicating parties. The presence of a SOAP Header Block component in a
WSDL description indicates that the service supports headers and
MAY require a Web service consumer/client that interacts with the
service to use the described header. Zero or more such headers may
be used.
The properties of the component are as
follows:
-
{} REQUIRED. A
xs:QName, a reference to an XML element declaration in the
{element
declarations} property of the
Description component. This element represents a SOAP header
block.
-
{mustUnderstand}
REQUIRED. A xs:boolean. When its value is "true", the SOAP
header block MUST be decorated with a SOAP
mustUnderstand attribute information item
with a value of "true"; if so, it is an error for the XML element
declaration referenced by the {element} property not to
allow this SOAP mustUnderstand attribute
information item. Otherwise, no additional constraint is
placed on the presence and value of a SOAP
mustUnderstand attribute information
item.
5.10.4 XML Representation
<description>
<binding name="xs:NCName" type="http://www.w3.org/2005/08/wsdl/soap" >
<fault ref="xs:QName" >
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?>
<documentation />*
</wsoap:header>*
...
</fault>*
<operation ref="xs:QName" >
<input messageLabel="xs:NCName"?>
<wsoap:header ... />*
...
</input>*
<output messageLabel="xs:NCName"?>
<wsoap:header ... />*
...
</output>*
</operation>*
</binding>
</description>
The XML representation for a SOAP Header Block component is an
element information item with the following Infoset
properties:
-
A [local name] of header
-
A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"
-
One or more attribute information items amongst its
[attributes] as follows:
-
A REQUIRED element attribute information
item with the following Infoset properties:
-
An OPTIONAL mustUnderstand attribute
information item with the following Infoset properties:
-
Zero or more namespace qualified attribute information
items. The [namespace name] of such attribute information
items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST
NOT be "http://www.w3.org/2005/08/wsdl/soap".
-
Zero or more element information item amongst its
[children], in order, as follows:
-
Zero or more documentation element information
items as defined in [WSDL 2.0 Core
Language].
-
Zero or more namespace-qualified element information
items amongst its [children]. The [namespace name] of such
element information items MUST NOT be
"http://www.w3.org/2005/08/wsdl" and MUST NOT be
"http://www.w3.org/2005/08/wsdl/soap".
5.10.5 Mapping XML Representation
to Component Properties
See Table 5-6.
Table 5-6. Mapping from XML Representation to SOAP Header
Block component Properties
| Property |
Value |
| {soap
headers} |
The set of SOAP Header Block components
corresponding to all the header element
information item in the [children] of the fault ,
input or output element information
item, if any. |
| {element} |
The element declaration from the
{element
declarations} resolved to by the value of the
element attribute information item. It is an
error for the element attribute information
item to have a value and that value does not resolve to a
global element declaration from the {element
declarations} property of the
Description component. |
| {mustUnderstand} |
The actual value of the
mustUnderstand attribute information item if
present, otherwise "false". |
5.11 WSDL SOAP
1.2 Binding
5.11.1 Identifying a WSDL SOAP 1.2
Binding
A WSDL SOAP Binding is identified as a SOAP 1.2 binding by
assigning the value "1.2" to the {soap version} property of the
Binding
component.
5.11.3
Default Binding Rules
These default binding rules are applicable to SOAP 1.2
bindings.
-
SOAP Action Feature. If a value for the {soap action} property
of a
Binding Operation component has NOT been specified then the
SOAP Action Feature (see [SOAP 1.2
Part 2: Adjuncts]) has NO value assigned by the Binding
component. Otherwise, the value of the {soap action} property
of a
Binding Operation component is the value of the SOAP Action
Feature for all messages of the corresponding
Interface Operation component.
-
SOAP MEP Selection. If the
Interface Operation component's {message
exchange pattern} property has the value
"http://www.w3.org/2005/08/wsdl/in-out", then the default value of
the {soap mep}
property for the corresponding
Binding Operation component is
"http://www.w3.org/2003/05/soap/mep/request-response/" identifying
the SOAP Request-Response Message Exchange Pattern as defined in
[SOAP 1.2 Part 2:
Adjuncts]. If the
Interface Operation component has any other value for the
{message
exchange pattern} property, then no default value is defined
for the {soap mep}
property of the corresponding
Binding Operation component.
| Editorial note:
One-way MEP defaulting |
|
| The Web Services
Description Working Group would like to add a rule here defaulting
to a standardized SOAP 1.2 one-way MEP for one-way operations if
one becomes available. Feedback is sought on this topic. |
-
HTTP Method Selection. This default binding rule is
applicable when the value of the {soap underlying
protocol} property of the Binding
component is "http://www.w3.org/2003/05/soap/bindings/HTTP/". If
the {soap mep}
property of the
Binding Operation component has the value
"http://www.w3.org/2003/05/soap/mep/request-response/" then the
default value of the {http method} property
is "POST". If the {soap mep} property of the
Binding Operation component has the value
"http://www.w3.org/2003/05/soap/mep/soap-response/" then the
default value of the {http method} property
is "GET".
-
HTTP IRI Generation. This default binding rule is
applicable when the value of the {soap underlying
protocol} property of the Binding
component is "http://www.w3.org/2003/05/soap/bindings/HTTP/". If
the {soap mep}
property of the
Binding Operation component has the value
"http://www.w3.org/2003/05/soap/mep/soap-response/" then the IRI to
execute the HTTP GET against MUST be generated using the HTTP
binding extension's rules for generating a IRI for HTTP GET (see
6.9.1 Serialization as
application/x-www-form-urlencoded ). The input
serialization format of x-www-form-urlencoded is the
only supported serialization format for HTTP GET in the SOAP
Response Message Exchange Pattern.
| Editorial note: Input
serialization for HTTP GET in SOAP HTTP binding |
|
Use of a different input
serialization format requires introduction of either a new MEP or a
new binding. The Working Group considered the limitations of the
x-www-form-urlencoded serialization format (see
points #2 and #3 of Binding message content to IRI analysis).
It decided that the limitations of the serialization format, which
could potentia |