Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts
http://www.w3.org/TR/2007/PR-wsdl20-adjuncts-20070523
W3C Proposed Recommendation
23
May
2007
http://www.w3.org/TR/2007/PR-wsdl20-adjuncts-20070523
PDF
PostScript
XML
plain text
http://www.w3.org/TR/2007/WD-wsdl20-adjuncts-20070326
http://www.w3.org/TR/wsdl20-adjuncts
Roberto Chinnici
Sun Microsystems
Hugo Haas
W3C
Amelia A. Lewis
TIBCO Software
Jean-Jacques Moreau
Canon
David Orchard
BEA Systems
Sanjiva Weerawarana
WSO2
WSDL 2.0 is the Web Services Description Language, an XML language for describing Web
services. This document, Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts,
specifies predefined extensions for use in WSDL 2.0:
Message exchange patterns
Operation safety
Operation styles
Binding extensions for SOAP and HTTP
This section describes the status of this document at the time
of its publication. Other documents may supersede this document. A
list of current W3C publications and the latest revision of this
technical report can be found in the W3C technical reports index at
http://www.w3.org/TR/.
This is the W3C
Proposed Recommendation of Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts for review by W3C Members and
other interested parties. It has been produced by the Web Services Description
Working Group, which is part of the W3C Web Services
Activity.
W3C Advisory Committee Representatives should consult their WBS
questionnaires. Reviews are expected until 20 June 2007.
Individuals are invited to send
feedback on this document to the public public-ws-desc-comments@w3.org
mailing list (public
archive).
The Working Group released a test suite along with an implementation
report.
Issues about this document are recorded in the issues
list maintained by the Working Group. A diff-marked version against the
previous version of this document is available.
Publication as a Proposed Recommendation does not imply
endorsement by the W3C Membership. This is a draft document and
may be updated, replaced or obsoleted by other documents at any
time. It is inappropriate to cite this document as other than
work in progress.
This document is governed by the 24
January 2002 CPP as amended by the W3C Patent
Policy Transition Procedure. W3C maintains a public
list of any patent disclosures made in connection with the
deliverables of the group; that page also includes instructions
for disclosing a patent. An individual who has actual knowledge
of a patent which the individual believes contains Essential
Claim(s) must disclose the information in accordance with
section
6 of the W3C Patent Policy.
English
Last Modified: $Date: 2007/05/18 21:27:53 $ CET
Introduction
The Web Services Description Language Version 2.0 (WSDL 2.0)
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:
Message exchange patterns:
Operation safety declaration:
Operation styles:
Binding extensions:
A SOAP 1.2 binding extension:
An HTTP/1.1 binding extension:
This document depends on WSDL Version 2.0 .
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 .
This specification uses a number of namespace prefixes throughout;
they are listed in . Note that the choice of
any namespace prefix is arbitrary and not semantically significant
(see ).
Prefixes and Namespaces used in this specification
| Prefix |
Namespace |
Notes |
| wsdl |
http://www.w3.org/ns/wsdl
|
This namespace is defined in .
A normative XML Schema ,
document for the
http://www.w3.org/ns/wsdl
namespace can be found at http://www.w3.org/ns/wsdl. This namespace is used as
the default namespace throughout this specification. |
| wsdlx |
http://www.w3.org/ns/wsdl-extensions
|
This specification extends in section the
http://www.w3.org/ns/wsdl-extensions namespace defined in .
A normative XML Schema ,
document for the
http://www.w3.org/ns/wsdl-extensions
namespace can be found at http://www.w3.org/ns/wsdl-extensions. |
| wsoap |
http://www.w3.org/ns/wsdl/soap
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/ns/wsdl/soap
namespace can be found at http://www.w3.org/ns/wsdl/soap. |
| whttp |
http://www.w3.org/ns/wsdl/http
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/ns/wsdl/http
namespace can be found at http://www.w3.org/ns/wsdl/http. |
| wrpc |
http://www.w3.org/ns/wsdl/rpc
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/ns/wsdl/rpc
namespace can be found at http://www.w3.org/ns/wsdl/rpc. |
| xs |
http://www.w3.org/2001/XMLSchema
|
Defined in the W3C XML Schema
specification , . |
Namespace names of the general form
http://example.org/... and
http://example.com/... represent application or
context-dependent URIs .
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 serialization. The syntax of BNF
pseudo-schemas is the same as the one used in .
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 .
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 ) that can transmit and/or receive message(s)
described in WSDL description(s) and process them.
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 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 ).
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 . Additional, non-normative patterns are available
in .
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 , after examination of existing predefined patterns.
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.
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
. "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
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.
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
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
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
Message Exchange Patterns
WSDL patterns are described in terms of the WSDL component model,
specifically the Interface Message Reference
and Interface Fault Reference components.
In-Only message exchange pattern
The in-only message exchange pattern
consists of exactly one message as follows:
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is In and direction is in
-
received from some node N
The in-only
message exchange pattern uses the 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.
Robust In-Only message exchange pattern
The robust-in-only message exchange
pattern consists of exactly one message as follows:
A message:
indicated by a Interface Message Reference component whose
message label is In and
direction is in
received from some node N
The robust in-only message exchange pattern uses the 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.
In-Out message exchange pattern
The in-out message exchange pattern
consists of exactly two messages, in order, as follows:
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is In and direction is in
-
received from some node N
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is Out and direction is out
-
sent to node N
The in-out message exchange pattern uses the 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.
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.
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
require bound
Interface Operation components to have one
or more of the styles defined in this section.
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 simulatenously, the corresponding attribute information item MUST be valid according to the schema
for the extension and additionally MUST obey the constraints listed
in
and .
Furthermore, the
associated messages MUST conform to the rules below,
described using XML Schema . 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 ).
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.
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).
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).
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:
A [local name] of signature
A [namespace name] of "http://www.w3.org/ns/wsdl/rpc"
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 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.
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>
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].
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. |
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 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 occurence 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.
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 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.
WSDL SOAP Binding Extension
The SOAP binding extension described in this section is an extension
for 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 . 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 , 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 , 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 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):
http location
and http location ignore uncited
on Binding Operation
components, as defined in
and , respectively.
http headers on Binding Message Reference and Binding Fault components, as defined in
http query parameter
separator default on Binding components,
http query parameter
separator on Binding Operation components,
as defined in
http content
encoding default on Binding and Binding Operation components, http content
encoding on Binding Message Reference and Binding Fault components, as defined in
http cookies on Binding components, as defined in .
http authentication scheme and
http authentication realm on Endpoint components, as defined in
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/.
Identifying the use of the SOAP Binding
A Binding component (defined in )
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.
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 . The
following binding rules MUST be adhered to:
If the value of the
message content model
property of the Interface Message Reference component is #any, then
the payload MAY be any one XML element.
If the value is #none, then the
payload MUST be empty.
If the value is #element, then the
payload MUST be the element information item identified by the
element declaration
property of the Interface Message Reference component.
-
If the Interface Message Reference component is declared
using a non-XML type system (as considered in the Types
section of ), then additional
binding rules MUST be defined to indicate how to map those
components into the SOAP envelope.
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 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 .
Specifying the SOAP Version
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 is used.
Relationship to WSDL Component Model
The SOAP protocol specification adds the following
property to the WSDL component model (as defined in ):
soap version REQUIRED. A xs:string, to the Binding
component.
The XML representation for specifying the SOAP version
is an optional attribute information item with the following Infoset properties:
-
A [local name] of version
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of xs:string
Mapping from XML Representation to Component properties
See .
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.
|
Specifying the SOAP Underlying Protocol
Description
Every SOAP binding MUST indicate what underlying protocol is in
use.
Relationship to WSDL Component Model
The SOAP protocol specification adds the following
property to the WSDL component model (as defined in ):
soap underlying protocol REQUIRED. A xs:anyURI,
which is an absolute IRI as defined by , to the Binding
component. This IRI refers to an appropriate SOAP
underlying protocol binding (see SOAP Protocol Binding
Framework in ), which is to be
used for any of the SOAP interactions described by this
binding.
The XML representation for specifying the SOAP protocol
is a REQUIRED attribute information item with the following Infoset properties:
-
A [local name] of protocol
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of xs:anyURI
Mapping from XML Representation to Component Properties
See .
Mapping from XML Representation to Binding component Extension
Properties
| Property |
Value |
| soap underlying protocol |
The actual value of the wsoap:protocol
attribute information item. |
Binding Faults
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.
Relationship to WSDL Component Model
The SOAP Fault binding extension adds the following
properties to the WSDL component model (as defined in ):
soap fault code REQUIRED. A union of xs:QName and
xs:token, to the Binding Fault component, where:
when the value of the soap version
is 1.2, the allowed QNames MUST be the ones defined by
, section 5.4.6;
the allowed token value is #any.
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.
The XML representation for binding a SOAP Fault are two
attribute information items with the following Infoset properties:
wsoap:code OPTIONAL attribute information item
A [local name] of code
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of union of xs:QName and
xs:token where the allowed token value
is #any
wsoap:subcodes OPTIONAL attribute information item
A [local name] of subcodes
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of union of list of xs:QName, and
xs:token where the allowed token value
is #any
See .
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. |
Binding Operations
Description
For every Interface Operation component contained in an Interface
component, in addition to the binding rules (for SOAP 1.2,
see ), 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.
Relationship to WSDL Component Model
The SOAP Operation binding extension specification adds the
following property to the WSDL component model (as defined
in ):
soap mep default OPTIONAL. A xs:anyURI,
which is an absolute IRI as defined by , to the Binding
component. The value of this property identifies the
default SOAP Message Exchange Pattern (MEP) for all the
Interface Operation components of any Interface component
to which this Binding is applied.
soap mep OPTIONAL.
A xs:anyURI, which is an absolute IRI as defined by , to the Binding Operation component. The
value of this property identifies the SOAP Message
Exchange Pattern (MEP) for this specific operation
(see , paragraph "SOAP MEP Selection", for constraints on bindings).
soap action OPTIONAL.
A xs:anyURI, which is an absolute IRI as defined by , to the Binding Operation component. The
value of this property identifies the value of the SOAP
Action Feature for the initial message of the message exchange pattern of the Interface Operation bound,
as specified in the binding rules of bindings to specific
versions of SOAP (see for
the SOAP 1.2 binding when the value
of the soap version property
of the Binding component is 1.2).
The XML representation for binding a Binding Operation are two
attribute information items with the following Infoset properties:
wsoap:mep OPTIONAL attribute information item
A [local name] of mep
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of xs:anyURI
wsoap:action OPTIONAL attribute information item
A [local name] of action
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of xs:anyURI
The following attribute information item for the binding element information item is
defined:
wsoap:mepDefault OPTIONAL attribute information item
-
A [local name] of
mepDefault
-
A [namespace name] of
http://www.w3.org/ns/wsdl/soap
-
A type of
xs:anyURI
See .
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. |
Declaring SOAP Modules
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 ). 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.
Relationship to WSDL Component Model
The SOAP Module component adds the following
property to the WSDL component model (as defined in ):
soap modules OPTIONAL. A set of SOAP Module components
as defined in
to the Binding component
Similarly, soap modules OPTIONAL, to the Binding Operation component
Similarly, soap modules OPTIONAL, to the Binding Message Reference component
Similarly, soap modules OPTIONAL, to the Binding Fault component
Similarly, soap modules OPTIONAL, to the Binding Fault Reference component
The SOAP modules applicable for a particular operation of
any service, consists of all the modules specified in the input
or output Binding Message Reference components, the infault
or outfault Binding Fault Reference components, those
specified within the Binding Fault components, those
specified within the Binding Operation components and those
specified within the Binding component. If any module is
declared in multiple components, then the requiredness of
that module is defined by the closest declaration, where
closeness is defined by whether it is specified directly at
the Binding Message Reference component or
Binding Fault Reference component level, the Binding Fault level or the
Binding Operation component level or the Binding component
level, respectively.
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 . The value of this property uniquely identifies the
SOAP module that is in use (as per the SOAP 1.2 processing model).
-
required REQUIRED.
A xs:boolean indicating if the SOAP
module is required.
-
parent REQUIRED.
The Binding, Binding Operation,
Binding Message Reference, Binding
Fault or Binding Fault Reference
components that contains this component in its
soap modules property.
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:
-
A [local name] of ref
-
A [namespace name] which has no value
-
A type of xs:anyURI
-
An OPTIONAL required
attribute information item with the
following Infoset properties:
-
A [local name] of required
-
A [namespace name] which has no value
-
A type of xs:boolean
-
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 .
-
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.
Mapping from XML Representation to Component Properties
See .
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].
|
IRI Identification Of A SOAP Module component
WSDL Version 2.0 Part 1: Core Language defines a fragment identifier
syntax for identifying components of a WSDL 2.0
document.
A SOAP Module component can be identified using the
wsdl.extension
XPointer Framework scheme:
wsdl.extension(http://www.w3.org/ns/wsdl/soap,
wsoap.module(parent/ref))
parent
is the pointer part of the parent component, as specified in WSDL
Version 2.0 Part 1: Core Language.
-
ref
is the value of the ref property of the component.