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 a W3C
Working Draft of the Web Services Description Language (WSDL)
2.0 document. This document has been produced as part of the
W3C Web Services
Activity. The authors of this document are the Web Services Description Working
Group members.
This document is the result of the merge of WSDL 2.0 Part 2
Predefined Extensions and 3 Bindings.
The Working Group is in the process of addressing the comments
it has received on WSDL 2.0 Part 1, 2 and 3 during its Last Call
period. This document reflects the current state of this work. The
latest status of the last call issues received by the Working Group
can be found in the last call issues
list. The Working Group is planning to publish a new Last Call
Working Draft once it has closed all these issues.
Comments on this document are to be sent to the public public-ws-desc-comments@w3.org
mailing list (public
archive).
For a detailed list of changes since the last publication of
this document, please refer to appendix B.
Part 2 Change Log.
Publication as a Working Draft 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.
1. Introduction
The Web Services Description Language WSDL Version 2.0 (WSDL)
[WSDL 2.0 Core Language]
defines an XML language for describing network services as
collections of communication endpoints capable of exchanging
messages. WSDL service definitions provide documentation for
distributed systems and serve as a recipe for automating the
details involved in applications communication. This document
defines extensions for the WSDL 2.0 language:
WSDL 2.0 Primer [WSDL 2.0
Primer] is a non-normative document intended to provide
an easily understandable tutorial on the features of the WSDL
Version 2.0 specifications.
The Core Language [WSDL 2.0 Core
Language] of the WSDL 2.0 specification describes the
core elements of the WSDL language.
1.1 Notational
Conventions
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in RFC2119
[IETF RFC 2119].
This specification uses a number of namespace prefixes
throughout; they are listed in Table 1-1.
Note that the choice of any namespace prefix is arbitrary and not
semantically significant (see [XML
Information Set]).
Namespace names of the general form "http://example.org/..." and
"http://example.com/..." represent application or context-dependent
URIs [IETF RFC 3986].
All parts of this specification are normative, with the
EXCEPTION of pseudo-schemas, examples, and sections explicitly
marked as "Non-Normative". Pseudo-schemas are provided for each
component, before the description of this component. They provide
visual help for the XML [XML 1.0]
serialization.
2. Predefined Message Exchange
Patterns
A node is an agent (section
2.3.2.2 Agent of the Web Services Architecture [Web Services Architecture]) that can transmit
and/or receive message(s) described in WSDL description(s) and
process them.
Note:
A node may be accessible via more than one physical address or
transport.
Web Services Description Language (WSDL) message exchange
patterns (hereafter simply 'patterns') define the sequence and of
abstract messages listed in an operation. Message exchange patterns
also define which other nodes send messages to, and receive
messages from, the service implementing the operation. WSDL message
exchange patterns describe the interaction at the abstract
(interface) level, which may be distinct from the pattern used by
the underlying protocol binding (e.g. SOAP Message Exchange
Patterns; section 4.11.3 Default
Binding Rules contains the default binding rules for the
selection of a SOAP 1.2 message exchange pattern based on the WSDL
message exchange pattern in use for the SOAP binding defined in
this specification in section 4. WSDL
SOAP Binding).
By design, WSDL message exchange patterns abstract out specific
message types. Patterns identify placeholders for messages, and
placeholders are associated with specific message types by the
operation using the pattern.
Unless explicitly stated otherwise, WSDL message exchange
patterns also abstract out binding-specific information like timing
between messages, whether the pattern is synchronous or
asynchronous, and whether the message are sent over a single or
multiple channels.
Like interfaces and operations, WSDL message exchange patterns
do not exhaustively describe the set of messages exchanged between
a service and other nodes; by some prior agreement, another node
and/or the service may send other messages (to each other or to
other nodes) that are not described by the pattern. For instance,
even though a pattern may define a single message sent from a
service to one other node, the Web Service may multicast that
message to other nodes.
To maximize reuse, WSDL message exchange patterns identify a
minimal contract between other parties and Web Services, and
contain only information that is relevant to both the Web Service
and another party.
This specification defines several message exchange patterns for
use with WSDL Version 2.0 Part 1: Core Language
[WSDL 2.0 Core
Language].
2.1 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 to the recipient specified by the ruleset.
However, extensions or bindings 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.
Bindings, features, or extension specifications may override the
semantics of a fault propagation ruleset, but this practice is
strongly discouraged.
2.1.1
Fault Replaces Message
Any message after the first in the pattern MAY be replaced with
a fault message, which MUST have identical direction. The fault
message MUST be delivered to the same target node as the message it
replaces. If there is no path to this node, the fault MUST be
discarded.
2.1.2 Message
Triggers Fault
Any message, including the first, MAY trigger a fault message in
response. Each recipient MAY propagate a fault message, and MUST
propagate no more than one fault for each triggering message. Each
fault message has direction the reverse of its triggering message.
The fault message MUST be delivered to the originator of the
message which triggered it. If there is no path to this node, the
fault MUST be discarded.
2.1.3 No Faults
No faults may be propagated.
2.2 Message Exchange
Patterns
WSDL patterns are described in terms of the WSDL component
model, specifically the Message Label and Fault Reference
components.
2.2.1 In-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.1.3 No
Faults.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/in-only'.
2.2.2 Robust
In-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.1.2
Message Triggers Fault.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/robust-in-only'.
2.2.3 In-Out
This pattern consists of exactly two messages, in order, as
follows:
-
A message:
-
A message:
This pattern uses the rule 2.1.1
Fault Replaces Message.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/in-out'.
2.2.4
In-Optional-Out
This pattern consists of one or two messages, in order, as
follows:
-
A message:
-
An optional message:
This pattern uses the rule 2.1.2
Message Triggers Fault.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/in-opt-out'.
2.2.5 Out-Only
This pattern consists of exactly one message as follows:
-
A message:
This pattern uses the rule 2.1.3 No
Faults.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/out-only'.
2.2.6 Robust
Out-Only
This pattern consists of exactly one message as follows:
-
message:
This pattern uses the rule 2.1.2
Message Triggers Fault.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/robust-out-only'.
2.2.7 Out-In
This pattern consists of exactly two messages, in order, as
follows:
-
A message:
-
A message:
This pattern uses the rule 2.1.1
Fault Replaces Message.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/out-in'.
2.2.8
Out-Optional-In
This pattern consists of one or two messages, in order, as
follows:
-
A message:
-
An optional message:
This pattern uses the rule 2.1.2
Message Triggers Fault.
An operation using this message exchange pattern has a {pattern}
property with the value
'http://www.w3.org/2005/05/wsdl/out-opt-in'.
3. Predefined Operation
Styles
This section defines
operation styles used by serialization formats to place
constraints on Interface Operations bound.
3.1 RPC Style
The RPC style is selected by assigning to an Interface Operation
component's
{style} property the value
http://www.w3.org/2005/05/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 3.1.1
wrpc:signature Extension and 3.1.2 XML
Representation of the wrpc:signature Extension.
The RPC style MUST NOT be used for Interface Operation
components whose
{message exchange pattern} property has a value other than
'http://www.w3.org/2005/05/wsdl/in-only' or
'http://www.w3.org/2005/05/wsdl/in-out'.
The RPC style places restrictions for Remote Procedure
Call-types of interactions. When this value is used, the associated
messages MUST conform to the rules below, described using XML
Schema [XML Schema
Structures]. Note that operations containing messages
described by other type systems may also indicate use of the RPC
style, as long as they are constructed in such a way as to follow
these rules.
If the Interface Operation component uses a
{message exchange pattern} for which there is no output
element, i.e. 'http://www.w3.org/2005/05/wsdl/in-only', then the
conditions stated below that refer to output elements MUST be
considered to be implicitly satisfied.
-
The content model of input and output
{element} 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 attributes.
-
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.
3.1.1
wrpc:signature Extension
The wrpc:signature extension attribute
information item MAY be used in conjunction with the RPC style
to describe the exact signature of the function represented by an
operation that uses the RPC style.
When present, the wrpc:signature extension
contributes the following property to the interface operation
component it is applied to:
-
{rpc-signature} REQUIRED. A list of pairs (q, t) whose
first component is of type xs:QName and whose second
component is of type xs:token. Values for the second
component MUST be chosen among the following four: "#in", "#out",
"#inout" "#return".
The value of the {rpc-signature} property MUST satisfy the
following conditions:
-
The value of the first component of each pair (q, t)
MUST be unique within the list.
-
For each child element of the input and output messages of the
operation, a pair (q, t) whose first component q
is equal to the qualified name of that element MUST be present in
the list, with the caveat that elements that appear with
cardinality greater than one MUST be treated as a single
element.
-
For each pair (q, #in), there MUST be a child element
of the input element with a name of q and there MUST NOT
be a child element of the output element with the same name.
-
For each pair (q, #out), there MUST be a child element
of the output element with a name of q and there MUST NOT
be a child element of the input element with the same name.
-
For each pair (q, #inout), there MUST be a child
element of the input element with a name of q and there
MUST be a child element of the output element with the same name.
Furthermore, those two elements MUST have the same type.
-
For each pair (q, #return), there MUST be a child
element of the output element with a name of q and there
MUST NOT be a child element of the input element with the same
name.
The function signature defined by a wrpc:signature
extension is determined as follows:
-
Start with the value of the {rpc-signature} property, a
(possibly empty) list of pairs of this form:
[(q0, t0), (q1, t1), ...]
-
Filter the elements of this list into two lists, the first one
(L1) comprising pairs whose t component is one of
{#in, #out, #inout}, the second (L2) pairs whose
t component is #return. During the composition of
L1 and L2, the relative order of members in the
original list MUST be preserved.
For ease of visualization, let's denote the two lists as
(L1) [(a0,
u0), (a1, u1),...]
and
(L2) [(r0,
#return), (r1, #return),...]
respectively.
-
Then, if the input sequence ends with an element wildcard, the
formal signature of the function is
f([d0] a0, [d1] a1, ..., rest) =>
(r0, r1, ...)
where rest is a formal parameter representing the
elements in the input message matched by the element wildcard.
Otherwise the formal signature of the function is
f([d0] a0, [d1] a1, ...) => (r0,
r1, ...)
i.e.
-
the list of formal arguments to the function is [a0, a1,
...];
-
the direction d of each formal argument a is
one of [in], [out], [inout], determined
according to the value of its corresponding u token;
-
the list of formal return parameters of the function is [r0,
r1, ...];
-
each formal argument and formal return parameter is typed
according to the type of the child element identified by it (unique
per the conditions given above).
Note:
The wrpc:signature extension allows the
specification of multiple return values for an operation. Several
popular programming languages support multiple return values for a
function. Moreover, for languages who do not, the burden on
implementors should be small, as typically multiple return values
will be mapped to a single return value of a structure type (or its
closest language-specific equivalent).
3.1.2 XML
Representation of the wrpc:signature Extension
The XML representation for the RPC signature extension is an
attribute information item with the following Infoset
properties:
The type of the name attribute information
item is a list type whose item type is the union of the
xs:QName type and the subtype of the xs:token
type restricted to the following four values: "#in", "#out",
"#inout", "#return". See Example
3-1 for a definition of this type.
Additionally, each even-numbered item (0, 2, 4, ...) in the list
MUST be of type xs:QName and each odd-numbered item (1, 3,
5, ...) in the list MUST be of the subtype of xs:token
described in the previous paragraph.
Example
3-1. Definition of the wrpc:signature extension
<xs:attribute name="signature" type="wrpc:signatureType"/>
<xs:simpleType name="signatureType">
<xs:list itemType="wrpc:signatureItemType"/>
</xs:simpleType>
<xs:simpleType name="signatureItemType">
<xs:union memberTypes="wrpc:directionToken xs:QName"/>
</xs:simpleType>
<xs:simpleType name="directionToken">
<xs:restriction base="xs:token">
<xs:enumeration value="#in"/>
<xs:enumeration value="#out"/>
<xs:enumeration value="#inout"/>
<xs:enumeration value="#return"/>
</xs:restriction>
</xs:simpleType>
3.1.3
wrpc:signature Extension Mapping To Properties of an
Interface Operation Component
A wrpc:signature extension attribute
information item is mapped to the following property of the
Interface Operation component defined by its [owner].
Table 3-1. Mapping of a wrpc:signature
Extension to Interface Operation Component Properties
| Property |
Value |
| {rpc-signature} |
A list of (xs:QName, xs:token)
pairs formed by grouping the items present in the actual value of
the wrpc:signature attribute information item
in the order in which they appear there. |
3.2 URI Style
The URI style may be used for Interface Operation components
using a message exchange pattern with an initial message.
The URI style is selected by assigning the Interface Operation
component's
{style} property the value
http://www.w3.org/2005/05/wsdl/style/uri.
Use of this value indicates that XML Schema [XML Schema Structures] was used to define
the schema of the
{element} 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 element 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.
3.3 Multipart
style
The Multipart style may be used for Interface Operation
components using a message exchange pattern with an initial
message.
The Multipart style is selected by assigning the Interface
Operation component's
{style} property the value
http://www.w3.org/2005/05/wsdl/style/multipart.
Use of this value indicates that XML Schema [XML Schema Structures] was used to define
the schema of the
{element} 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.
4. WSDL SOAP
Binding
The SOAP binding described in this section is SOAP version
independent ("1.2" as well as other versions) and an extension for
[WSDL 2.0 Core Language] to
enable Web Services applications to use SOAP. This binding extends
WSDL 2.0 by adding properties to the Binding
component as defined in [WSDL 2.0
Core Language]. In addition, an XML Infoset
representation for these additional properties is provided, along
with a mapping from that representation to the various component
properties.
As allowed in [WSDL 2.0 Core
Language], a Binding component MAY exist without
indicating a specific Interface
component that it applies to. In this case, there MUST NOT be
any Binding
Operation or Binding
Fault components present in the Binding component.
The SOAP binding is designed with the objective of minimizing
what needs to be explicitly declared for common cases. This is
achieved by defining a set of default rules which apply for all
Interface Operation components of an Interface component, unless
specifically overidden on a per Interface Operation basis. Thus, if
a given Interface Operation component is not referred to
specifically, then all the default rules apply for that component.
That is, per the requirements of [WSDL
2.0 Core Language], all operations of an Interface
component are bound by this binding.
Notice that there are no default binding rules defined for
Interface
Fault components by this binding, as no reasonable default is
applicable to all cases. Thus, if a given Interface component has
any Fault components, then such Interface components MUST be bound
via Binding components which indicate a specific interface and
contain as many Binding Fault components as there are Fault
components in the Interface Fault component.
A subset of the HTTP properties specified in the HTTP binding
defined in section 5. WSDL HTTP
Binding 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:
4.1 XML Syntax
Summary (Non-Normative)
<description>
<binding name="xs:NCName" interface="xs:QName"?
type="http://www.w3.org/2005/05/wsdl/soap"
whttp:version="xs:string"??
whttp:transferCodingDefault="xs:string"??
wsoap:version="xs:string"?
wsoap:protocol="xs:anyURI"
wsoap:mepDefault="xs:anyURI"? >
<documentation />?
<wsoap:module uri="xs:anyURI" required="xs:boolean"? >
<documentation />?
</wsoap:module>*
<fault ref="xs:QName"
wsoap:code="xs:QName"
wsoap:subcodes="list of xs:QName"? >
<documentation />?
<wsoap:module ... />*
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?>
<documentation />?
</wsoap:header>*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</fault>*
<operation ref="xs:QName"
whttp:location="xs:anyURI"??
whttp:transferCodingDefault="xs:string"?? >
wsoap:mep="xs:anyURI"?
wsoap:action="xs:anyURI"? >
<documentation />?
<wsoap:module ... />*
<input messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />?
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</input>*
<output messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />?
<wsoap:module ... />*
<wsoap:header ... />*
<whttp:header ... />*??
[ <feature /> | <property /> ]*
</output>*
<infault ref="xs:QName"
messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />?
<wsoap:module ... />*
[ <feature /> | <property /> ]*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"?? >
<documentation />?
<wsoap:module ... />*
[ <feature /> | <property /> ]*
</outfault>*
[ <feature /> | <property /> ]*
</operation>*
[ <feature /> | <property /> ]*
</binding>
<service>
<endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"?
whttp:authenticationType="xs:string"??
whttp:authenticationRealm="xs:string"?? >
<documentation />?
[ <feature /> | <property /> ]*
</endpoint>
[ <feature /> | <property /> ]*
</service>
</description>
Note:
The double question marks ("??") after the
attributes in the whttp namespace indicates that those
optional attributes only make sense when the SOAP binding uses HTTP
as the underlying protocol, for example, when the value of the
wsoap:protocol attribute is
"http://www.w3.org/2003/05/soap/bindings/HTTP/".
4.2
Identifying the use of the SOAP Binding
A Binding component (defined in [WSDL 2.0 Core Language]) is identified as
a SOAP binding by assigning the value
"http://www.w3.org/2005/05/wsdl/soap" to the {type}
property of the Binding component.
4.3 Default
Binding Rules
-
Payload Construction. When formulating the SOAP
envelope to be transmitted the contents of the payload (i.e., the
contents of the SOAP Body element information item of the
SOAP envelope) MUST be what is defined by the corresponding
Interface Message Reference component. This is subject to
optimization by a feature that is in use which may affect
serialization, such as MTOM [SOAP Message
Transmission Optimization Mechanism]. The following
default binding rules MUST be adhered to:
-
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} 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
[WSDL 2.0 Core Language])
then additional binding rules MUST be defined to indicate how to
map those components into the SOAP envelope.
Note:
This SOAP binding only allows one single element in SOAP
body.
-
SOAP Header Construction. If the {soap headers}
property as defined in section 4.10
Declaring SOAP Header Blocks exists and is not empty in a
Binding Message Reference or Binding Fault component, element
information item conforming to the element declaration of a
SOAP Header Block component's {element} property, in the {soap
headers} property, MUST be turned into a SOAP header block for the
corresponding message.
And, if the SOAP Header Block component's {mustUnderstand}
property is present and its value is "true", that particular SOAP
header block should be marked with a mustUnderstand
attribute information item with a value of "true" or "1"
as per the SOAP specification.
SOAP header blocks other than the ones declared in the {soap
headers} property may be present at run-time, such as the SOAP
header blocks resulting from SOAP modules declared as explained in
section 4.9 Declaring SOAP
Modules.
4.4 Specifying the
SOAP Version
4.4.1 Description
Every SOAP binding MUST indicate what version of SOAP is in use
for the operations of the interface that this binding applies
to.
By default, SOAP 1.2 [SOAP 1.2
Part 1: Messaging Framework] is used.
4.4.2 Relationship to WSDL Component
Model
The SOAP protocol specification adds the following property to
the WSDL component model (as defined in [WSDL 2.0 Core Language]):
4.4.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:version="xs:string"? >
...
</binding>
</description>
The XML representation for specifying the SOAP version is an
optional attribute information item with the following
Infoset properties:
4.4.4 Mapping from XML
Representation to Component properties
See Table 4-1.
Table 4-1. Mapping from XML Representation to Binding
Component Extension Properties
| Property |
Value |
| {soap version} |
The actual value of the
wsoap:version attribute information item if
present, otherwise "1.2". |
4.5 Specifying
the SOAP Underlying Protocol
4.5.1 Description
Every SOAP binding MUST indicate what underlying protocol is in
use.
4.5.2 Relationship to WSDL Component
Model
The SOAP protocol specification adds the following property to
the WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{soap underlying protocol}, a xs:anyURI, which is an
absolute URI as defined by [IETF RFC
3986], to the Binding component.
4.5.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:protocol="xs:anyURI" >
...
</binding>
</description>
The XML representation for specifying the SOAP protocol is a
REQUIRED attribute information item with the following
Infoset properties:
4.5.4 Mapping from XML
Representation to Component Properties
See Table 4-2.
Table 4-2. Mapping from XML Representation to Binding
Component Extension Properties
| Property |
Value |
| {soap underlying protocol} |
The actual value of the
wsoap:protocol attribute information
item. |
4.6 Specifying the Default SOAP
MEP
4.6.1 Description
Every Binding Operation component of a SOAP binding MUST
indicate the SOAP Message Exchange Pattern (MEP) to be used for
that operation. This binding specification allows the user to
indicate a default SOAP MEP to be used for all Binding Operation
components of this Binding component.
4.6.2 Relationship to WSDL
Component Model
The default SOAP MEP specification is a syntactic convenience
and does not affect the underlying component model.
4.6.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:protocol="xs:anyURI"
wsoap:mepDefault="xs:anyURI ?" >
...
</binding>
</description>
The XML representation for specifying the default SOAP MEP is an
OPTIONAL attribute information item with the following
Infoset properties:
4.7 Binding
Faults
4.7.1 Description
For every Interface Fault component contained in an Interface
component, a mapping to a SOAP Fault must be described. This
binding specification allows the user to indicate the SOAP fault
code and subcodes that are transmitted for a given Interface Fault
component.
4.7.2 Relationship to WSDL Component
Model
The SOAP Fault binding adds the following properties to the WSDL
component model (as defined in [WSDL
2.0 Core Language]):
-
{soap fault code}, a xs:QName, to the Binding Fault
component. The value of this property identifies a possible SOAP
fault for the operations in scope.
-
{soap fault subcodes}, a list of xs:QName, to the
Binding Fault component. The value of this property identifies one
or more subcodes for this SOAP fault.
4.7.3 XML Representation
<description>
<binding >
<fault ref="xs:QName"
wsoap:code="xs:QName"
wsoap:subcodes="list of xs:QName"? >
<documentation />?
[ <feature /> | <property /> ]*
</fault>*
</binding>
</description>
The XML representation for binding a SOAP Fault are two
attribute information items with the following Infoset
properties:
4.7.4 Mapping XML Representation to
Component Properties
See Table 4-3.
Table 4-3. Mapping from XML Representation to SOAP Fault
Component Properties
| Property |
Value |
| {soap fault code} |
The actual value of the
code attribute information item. |
| {soap fault subcodes} |
The actual value of the
subcodes attribute information item. |
4.8
Binding Operations
4.8.1 Description
For every Interface Operation component contained in an
Interface component, in addition to the default binding rules (for
SOAP 1.2, see 4.11.3 Default Binding
Rules), there may be additional binding information to be
specified. This binding 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.
4.8.2 Relationship to WSDL
Component Model
The SOAP Operation binding specification adds the following
property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{soap mep}, a xs:anyURI, which is an absolute URI as
defined by [IETF RFC 3986], to
the Binding Operation component. The value of this property
identifies the SOAP Message Exchange Pattern (MEP) for this
specific operation. If no specific value is assigned, then the
value assigned by the default rules apply (for SOAP 1.2, see
4.11.3 Default Binding
Rules). It is an error for this property to not have a
value (which MAY happen if the default rules are not
applicable).
-
{soap action}, a xs:anyURI, which is an absolute URI as
defined by [IETF RFC 3986], to
the Binding Operation component. The value of this property
identifies the value of the SOAP Action Feature (as defined for
this specific operation).
4.8.3 XML Representation
<description>
<binding >
<operation ref="xs:QName"
wsoap:mep="xs:anyURI"?
wsoap:action="xs:anyURI"? >
</operation>
</binding>
</description>
The XML representation for binding an Operation are two
attribute information items with the following Infoset
properties:
4.8.4 Mapping from XML
Representation to Component Properties
See Table 4-4.
Table 4-4. Mapping from XML Representation to SOAP
Operation Component Properties
| Property |
Value |
| {soap mep} |
The actual value of the
wsoap:mep attribute information item, if
present. If not, the actual value of the
wsoap:mepDefault attribute information item
of the parent wsdl:binding element information item, if
present. If not the value as defined by the default SOAP binding
rules (for SOAP 1.2, see 4.11.3
Default Binding Rules), if applicable. |
| {soap action} |
The actual value of the
action attribute information item., if
any. |
4.9
Declaring SOAP Modules
4.9.1 Description
In SOAP, it is permissible for specification interaction to
engage one or more additional features (typically implemented as
one or more SOAP header blocks), as defined by SOAP Modules (see
[SOAP 1.2 Part 1: Messaging
Framework]). This binding specification allows users to
indicate which SOAP Modules are in use across the entire binding,
on a per operation basis or on a per message basis.
4.9.2 Relationship to WSDL Component
Model
The SOAP Module component adds the following property to the
WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{soap modules}, a set of SOAP Module components as defined in
4.9.3 SOAP Module
Component, to the Binding, Binding Operation, Binding
Message Reference, Binding Fault and Binding Fault Reference
components.
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.
4.9.3 SOAP Module Component
The SOAP Module component identifies a SOAP module that is in
use. The properties of the SOAP Module component are as
follows:
-
{uri} REQUIRED. A xs:anyURI, which is an absolute URI
as defined by [IETF RFC 3986].
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.
4.9.4 XML Representation
<description>
<binding >
<wsoap:module uri="uri"
required="boolean"? >
<documentation ... />?
</wsoap:module>
<fault>
<wsoap:module ... />*
</fault>
<operation>
<wsoap:module ... />*
<input>
<wsoap:module ... />*
</input>
<output>
<wsoap:module ... />*
</output>
<infault>
<wsoap:module ... />*
</infault>
<outfault>
<wsoap:module ... />*
</outfault>
</operation>
</binding>
</description>
The XML representation for a SOAP Module component is an
element information item with the following Infoset
properties:
-
A [local name] of module
-
A [namespace name] of "http://www.w3.org/2005/05/wsdl/soap"
-
One or more attribute information items amongst its
[attributes] as follows:
-
A REQUIRED uri attribute information item
with the following Infoset properties:
-
An OPTIONAL required attribute information
item with the following Infoset properties:
-
Zero or more namespace qualified attribute information
items. The [namespace name] of such attribute information
items MUST NOT be "http://www.w3.org/2005/05/wsdl" and MUST
NOT be "http://www.w3.org/2005/05/wsdl/soap".
-
Zero or more element information item amongst its
[children], in order, as follows:
-
An OPTIONAL documentation element information
item as defined in [WSDL 2.0 Core
Language].
-
Zero or more namespace-qualified element information
items amongst its [children]. The [namespace name] of such
element information items MUST NOT be
"http://www.w3.org/2005/05/wsdl" and MUST NOT be
"http://www.w3.org/2005/05/wsdl/soap".
4.9.5 Mapping from XML
Representation to Component Properties
See Table 4-5.
Table 4-5. Mapping from XML Representation to SOAP Module
Component Properties
| Property |
Value |
| {soap modules} |
The set of SOAP Modules 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. |
| {uri} |
The actual value of the
uri attribute information item. |
| {required} |
The actual value of the
required attribute information item if
present, otherwise false. |
4.10
Declaring SOAP Header Blocks
4.10.1 Description
SOAP allows the use of header blocks in the header part of the
message. This binding allows users to declare the SOAP header
blocks in use on a per message ond on a per fault basis.
4.10.2 Relationship to WSDL
Component Model
The SOAP Header Blocks binding specification adds the following
property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{soap headers}, OPTIONAL, a set of SOAP Header Block components
as defined in 4.10.3 SOAP
Header Block Component, to the Binding Fault and Binding
Message Reference components.
4.10.3 SOAP Header Block
Component
A SOAP Header Block component describes an abstract piece of
header data (message headers) that is associated with the exchange
of messages between the communicating parties. The presence of a
SOAP Header Block component in a WSDL description indicates that
the service supports headers and MAY require a Web service
consumer/client that interacts with the service to use the
described header. Zero or more such headers may be used.
The properties of the SOAP Header Block component are as
follows:
-
{element} REQUIRED. A xs:QName, a reference to an XML
element declaration in the {element
declarations} property of the Description Component. This
element represents a SOAP header block.
-
{mustUnderstand} REQUIRED. A xs:boolean indicating if
the SOAP header block MUST be decorated with a SOAP
mustUnderstand attribute information
item.
4.10.4 XML Representation
<description>
<binding name="xs:NCName" type="http://www.w3.org/2005/05/wsdl/soap" >
<fault ref="xs:QName"
wsoap:code="xs:QName" >
<wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?>
<documentation />?
</wsoap:header>*
...
</fault>*
<operation ref="xs:QName" >
<input messageLabel="xs:NCName"?>
<wsoap:header ... />*
...
</input>*
<output messageLabel="xs:NCName"?>
<wsoap:header ... />*
...
</output>*
</operation>*
</binding>
</description>
The XML representation for a SOAP Header Block component is an
element information item with the following Infoset
properties:
-
A [local name] of header
-
A [namespace name] of "http://www.w3.org/2005/05/wsdl/soap"
-
One or more attribute information items amongst its
[attributes] as follows:
-
A REQUIRED element attribute information
item with the following Infoset properties:
-
An OPTIONAL mustUnderstand attribute
information item with the following Infoset properties:
-
Zero or more namespace qualified attribute information
items. The [namespace name] of such attribute information
items MUST NOT be "http://www.w3.org/2005/05/wsdl" and MUST
NOT be "http://www.w3.org/2005/05/wsdl/soap".
-
Zero or more element information item amongst its
[children], in order, as follows:
-
An OPTIONAL documentation element information
item as defined in [WSDL 2.0 Core
Language].
-
Zero or more namespace-qualified element information
items amongst its [children]. The [namespace name] of such
element information items MUST NOT be
"http://www.w3.org/2005/05/wsdl" and MUST NOT be
"http://www.w3.org/2005/05/wsdl/soap".
4.10.5 Mapping XML Representation
to Component Properties
See Table 4-6.
Table 4-6. Mapping from XML Representation to SOAP Header
Block Component Properties
| Property |
Value |
| {soap headers} |
The set of SOAP Header Block components
corresponding to all the header element
information item in the [children] of the fault ,
input or output element information
item, if any. |
| {element} |
The element declaration from the
{element
declarations} resolved to by the value of the
element attribute information item. It is an
error for the element attribute information
item to have a value and that value does not resolve to a
global element declaration from the {element
declarations} property of the Description component. |
| {mustUnderstand} |
The actual value of the
mustUnderstand attribute information item if
present, otherwise false. |
4.11 SOAP 1.2
Binding
4.11.1 Identifying a SOAP 1.2
Binding
A 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.
4.11.2 Description
The SOAP 1.2 binding defined in this section is an extension of
the 4. WSDL SOAP Binding to
enable Web Service applications to use SOAP 1.2 [SOAP 1.2 Part 1: Messaging
Framework].
The SOAP 1.2 binding supports the SOAP 1.2 HTTP binding defined
by the [SOAP 1.2 Part 2:
Adjuncts] specification. This is indicated by assigning
the URI "http://www.w3.org/2003/05/soap/bindings/HTTP/" (as defined
by [SOAP 1.2 Part 2:
Adjuncts]) to the {soap underlying protocol} property.
Other values MAY be used for this property in conjunction with the
SOAP 1.2 binding defined by this specification provided that the
semantics of such protocols are consistent with this binding.
Default rules in section 4.11.3
Default Binding Rules define the relationship between SOAP
message exchange patterns defined in [SOAP 1.2 Part 2: Adjuncts] and WSDL
message exchange patterns defined in 2.
Predefined Message Exchange Patterns.
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 5.6 Binding Operations. When such
a location is specified, the Endpoint component also follows the
rules for constructing the address from the {address}
property and the {http location} property values.
4.11.3
Default Binding Rules
These default binding rules are applicable to SOAP 1.2
binding.
-
SOAPAction. If a value for the {soap action} property
of a Binding Operation component has NOT been specified then the
SOAP Action Feature (see [SOAP 1.2
Part 2: Adjuncts]) has NO value assigned by the Binding
component.
-
SOAP MEP Selection. If the Interface Operation
component's
{message exchange pattern} property has the value
"http://www.w3.org/2005/05/wsdl/in-out" then the default value of
the {soap mep} property for the corresponding Binding Operation
component is "http://www.w3.org/2003/05/soap/mep/request-response/"
identifying the SOAP Request-Response Message Exchange Pattern as
defined in [SOAP 1.2 Part 2:
Adjuncts]. If the Interface Operation component has any
other value for the
{message exchange pattern} property, then no default value is
defined for the {soap mep} property of the corresponding Binding
Operation component.
-
HTTP Method Selection. This default binding rule is
applicable when the value of the {soap underlying protocol}
property of the Binding component is
"http://www.w3.org/2003/05/soap/bindings/HTTP/". If the {soap mep}
property of the Binding Operation component has the value
"http://www.w3.org/2003/05/soap/mep/request-response/" then the
default value of the {http method} property is POST. If
the {soap mep} property of the Binding Operation component has the
value "http://www.w3.org/2003/05/soap/mep/soap-response/" then the
default value of the {http method} property is GET.
-
HTTP URI Generation. This default binding rule is
applicable when the value of the {soap underlying protocol}
property of the Binding component is
"http://www.w3.org/2003/05/soap/bindings/HTTP/". If the {soap mep}
property of the Binding Operation component has the value
"http://www.w3.org/2003/05/soap/mep/soap-response/" then the URI to
execute the HTTP GET against MUST be generated using the HTTP
binding's rules for generating a URI for HTTP GET (see 5. WSDL HTTP Binding). The input
serialization format of x-www-form-urlencoded is the
only supported serialization format for HTTP GET in the SOAP
Response Message Exchange Pattern.
| Editorial note: Input
serialization for HTTP GET in SOAP HTTP binding |
|
Use of a different input
serialization format requires introduction of either a new MEP or a
new binding. The Working Group considered the limitations of the
x-www-form-urlencoded serialization format (see
points #2 and #3 of Binding message content to URI analysis).
It decided that the limitations of the serialization format, which
could potentially be solved by a serialization format extension,
were not sufficiently broad enough to warrant allowing
extensibility in input serialization for the soap-response MEP. The
Working Group solicits the public's feedback on this decision. |
4.12
Conformance
An element information item whose namespace name is
"http://www.w3.org/2005/05/wsdl" and whose local part is
description conforms to this binding specification if
the element information items and attribute
information items whose namespace is
http://www.w3.org/2005/05/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.
5. WSDL HTTP
Binding
The HTTP binding described in this section is an extension for
[WSDL 2.0 Core Language] to
enable Web Services applications to use HTTP 1.1 [IETF RFC 2616] (as well as other versions of
HTTP) and HTTPS [IETF RFC
2818]. This binding extends WSDL 2.0 by adding
properties to the component model defined in [WSDL 2.0 Core Language]. In addition an
XML Infoset representation for these additional properties is
provided, along with a mapping from that representation to the
various component properties.
As allowed in [WSDL 2.0 Core
Language], a Binding component MAY exist without
indicating a specific Interface component that it applies to. In
this case there MUST NOT be any Binding Operation or Binding Fault
components present in the Binding component.
The HTTP binding is designed with the objective of minimizing
what needs to be explicitly declared for common cases. This is
achieved by defining a set of default rules which apply for all
Interface Operation components of an Interface component, unless
specifically overidden on a per Interface Operation basis. Thus, if
a given Interface Operation component is not referred to
specifically, then all the default rules apply for that component.
That is, per the requirements of [WSDL
2.0 Core Language] all operations of an Interface
component are bound by this binding.
Notice that there are no default binding rules defined for Fault
components by this binding, as no HTTP fault code is suitable as a
default for all possible cases. Thus, if a given Interface
component has any Fault components, then such Interface components
MUST be bound via Binding components which indicate a specific
interface and contain as many Binding Fault components as there are
Fault components in the Interface Fault component.
[Definition: 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} property of the Interface Message Reference component
for input and output messages, and in the
{element} property of an Interface Fault component for
faults.]
5.1
Identifying the use of the HTTP Binding
A Binding component (defined in [WSDL 2.0 Core Language]) is identified as
an HTTP binding by assigning the value
"http://www.w3.org/2005/05/wsdl/http" to the {type}
property of the Binding component.
5.2 HTTP Syntax
Summary (Non-Normative)
<description>
<binding name="xs:NCName" interface="xs:QName"?
type="http://www.w3.org/2005/05/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="xs:int"?
whttp:reasonPhrase="xs:string"? >
<documentation />?
<whttp:header element="xs:QName" >
<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"?
whttp:transferCoding="xs:string"? >
<documentation />?
[ <feature /> | <property /> ]*
</infault>*
<outfault ref="xs:QName"
messageLabel="xs:NCName"?
whttp:transferCoding="xs:string"? >
<documentation />?
[ <feature /> | <property /> ]*
</outfault>*
[ <feature /> | <property /> ]*
</operation>*
[ <feature /> | <property /> ]*
</binding>
<service>
<endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"?
whttp:authenticationType="xs:string"?
whttp:authenticationRealm="xs:string"? >
<documentation />?
[ <feature /> | <property /> ]*
</endpoint>
[ <feature /> | <property /> ]*
</service>
</description>
5.3 Default Binding
Rules
-
HTTP Method Declaration. When formulating the HTTP
message to be transmitted, the HTTP request method MUST be what is
defined by the whttp:method attribute on
operation , or with the
whttp:methodDefault attribute on binding
.
-
Payload construction. 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:
-
Interface Message Reference component: if the value of the
{message content model} property is #any then the
payload MAY be any one XML element. If the value is #none
then the payload MUST be empty. Finally if the value is
#element then the payload will be the element
information item identified by the
{element} property.
-
Interface Fault component: the payload will be the element
information item identified by the
{element} property.
If the Interface Message Reference component or the Interface
Fault component is declared using a non-XML type system (as
considered in the Types section of [WSDL 2.0 Core Language]) then additional
binding rules MUST be defined to indicate how to map those
components into the HTTP envelope.
-
Serialization format. The HTTP request serialization
format MUST be what is defined by the {http input serialization}
property. The HTTP response serialization format MUST be what is
defined by the {http output serialization} property. The HTTP
serialization format of a fault MUST be what is defined by the
{http fault serialization} property.
Section 5.9 Serialization
Format of Instance Data defines serialization formats
supported by this binding along with their constraints.
-
Default input and output serialization format. Table 5-1 defines the default values for the
GET, POST, PUT and DELETE values of the {http method} property.
Table 5-1. Default values for GET, POST, PUT and
DELETE
| HTTP Method |
Default Input Serialization |
Default Output Serialization |
| {http method} |
{http input serialization} |
{http output serialization} |
| GET |
application/x-www-form-urlencoded |
application/xml |
| POST |
application/xml |
application/xml |
| PUT |
application/xml |
application/xml |
| DELETE |
application/x-www-form-urlencoded |
application/xml |
The default values for the {http input serialization} and {http
output serialization} properties for any other value of the {http
method} method is application/xml.
Mechanisms other than setting the serialization properties MAY
modify the serialization format of the instance data corresponding to the
message. An example of such modification is the WSDL SOAP Binding
HTTP URI Serialization rules specified in 4.3 Default Binding Rules. This binding
specifies that the SOAP-Response
Message Exchange Pattern ([SOAP
1.2 Part 2: Adjuncts], Section 6.3) only supports input
message serialization as
application/x-www-form-urlencoded. Other examples of
such mechanisms are other message exchange patterns or
bindings.
-
Accept headers. Standard HTTP accept headers (see
section 14 of [IETF RFC 2616])
MAY be used in an HTTP request. When constructing an HTTP
Accept header, the HTTP client MAY take into account
the expectedMediaType information (see [MTXML]) appearing on an output
message description to find out about the type of binary element
content which is expected to be sent by the HTTP server.
-
HTTP Header Construction. If the {http headers}
property as defined in section 4.10
Declaring SOAP Header Blocks exists and is not empty in a
Binding Message Reference or Binding Fault component, element
information item conforming to the element declaration of a
HTTP Header Component's {element} property, in the {http headers}
property, MUST be turned into a HTTP header for the corresponding
message.
Only element information items of type
xs:string or xs:anyURI may be serialized. All
complex data types are ignored. Attributes on data elements are
ignored.
Each such element information item is serialized as
follows:
-
The HTTP header name used is the element information
item local name. The element information item local
name MUST follow the field-name production rules as specified in
section 4.2 of [IETF RFC 2616];
if not, the element information item MUST be ignored. If
an HTTP header corresponding to the element information
item local name is set by a different mechanism other than the
HTTP Binding, such as the HTTP stack or another feature, then an
error MUST be raised.
-
The HTTP header content is serialized from the corresponding
element information item value in UTF-8. If this
serialization is NOT possible, then the element information
item MUST be ignored.
5.4
Specifying the HTTP Version
5.4.1 Description
Every Binding component MUST indicate what version of HTTP is in
use for the operations of the interface that this binding applies
to.
By default, HTTP/1.1 [IETF RFC
2616] is used.
5.4.2 Relationship to WSDL Component
Model
The HTTP binding specification adds the following property to
the WSDL component model (as defined in [WSDL 2.0 Core Language]):
5.4.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
whttp:version="xs:string"? >
</binding>
</description>
The XML representation for specifying the HTTP version is an
optional attribute information item with the following
Infoset properties:
5.4.4 Mapping from XML
Representation to Component Properties
See Table 5-2.
Table 5-2. Mapping from XML Representation to Binding
Component Extension Properties
| Property |
Value |
| {http version} |
The actual value of the
whttp:version attribute information
item. |
5.5 Specifying the Default HTTP
Method
5.5.1 Description
Every Binding Operation component MUST indicate what HTTP method
is in use for the operations of the interface that this binding
applies to. This binding specification allows the user to indicate
a default HTTP method to be used for all Binding Operation
components of this Binding component.
5.5.2 Relationship to WSDL
Component Model
The default HTTP method specification is a syntactic convenience
and does not affect the underlying component model.
5.5.3 XML Representation
<description>
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
whttp:methodDefault="xs:string"? >
</binding>
</description>
The XML representation for specifying the default HTTP method is
an optional attribute information item with the following
Infoset properties:
5.6
Binding Operations
5.6.1 Description
This binding specification provides a binding to HTTP of
Interface Operation components whose
{message exchange pattern} property has the value
'http://www.w3.org/2005/05/wsdl/in-only',
'http://www.w3.org/2005/05/wsdl/robust-in-only' or
'http://www.w3.org/2005/05/wsdl/in-out'. This HTTP binding MAY be
used with other message exchange patterns such as outbound message
exchange patterns, provided that additional semantics are defined,
such as with an extension or with a Feature.
Each of the supported message exchange patterns involves one to
two messages or faults being exchanged. The first is transmitted
using an HTTP request, and the second is transmitted using the
corresponding HTTP response. In cases where only one message is
being sent, the message body of the HTTP response MUST be
empty.
For every Binding operation component corresponding to such
Interface Operation components, this binding specification allows
the user to indicate the HTTP method to use, the input, output and
fault serialization, and the location of the bound operation.
5.6.2 Relationship to WSDL
Component Model
The HTTP binding adds the following property to the Binding
Operation component of the WSDL component model (as defined in
[WSDL 2.0 Core
Language]):
-
{http location}, REQUIRED. A xs:anyURI. This URI is
combined with the base URI specified in the {address}
property of the endpoint component to form the full URI for the
HTTP request to invoke the operation. It MUST contain an absolute
or a relative URI, i.e. it MUST NOT include a fragment identifier
in the URI. Input serializations may define additional processing
rules to be applied to the value of {http location} before
combining it with the {address}
property of the endpoint element to form the HTTP request URI. For
example, the application/x-www-form-urlencoded serialization
defined in section 5.9.1
Serialization as application/x-www-form-urlencoded defines
a syntax to use the {http location} as a template using elements of
the instance data.
If the resulting URI uses the https scheme, then
HTTP over TLS [IETF RFC 2818]
is used to send the HTTP request.
-
{http method} REQUIRED. A xs:string indicating the
value for the HTTP Request Method for this specific operation.
-
{http input serialization} REQUIRED. A xs:string
indicating the value for the serialization of the HTTP Request
message for this specific operation. Its value MUST be the name of
a IANA media type token.
-
{http output serialization} REQUIRED. A xs:string
indicating the value for the serialization of the HTTP Response
message for this specific operation. Its value MUST be the name of
a IANA media type token.
-
{http fault serialization} REQUIRED. A xs:string
indicating the value for the serialization of the HTTP Response
message for this specific operation in case a fault is returned.
Its value MUST be the name of a IANA media type token.
-
{http query parameter separator} REQUIRED. A xs:string
indicating the query parameter separator character. Its default
value is "&".
5.6.3 XML Representation
<description>
<binding whttp:queryParameterSeparatorDefault="xs:string"? >
<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:queryParameterSeparator="xs:string"? >
</operation>
</binding>
</description>
The XML representation for binding an Operation are four
attribute information items with the following Infoset
properties:
-
An OPTIONAL location attribute information
item with the following Infoset properties:
-
An OPTIONAL method attribute information
item with the following Infoset properties:
-
An OPTIONAL inputSerialization attribute
information item with the following Infoset properties:
-
An OPTIONAL outputSerialization attribute
information item with the following Infoset properties:
-
An OPTIONAL faultSerialization attribute
information item with the following Infoset properties:
-
A [local name] of faultSerialization
-
A [namespace name] of "http://www.w3.org/2005/05/wsdl/http"
-
A type of xs:string
-
A default value of "application/xml"
-
An OPTIONAL queryParameterSeparatorDefault
attribute information item with the following Infoset
properties:
-
A [local name] of
queryParameterSeparatorDefault
-
A [namespace name] of "http://www.w3.org/2005/05/wsdl/http"
-
A type of xs:string whose length facet value is 1
-
An OPTIONAL queryParameterSeparator attribute
information item with the following Infoset properties:
-
A [local name] of queryParameterSeparator
-
A [namespace name] of "http://www.w3.org/2005/05/wsdl/http"
-
A type of xs:string whose length facet value is 1
5.6.4 Mapping from XML
Representation to Component Properties
See Table 5-3.
Table 5-3. Mapping from XML Representation to Binding
Operation Component Extension Properties
| Property |
Value |
| {http location} |
The actual value of the
whttp:location attribute information item, if
present. Otherwise empty. |
| {http method} |
The actual value of the
whttp:method attribute information item, if
present. Otherwise, the actual value of the
whttp:methodDefault attribute information
item as defined in 5.5
Specifying the Default HTTP Method. Otherwise, error. |
| {http input serialization} |
The actual value of the
whttp:inputSerialization attribute information
item, if present. Otherwise, the default value as defined in
5.3 Default Binding
Rules, computed based on the value of the {http method}
property. |
| {http output serialization} |
The actual value of the
whttp:outputSerialization attribute information
item, if present. Otherwise, the default value as defined in
5.3 Default Binding
Rules, computed based on the value of the {http method}
property. |
| {http fault serialization} |
The actual value of the
whttp:faultSerialization attribute information
item. |
| {http query parameter separator} |
The actual value of the
whttp:queryParameterSeparator attribute
information item, if present. Otherwise, the actual value of
the whttp:queryParameterSeparatorDefault attribute
information item, if present. Otherwise, "&". |
5.7
Declaring HTTP Headers
5.7.1 Description
HTTP allows the use of headers in messages. This binding allows
users to declare the HTTP headers in use on a per message ond on a
per fault basis.
5.7.2 Relationship to WSDL Component
Model
The HTTP Header binding specification adds the following
property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):
-
{http headers}, OPTIONAL, a set of HTTP Header components as
defined in 5.7.3 HTTP
Header Component, to the Binding Fault and Binding Message
Reference components.
5.7.3 HTTP Header Component
A HTTP Header component describes an abstract piece of header
data (message headers) that is associated with the exchange of
messages between the communicating parties. The presence of a HTTP
Header component in a WSDL description indicates that the service
supports headers and MAY require a Web service consumer/client that
interacts with the service to use the described header. Zero or
more such headers may be used.
The properties of the HTTP Header component are as follows:
5.7.4 XML Representation
<description>
<binding name="xs:NCName" type="http://www.w3.org/2005/05/wsdl/http" >
<fault ref="xs:QName">
<whttp:header element="xs:QName">
<documentation />?
</whttp:header>*
...
</f