1. Introduction
The Web Services Description Language Version 2.0 (WSDL 2.0)
[WSDL 2.0 Core Language]
provides a model and an XML format for describing Web services.
WSDL 2.0 enables one to separate the description of the abstract
functionality offered by a service from concrete details of a
service description such as "how" and "where" that functionality is
offered.
This document, "Web Services Description Language (WSDL) Version
2.0 Part 2: Adjuncts", specifies predefined extensions for use in
WSDL 2.0:
This document depends on "Web Services Description Language
(WSDL) Version 2.0 Part 1: Core Language" [WSDL 2.0 Core Language]. See also the "Web
Services Description Language (WSDL) Version 2.0 Part 0: Primer"
[WSDL 2.0 Primer] for more
information and examples.
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].
1.2 Assertions
Assertions about WSDL 2.0 documents and components that are not
enforced by the normative XML schema for WSDL 2.0 are marked by a
dagger symbol (†) at the end of a sentence. Each assertion has been
assigned a unique identifier that consists of a descriptive textual
prefix and a unique numeric suffix. The numeric suffixes are
assigned sequentially and never reused so there may be gaps in the
sequence. The assertion identifiers MAY be used by implementations
of this specification for any purpose, e.g. error reporting.
The assertions and their identifiers are summarized in section
C. Assertion
Summary.
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 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 such as
timing between messages, whether the pattern is synchronous or
asynchronous, and whether the messages 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 messages (to each other or to other
nodes) that are not described by the pattern.†
For instance, even though a pattern can define a single message
sent from a service to one other node, the Web service can in
practice 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]. Additional, non-normative patterns are
available in [WSDL 2.0 Additional
MEPs].
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 in 2.1.1 Pattern Name, 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 an
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
Interface 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 can occur. The most
common patterns for fault propagation are defined in the following
subsections, and referenced by the patterns in 2.3 Message Exchange Patterns.
"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 that generate faults 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 can
override the semantics of a fault propagation ruleset, but this
practice is strongly discouraged.
2.2.1
Fault Replaces Message propagation rule
When the Fault Replaces Message propagation
rule is in effect, 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.†
The Fault Replaces Message propagation rule is identified by the
following URI:
http://www.w3.org/ns/wsdl/fault-replaces-message
2.2.2 Message
Triggers Fault propagation rule
When the Message Triggers Fault propagation
rule is in effect, 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 or 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.†
The Message Triggers Fault propagation rule is identified by the
following URI:
http://www.w3.org/ns/wsdl/message-triggers-fault
2.2.3 No Faults
propagation rule
When the No
Faults propagation rule is in effect, faults MUST NOT be
propagated. †
The No Faults propagation rule is identified by the following
URI: http://www.w3.org/ns/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 message
exchange pattern
The
in-only message exchange pattern consists of exactly
one message as follows:†
-
A message:
The
in-only message exchange pattern uses the rule
2.2.3 No Faults propagation
rule.†
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/ns/wsdl/in-only".
2.3.2 Robust
In-Only message exchange pattern
The robust-in-only message
exchange pattern consists of exactly one message as
follows:†
-
A message:
The
robust in-only message exchange pattern uses the rule
2.2.2 Message Triggers Fault
propagation rule.†
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/ns/wsdl/robust-in-only".
2.3.3 In-Out message exchange
pattern
The
in-out message exchange pattern consists of exactly
two messages, in order, as follows:†
-
A message:
-
A message:
The
in-out message exchange pattern uses the rule 2.2.1 Fault Replaces Message
propagation rule.†
An operation using this message exchange pattern has a {message
exchange pattern} property with the value
"http://www.w3.org/ns/wsdl/in-out".
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 can 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 can be obscured, or blame laid on a third
party, or denial-of-service attacks can be enabled or
exacerbated.
Security mechanisms addressing such attacks can 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 including the value
"http://www.w3.org/ns/wsdl/style/rpc" in the {style}
property of an
Interface Operation component.
An
Interface Operation component conforming to the RPC style MUST
obey the constraints listed further below. Also, if the
wrpc:signature extension is engaged simultaneously,
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.
Furthermore, 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 RPC
style is used by an
Interface Operation component then its {message
exchange pattern} property MUST have the value either
"http://www.w3.org/ns/wsdl/in-only" or
"http://www.w3.org/ns/wsdl/in-out".†
If the
Interface Operation component uses a {message
exchange pattern} for which there is no output element, i.e.
"http://www.w3.org/ns/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.
-
Both the
input and output sequences 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}
OPTIONAL, but MUST
be present when the style is RPC†. 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. There MUST NOT be a child
element of the output element with the name of
q.†
-
For each pair
(q, #out), there MUST be a child element of the output
element with a name of q. There MUST NOT be a child
element of the input element with the name of
q.†
-
For each pair
(q, #inout), there MUST be a child element of the input
element with a name of q. There MUST also be a child
element of the output element with the name of
q.†
-
For each pair
(q, #return), there MUST be a child element of the output
element with a name of q. There MUST NOT be a child
element of the input element with the name of
q.†
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
implementers 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 signature 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 including the value
"http://www.w3.org/ns/wsdl/style/iri" in the {style}
property of an
Interface Operation component.
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. There are no occurrence constraints on the
sequence.
-
The sequence
MUST contain only local element children.† Note
these child elements can contain the nillable
attribute.
-
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 children
elements of the sequence 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 including the value
"http://www.w3.org/ns/wsdl/style/multipart" in the {style}
property of an
Interface Operation component.
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.†
The
attributes minOccurs and maxOccurs for
these child elements MUST have a value 1.†
Note these child elements can contain the nillable
attribute.
-
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 an
extension for [WSDL 2.0 Core
Language] to enable Web services applications to use
SOAP. This binding extension is SOAP version independent ("1.2" as
well as other versions) and extends WSDL 2.0 by adding properties
to the Binding
component, and its related components, 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 can exist without indicating a specific
Interface component that it applies to. In this case, no
Binding Operation or
Binding Fault component can be 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 that affect all
Interface Operation components of an
Interface component to which the SOAP binding extension is
applied, unless specifically overridden by a
Binding Operation component. Thus, if a given
Interface Operation component is not referred to specifically
by a
Binding Operation component, then all the default rules apply
to that
Interface Operation component. As a result, in accordance with
the requirements of [WSDL 2.0 Core
Language], all operations of an
Interface component will be bound by this binding
extension.
Note: As in other parts of this specification,
one could have done away with "default" properties at the component
model level, and have set the value for the corresponding
non-default properties in the XML mapping section. However, default
properties are required for interface-less binding. Indeed, an
interface-less binding has no means to set the non-default version
of the property at the operation-level, since there is precisely no
operation (there is not even an interface). Hence the mapping needs
to be done elsewhere.
A subset of the HTTP properties specified in the HTTP binding
extension defined in section 6.
WSDL HTTP Binding Extension are present 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/".
These
properties MUST NOT be used unless the underlying protocol is
HTTP.†
The allowed properties are the ones that describe the underlying
protocol (HTTP):
5.1 SOAP Syntax
Summary (Non-Normative)
<description>
<binding name="xs:NCName" interface="xs:QName"?
type="http://www.w3.org/ns/wsdl/soap"
whttp:queryParameterSeparatorDefault="xs:string"??
whttp:contentEncodingDefault="xs:string"??
whttp:cookies="xs:boolean"?
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="union of (list of xs:QName), xs:token"?
whttp:contentEncoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?
required="xs:boolean"? >
<documentation />*
</wsoap:header>*
<whttp:header ... />*??
</fault>*
<operation ref="xs:QName"
whttp:location="xs:anyURI"??
whttp:contentEncodingDefault="xs:string"??
whttp:queryParameterSeparator="xs:string"??
whttp:ignoreUncited="xs:boolean"??
wsoap:mep="xs:anyURI"?
wsoap:action="xs:anyURI"? >
<documentation />*
<wsoap:module ... />*
<input messageLabel="xs:NCName"?
whttp:contentEncoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
</input>*
<output messageLabel="xs:NCName"?
whttp:contentEncoding="xs:string"?? >
<documentation />*
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
</output>*
<infault ref="xs:QName"
messageLabel="xs:NCName"?>
<documentation />*
<wsoap:module ... />*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"?>
<documentation />*
<wsoap:module ... />*
</outfault>*
</operation>*
</binding>
<service>
<endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"?
whttp:authenticationScheme="xs:token"??
whttp:authenticationRealm="xs:string"?? >
<documentation />*
</endpoint>
</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/ns/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 further subject to optimization by a feature in use which
affects 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
the 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, then an 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 MUST 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.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, to
the
Binding Fault component, where:
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 possible 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. The list of subcodes is
the nested sequence of subcodes. An empty list represents a fault
code without subcodes.
5.6.3 XML Representation
<description>
<binding >
<fault ref="xs:QName"
wsoap:code="union of xs:QName, xs:token"?
wsoap:subcodes="union of (list of xs:QName), xs:token"? >
<documentation />*
</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 a
Binding 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
wsoap:action attribute information item, if
any. |
5.8
Declaring SOAP Modules
5.8.1 Description
The SOAP messaging framework allows a Web service 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
(Second Edition)]). This binding extension specification
allows description of 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/ns/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/ns/wsdl" and MUST NOT be
"http://www.w3.org/ns/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/ns/wsdl" and MUST NOT be
"http://www.w3.org/ns/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 client interacting 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: