Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts
http://www.w3.org/TR/2006/CR-wsdl20-adjuncts-20060106
W3C Candidate Recommendation
6
January
2006
http://www.w3.org/TR/2006/CR-wsdl20-adjuncts-20060106
PDF
PostScript
XML
plain text
http://www.w3.org/TR/2005/WD-wsdl20-adjuncts-20050803
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 is an XML format for describing network services as a set
of endpoints operating on messages containing either
document-oriented or procedure-oriented information.
Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts defines predefined extensions for use in WSDL 2.0:
Message exchange patterns
Operation styles
Binding Extensions
This
specification depends on WSDL Version 2.0 .
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
Candidate 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. The publication of this document signifies a call
for implementations of this specification. This specification
will remain a Candidate Recommendation at least until 15 March
2006.
This Working Draft addresses all the comments received during
the second Last Call review period on the WSDL 2.0
drafts. The detailed disposition of the comments received
can be found in the Last Call issues list.
A diff-marked version against the
previous version of this document is available. For a
detailed list of changes since the last publication of this
document, please refer to appendix .
The Working Group plans to submit
this specification for consideration as a W3C
Proposed Recommendation if the following exit criteria have
been met:
-
Two interoperable implementations of all the
features, both mandatory and optional, of the specifications
have been produced.
-
The Working Group releases a test suite along with an implementation
report.
The following features defined in this specification are considered at risk:
-
Serialization of the instance data in parts of the HTTP request IRI
(section ): feedback is sought on this topic
-
Definition of the Robust In-Only, In-Optional-Out, Out-Only,
Robust Out-Only, Out-In, Out-Optional-In message exchange
pattern (in section ): the Working
Group is intending to remove those definitions from the
specification if it does not have evidence of their use
Implementers are encouraged to provide feedback by
15 March 2006.
Comments on this document are to be sent to the public public-ws-desc-comments@w3.org
mailing list (public
archive).
Issues about this document are recorded in the Candidate Recommendation
issues list maintained by the Working Group. A list of formal
objections against the set of WSDL 2.0 Working Drafts is
also available.
Publication as a Candidate 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 has been produced under the 24
January 2002 Current Patent Practice as amended by the
W3C
Patent Policy Transition Procedure. Patent disclosures
relevant to this specification may be found on the Working
Group's patent
disclosure page. An individual who has actual knowledge of
a patent which the individual believes contains Essential
Claim(s) with respect to this specification should disclose the
information in accordance with section
6 of the W3C Patent Policy.
English
Last Modified: $Date: 2006/01/05 20:52:02 $ CET
Introduction
The Web Services Description Language WSDL Version 2.0 (WSDL)
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:
Message exchange patterns:
Operation safety declaration:
Operation styles:
Binding extensions:
A SOAP 1.2 binding extension:
An HTTP/1.1 binding extension:
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 of the WSDL 2.0
specification describes the core elements of the WSDL language.
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/2006/01/wsdl
|
This namespace is defined in .
A normative XML Schema ,
document for the
http://www.w3.org/2006/01/wsdl
namespace can be found at http://www.w3.org/2006/01/wsdl. This namespace is used as
the default namespace throughout this specification. |
| wsdlx |
http://www.w3.org/2006/01/wsdl-extensions
|
This specification extends in section the
http://www.w3.org/2006/01/wsdl-extensions namespace defined in .
A normative XML Schema ,
document for the
http://www.w3.org/2006/01/wsdl-extensions
namespace can be found at http://www.w3.org/2006/01/wsdl-extensions. |
| wsoap |
http://www.w3.org/2006/01/wsdl/soap
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/2006/01/wsdl/soap
namespace can be found at http://www.w3.org/2006/01/wsdl/soap. |
| whttp |
http://www.w3.org/2006/01/wsdl/http
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/2006/01/wsdl/http
namespace can be found at http://www.w3.org/2006/01/wsdl/http. |
| wrpc |
http://www.w3.org/2006/01/wsdl/rpc
|
Defined by this
specification. A normative XML Schema ,
document for the
http://www.w3.org/2006/01/wsdl/rpc
namespace can be found at http://www.w3.org/2006/01/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 .
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 this specification 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 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 .
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.
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.
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
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.
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
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
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
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
This 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
This pattern uses the rule .
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.
Robust In-Only
This 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
This pattern uses the rule .
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.
In-Out
This 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
This pattern uses the rule .
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.
In-Optional-Out
This pattern consists of one or 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
An optional message:
indicated by a Interface Message Reference component whose
message label is Out and
direction is out
sent to node N
This pattern uses the rule .
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.
Out-Only
This pattern consists of exactly one message as follows:
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is Out and direction is out
-
sent to some node N
This pattern uses the rule .
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.
Robust Out-Only
This pattern consists of exactly one message as follows:
message:
indicated by a Interface Message Reference component whose
message label is Out and
direction is out
sent to some node N
This pattern uses the rule .
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.
Out-In
This pattern consists of exactly two messages, in order, as follows:
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is Out and direction is out
-
sent to some node N
-
A message:
-
indicated by a Interface Message Reference component
whose message label
is In and direction is in
-
sent from node N
This pattern uses the rule .
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.
Out-Optional-In
This pattern consists of one or two messages, in order, as
follows:
A message:
indicated by a Interface Message Reference component whose
message label is Out and
direction is out
sent to some node N
An optional message:
indicated by a Interface Message Reference component whose
message label is In and
direction is in
sent from node N
This pattern uses the rule .
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.
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.
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 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
and .
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 . 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 ).
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 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).
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).
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/2006/01/wsdl/rpc"
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 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 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 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.
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 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.
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 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 . 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
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 , 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 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:
http version on Binding components, as defined in
http location on Binding Operation components, as defined in
http headers on Binding Message Reference and Binding Fault components, as defined in
http transfer
coding default on Binding and Binding Operation components, http transfer
coding 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/2006/01/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 subject
to optimization by a feature that is in use which may affect
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 will 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
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, 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 .
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/2006/01/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.
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/2006/01/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 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.
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/2006/01/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/2006/01/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
that uses this Binding component.
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.
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 an 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/2006/01/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/2006/01/wsdl/soap
-
A type of xs:anyURI
The following attribute information item for the binding element information item is
defined:
-
A [local name] of mepDefault
-
A [namespace name] of
http://www.w3.org/2006/01/wsdl/soap
-
A type of xs:anyURI
Mapping from XML Representation to Component Properties
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
action attribute information item, if any. |
Declaring SOAP Modules
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 ). 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.
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 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 identifies the
specific SOAP module that is in use.
-
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
component component 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/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:
-
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/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 .
-
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.
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/2006/01/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.
WSDL SOAP 1.2 Binding
Identifying a WSDL SOAP 1.2 Binding
A WSDL SOAP Binding is identified as a SOAP 1.2 binding by assigning the value
1.2 to the soap version property of the Binding component.
Description
The WSDL SOAP 1.2 binding extension defined in this section is an extension of the SOAP binding defined in section
to enable Web Service applications to use SOAP 1.2 .
The WSDL SOAP 1.2 binding extension supports
the SOAP 1.2 HTTP binding defined by the specification. This is indicated by
assigning the URI http://www.w3.org/2003/05/soap/bindings/HTTP/
(as defined by ) to the
soap underlying protocol property. Other values MAY be used
for this property in conjunction with the SOAP 1.2 binding extension
defined by this specification provided that the semantics of
such protocols are consistent with this binding extension.
Default rules in section
define the relationship between SOAP message exchange patterns
defined in and WSDL message
exchange patterns defined in section .
When the SOAP Message Exchange Pattern is the SOAP 1.2 Response
MEP and the underlying protocol is HTTP, the Binding Operation may use the
http location property
defined in section . When this
property is present on the Binding Operation component, the Endpoint component also follows the
rules for constructing the address from the address
property and the http location property values.
SOAP 1.2 Binding Rules
These binding rules
are applicable to SOAP 1.2 bindings.
SOAP Action Feature. The value of the
SOAP Action Feature for the initial message of the message exchange pattern
of the Interface Operation bound is specified by the soap action property of this
Binding Operation component. If the
Binding Operation component does NOT have a
soap action property
defined, then the SOAP Action Feature (see ) has NO value. Otherwise, its value is
the value of the SOAP Action Feature for the initial message
of the message exchange pattern.
SOAP MEP Selection.
For a given Interface Operation component, if
there is a Binding Operation component whose
interface operation
property matches the component in question and its soap mep property has a
value, then SOAP MEP is the value of the soap mep property. Otherwise, the SOAP MEP
is the value of the Binding component's soap mep default, if
any. Otherwise, if the Interface Operation
component's message
exchange pattern property has the value
http://www.w3.org/2006/01/wsdl/in-out, then the SOAP MEP is the URI
http://www.w3.org/2003/05/soap/mep/request-response/
identifying the SOAP Request-Response Message Exchange
Pattern as defined in .
Otherwise (i.e. if the Interface Operation
component has any other value for the message exchange pattern property), it is
an ERROR.
One-way MEP defaulting
The Web Services Description Working Group would like to
add a rule here defaulting to a standardized SOAP 1.2
one-way MEP for one-way operations if one becomes
available. Feedback is sought on this topic.
HTTP Method Selection. This default
binding rule is applicable when the value of the
soap underlying protocol property of the Binding component is
http://www.w3.org/2003/05/soap/bindings/HTTP/. If
the SOAP MEP selected as specified above has the value
http://www.w3.org/2003/05/soap/mep/request-response/
then the HTTP method used is
POST. If the SOAP MEP selected has the value
http://www.w3.org/2003/05/soap/mep/soap-response/
then the HTTP method used is
GET.
HTTP IRI Generation. This default
binding rule is applicable when the value of the
soap underlying protocol
property of the Binding component is
http://www.w3.org/2003/05/soap/bindings/HTTP/. If
the SOAP MEP selected is
http://www.w3.org/2003/05/soap/mep/soap-response/
then the value of the SOAP
http://www.w3.org/2003/05/soap/mep/ImmediateDestination property MUST be
generated using the HTTP binding extension's rules for generating a
IRI for HTTP GET (see ). The
input serialization format of
application/x-www-form-urlencoded is the only supported
serialization format for HTTP GET in the SOAP Response
Message Exchange Pattern.
This section describes the relationship between WSDL components and SOAP
1.2 MEP properties as described in .
Using SOAP Request-Response
When using the WSDL http://www.w3.org/2006/01/wsdl/in-out
message exchange pattern bound to a SOAP
http://www.w3.org/2003/05/soap/mep/request-response/
MEP
(as would be the case for a usual SOAP-over-HTTP In-Out operation),
this section describes the relationships. Extensions (such as ) MAY alter these
mappings.
The Client
As the client, the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
takes the value RequestingSOAPNode.
The SOAP http://www.w3.org/2003/05/soap/mep/ImmediateDestination
property takes the value of the WSDL address property of the
Endpoint component.
The WSDL In message is mapped to the SOAP
http://www.w3.org/2003/05/soap/mep/OutboundMessage property.
The WSDL Out message maps to the SOAP
http://www.w3.org/2003/05/soap/mep/InboundMessage property.
The Service
As the service, the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
takes the value RespondingSOAPNode.
The WSDL In message is mapped to the SOAP
http://www.w3.org/2003/05/soap/mep/InboundMessage property.
The WSDL Out message maps to the SOAP
http://www.w3.org/2003/05/soap/mep/OutboundMessage property.
Using SOAP-Response
When using the WSDL http://www.w3.org/2006/01/wsdl/in-out
message exchange pattern bound to a
http://www.w3.org/2003/05/soap/mep/soap-response/ SOAP MEP,
this section describes the relationships.
The Client
As the client, the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
takes the value RequestingSOAPNode.
The SOAP http://www.w3.org/2003/05/soap/mep/ImmediateDestination
property takes the value of the WSDL address property, modified
by the http location
property following the rules described in section .
The SOAP http://www.w3.org/2003/05/soap/mep/OutboundMessage property
has no value.
The WSDL Out message maps to the SOAP
http://www.w3.org/2003/05/soap/mep/InboundMessage property.
The Service
As the service, the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
takes the value RespondingSOAPNode.
The WSDL In message is constructed from the destination URI as per the
rules in section .
The WSDL Out message maps to the SOAP
http://www.w3.org/2003/05/soap/mep/OutboundMessage property.
Conformance
An element information item whose namespace name is http://www.w3.org/2006/01/wsdl
and whose local part is description conforms to this
binding extension specification if the element information items and attribute information items whose namespace
is http://www.w3.org/2006/01/wsdl/soap conform to the XML Schema for that element
or attribute as defined by this specification and additionally
adheres to all the constraints contained in this
specification.
WSDL HTTP Binding Extension
The HTTP binding extension described in this section is an extension for
to enable Web Services applications to use
HTTP 1.1 (as well as other versions of HTTP) and HTTPS . This binding extension extends WSDL 2.0
by adding properties to the component model 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 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 HTTP 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 all operations of an
Interface component are bound by an HTTP binding.
The internal
tree representation of an input, output or fault message is
called an instance data, and is constrained by
the schema definition associated the message: the XML element
referenced in the
element declaration
property of the
Interface Message Reference
component for input and output messages (unless the message content model is #any), and in the
element declaration
property of an
Interface Fault
component for faults.
Identifying the use of the HTTP Binding
A Binding component (defined in )
is identified as an HTTP binding by assigning the value
http://www.w3.org/2006/01/wsdl/http to the type property of
the Binding component.
HTTP Syntax Summary (Non-Normative)
<description>
<binding name="xs:NCName" interface="xs:QName"?
type="http://www.w3.org/2006/01/wsdl/http"
whttp:methodDefault="xs:string"?
whttp:queryParameterSeparatorDefault="xs:string"?
whttp:cookies="xs:boolean"?
whttp:version="xs:string"?
whttp:transferCodingDefault="xs:string"? >
<documentation />?
<fault ref="xs:QName"
whttp:code="union of xs:int, xs:token"?
whttp:transferCoding="xs:string"? >
<documentation />*
<whttp:header name="xs:string" type="xs:QName"
required="xs:boolean"? >
<documentation />*
</whttp:header>*
[ <feature /> | <property /> ]*
</fault>*
<operation ref="xs:QName"
whttp:location="xs:anyURI"?
whttp:method="xs:string"?
whttp:inputSerialization="xs:string"?
whttp:outputSerialization="xs:string"?
whttp:faultSerialization="xs:string"?
whttp:transferCodingDefault="xs:string"? >
<documentation />*
<input messageLabel="xs:NCName"?
whttp:transferCoding="xs:string? >
<documentation />*
<whttp:header ... />*
[ <feature /> | <property /> ]*
</input>*
<output messageLabel="xs:NCName"?
whttp:transferCoding="xs:string? >
<documentation />*
<whttp:header ... />*
[ <feature /> | <property /> ]*
</output>*
<infault ref="xs:QName"
messageLabel="xs:NCName"? >
<documentation />*
[ <feature /> | <property /> ]*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"? >
<documentation />*
[ <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>
HTTP Binding Rules
HTTP Method Selection
When formulating the HTTP message to be transmitted, the
HTTP request method used MUST be the following:
-
For a given Interface Operation component, if
there is a Binding Operation component whose
interface operation
property matches the component in question and its http method property has a
value, then the value of the http method property.
-
Otherwise, the value of the Binding component's http method default, if
any.
-
Otherwise, if a
safety property as defined in is present on the bound Interface Operation
component and has a value of true,
the value GET.
-
Otherwise, it is
an ERROR.
Payload Construction And Serialization Format
When formulating the HTTP message to be transmitted, the
contents of the payload (i.e. the contents of the HTTP message
body) MUST be what is defined by the corresponding Interface Message
Reference or Interface Fault components,
serialized as specified by the serialization format used.