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. The syntax
of BNF pseudo-schemas is the same as the one used in
[WSDL 2.0 Core
Language].
2. Predefined Message Exchange
Patterns
Web Services Description Language (WSDL) message exchange
patterns (hereafter simply 'patterns') define the sequence and
cardinality 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.
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.
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.10.3 SOAP
1.2 Binding Rules contains the 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.
This fault propagation rule is identified by the following URI:
http://www.w3.org/2006/01/wsdl/fault-replaces-message
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.
This fault propagation rule is identified by the following URI:
http://www.w3.org/2006/01/wsdl/message-triggers-fault
2.2.3 No Faults
Faults MUST NOT be propagated.
This fault propagation rule is identified by the following URI:
http://www.w3.org/2006/01/wsdl/no-faults
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/2006/01/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/2006/01/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/2006/01/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/2006/01/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/2006/01/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/2006/01/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/2006/01/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/2006/01/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 that can be used to place constraints on
Interface Operation components, in particular with respect to
the format of the messages they refer to. The serialization formats
defined in section 6.8
Serialization Format of Instance Data require bound
Interface Operation components to have one or more of the
styles defined in this section.
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/2006/01/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/2006/01/wsdl/in-only" or
"http://www.w3.org/2006/01/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/2006/01/wsdl/in-only", then the conditions
stated below that refer to output elements MUST be considered to be
implicitly satisfied.
-
The value of the {message
content model} property for the
Interface Message Reference components of the {interface
message references} property MUST be "#element".
-
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 which 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 an excerpt from the normative schema 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="xs:QName wrpc:directionToken"/>
</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 is selected by assigning the
Interface Operation component's {style}
property the value "http://www.w3.org/2006/01/wsdl/style/iri".
When using this style, the value of the {message
content model} property of the
Interface Message Reference component corresponding to the
initial message of the message exchange pattern MUST be
"#element".
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 is selected by assigning the
Interface Operation component's {style}
property the value
"http://www.w3.org/2006/01/wsdl/style/multipart".
When using this style, the value of the {message
content model} property of the
Interface Message Reference component corresponding to the
initial message of the message exchange pattern MUST be
"#element".
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 overridden 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.
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/2006/01/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"?
whttp:transferCoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?
required="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"?>
<documentation />*
<wsoap:module ... />*
[ <feature /> | <property /> ]*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"?>
<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:token"??
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/2006/01/wsdl/soap" to the {type}
property of the Binding
component.
5.3 SOAP 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
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.9 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
declaration} property, in the {soap headers}
property, MAY be turned into a SOAP header block for the
corresponding message.
If the value of the SOAP
Header Block component's {required} property is
"true", the inclusion of this SOAP header block is REQUIRED,
otherwise it is OPTIONAL.
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.8 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 Binding
Faults
5.6.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.6.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}
REQUIRED. A union of xs:QName and xs:token where
the allowed token value is "#any", to the
Binding Fault component. The value of this property identifies
a possible SOAP fault for the operations in scope. If the value of
this property is "#any", no assertion is made about the value of
the SOAP fault code.
-
{soap fault subcodes}
REQUIRED. A union of list of xs:QName, and
xs:token where the allowed token value is "#any", to the
Binding Fault component. The value of this property identifies
one or more subcodes for this SOAP fault. If the value of this
property is "#any", no assertion is made about the value of the
SOAP fault subcode.
5.6.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.6.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;
otherwise "#any". |
| {soap fault
subcodes} |
The actual value of the
subcodes attribute information item, if
present; otherwise "#any". |
5.7
Binding Operations
5.7.1 Description
For every
Interface Operation component contained in an Interface
component, in addition to the binding rules (for SOAP 1.2, see
5.10.3 SOAP 1.2 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.7.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]):
5.7.3 XML Representation
<description>
<binding wsoap:mepDefault="xs:anyURI"? >
<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:
The following attribute information item for the
binding element information item is
defined:
5.7.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 default} |
The actual value of the
wsoap:mepDefault attribute information item,
if present. |
| {soap mep} |
The actual value of the
wsoap:mep attribute information item, if
present. |
| {soap action} |
The actual value of the
action attribute information item, if
any. |
5.8
Declaring SOAP Modules
5.8.1 Description
The SOAP messaging framework allows 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.8.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:
5.8.4 XML Representation
<description>
<binding >
<wsoap:module ref="xs:anyURI"
required="xs: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/2006/01/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/2006/01/wsdl" and MUST
NOT be "http://www.w3.org/2006/01/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/2006/01/wsdl" and MUST NOT be
"http://www.w3.org/2006/01/wsdl/soap".
5.8.5 Mapping from XML
Representation to Component Properties
See Table 5-5.
Table 5-5. Mapping from XML Representation to SOAP Module
component-related 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". |
| {parent} |
The Binding,
Binding Operation,
Binding Message Reference,
Binding Fault or
Binding Fault Reference component corresponding to the
binding , operation , fault
, input , output , infault
or outfault element information item in
[parent]. |
5.9
Declaring SOAP Header Blocks
5.9.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 and on a per fault basis.
5.9.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.9.3 SOAP Header Block
component
A SOAP Header Block
component describes an abstract piece of header data (SOAP header
block) 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 block. Zero or one such header
block 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 XML element declaration 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
declaration} 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.
-
{} REQUIRED. A
xs:boolean indicating if the SOAP header block is
required. If the value is "true", then the SOAP header block MUST
be included in the message. If it is "false", then the SOAP header
block MAY be included.
-
{} REQUIRED. The
Binding Fault or
Binding Message Reference component component that contains
this component in its {soap headers}
property.
5.9.4 XML Representation
<description>
<binding name="xs:NCName" type="http://www.w3.org/2006/01/wsdl/soap" >
<fault ref="xs:QName" >
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?
required="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/2006/01/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:
-
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/2006/01/wsdl" and MUST
NOT be "http://www.w3.org/2006/01/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/2006/01/wsdl" and MUST NOT be
"http://www.w3.org/2006/01/wsdl/soap".
5.9.5 Mapping XML Representation to
Component Properties
See Table 5-6.
Table 5-6. Mapping from XML Representation to SOAP Header
Block component-related 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
declaration} |
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 |