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. WSDL
Version 2.0 Bindings describes how to use WSDL in conjunction
with SOAP 1.2
This is a
Three formal objections from Working Group participants have been received against portions of the WSDL 2.0 specification. Feedback is specifically encouraged on these topics:
Compositors (see
Feature and properties (see
Requiring unique GEDs or required feature to
distinguish operations (see
A
This document has been produced as part of the
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
Last Modified: $Date: 2004/08/03 17:34:10 $ CET
The Web Services Description Language WSDL Version 2.0 (WSDL)
SOAP Version 1.2
HTTP/1.1
WSDL 2.0 Primer
The Core Language
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
| Prefix | Namespace | Notes |
|---|---|---|
| wsdl |
|
A normative XML Schema |
| wsoap |
|
A normative XML Schema |
| whttp |
|
A normative XML Schema |
| wsdls | This prefix and namespace name are used to refer to
the simple types defined by |
|
| xs |
|
Defined in the W3C XML Schema
specification |
Namespace names of the general form
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 1.0-based
Note that the WSDL binding specifications in this document are defined in terms of a component model defined by this specification. As such, it is explicitly NOT a conformance requirement to be able to process documents encoded in a particular version of XML.
The SOAP binding described in this section is an extension
for
As allowed in
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
Notice that there are no default binding rules defined for
A subset of the HTTP properties specified in the HTTP binding
defined in section
{http version} as defined in
{http transfer coding} as defined in
{http cookies} as defined in
{http authentication scheme} and {http authentication
realm} as defined in
When the SOAP Message Exchange Pattern is the SOAP Response
MEP, the Binding Operation may use the {http location} property
defined in
The double question marks ("??") after the
attributes in the
A Binding component (defined in
If the value of the
If the value is
If the value is
If the Message Reference component is declared
using a non-XML type system (as considered in the Types
section of
This SOAP binding only allows one single element in SOAP body.
x-www-form-urlencoded is the only supported
serialization format for HTTP GET in the SOAP Response
Message Exchange Pattern.
x-www-form-urlencoded serialization
format (see Every SOAP binding MUST indicate what underlying protocol is in
use, as defined in the SOAP Protocol Binding Framework
section of
The SOAP binding defined by this specification supports
the SOAP HTTP binding defined by the
The SOAP protocol specification adds the following
property to the WSDL component model (as defined in
{soap underlying protocol}, an absolute URI as defined by
The XML representation for specifying the SOAP protocol
is a REQUIRED
A [local name] of
A [namespace name] of
See
| Property | Mapping |
|---|---|
| {soap underlying protocol} | The actual value of the |
Every Binding Operation component of a SOAP binding MUST
indicate the SOAP Message Exchange Pattern (MEP) (see
The default SOAP MEP specification is a syntactic convenience and does not affect the underlying component model.
The XML representation for specifying the default SOAP
MEP is an OPTIONAL
A [local name] of
A [namespace name] of
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
The SOAP Module component adds the following
property to the WSDL component model (as defined in
{soap modules} to the Binding, Binding Operation and Binding Message 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, and 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 level, the Binding Operation component level or the Binding component level, respectively.
The SOAP Module component identifies a SOAP module that is in use. The properties of the SOAP Module component are as follows:
{uri} An absolute URI as defined by
{required} A boolean indicating if the SOAP module is required.
The XML representation for a SOAP Module component is an
A [local name] of
A [namespace name] of
One or more
A REQUIRED
A [local name] of
A [namespace name] which has no value
An OPTIONAL
A [local name] of
A [namespace name] which has no value
Zero or more namespace qualified
Zero or more
An OPTIONAL
Zero or more namespace-qualified
See
| Property | Mapping |
|---|---|
| {uri} | The actual value of the |
| {required} | The actual value of the |
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.
The SOAP Fault binding adds the following
properties to the WSDL component model (as defined in
{soap fault code}, a QName as defined by
{soap fault subcodes}, a list of QNames, to the Binding Fault component. The value of this property identifies one or more subcodes for this SOAP fault.
The XML representation for binding a SOAP Fault are two
wsoap:code REQUIRED
A [local name] of
A [namespace name] of
wsoap:subcodes OPTIONAL
A [local name] of
A [namespace name] of
See
| Property | Mapping |
|---|---|
| {soap fault code} | The actual value of the |
| {soap fault subcodes} | The actual value of the |
For every Interface Operation component contained in an
Interface component, in addition to the default binding
rules described in
The SOAP Operation binding specification adds the
following property to the WSDL component model (as defined
in
{soap mep}, an absolute URI as defined by
{soap action}, an absolute URI as defined by
The XML representation for binding an Operation are two
wsoap:mep OPTIONAL
A [local name] of
A [namespace name] of
wsoap:action OPTIONAL
A [local name] of
A [namespace name] of
See
| Property | Mapping |
|---|---|
| {soap mep} | The actual value of the
|
| {soap action} | The actual value of the
|
The HTTP binding described in this section is an extension for
As allowed in
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
Notice that there are no default binding rules defined for Fault components by this binding. 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 Binding component (defined in
Message Reference component: if the value of the
Interface Fault component: the payload will be the
If the Message Reference component or the Interface Fault
component is declared using a non-XML type system (as
considered in the Types section of
Section
| 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
application/x-www-form-urlencoded serialization
format places constraints on the stype of the interface
operation bound (see
The default vales for the {http input serialization} and
{http output serialization} properties for any other {http
method} is application/xml.
Mechanisms that are outside the scope of this specification
MAY modify the serialization format of the application/x-www-form-urlencoded and the
Accept header, the requester agent MAY take
into account the
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
The HTTP binding specification adds the following
property to the WSDL component model (as defined in
{http version}, a string value to the Binding component.
The XML representation for specifying the HTTP version
is an optional
A [local name] of
A [namespace name] of
A type of
A default value of
See
| Property | Mapping |
|---|---|
| {http version} | The actual value of the |
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.
The default HTTP method specification is a syntactic convenience and does not affect the underlying component model.
The XML representation for specifying the default HTTP method
is an optional
A [local name] of
A [namespace name] of
A type of
No default value
This binding specification provides a binding to HTTP of
Interface Operation components whose
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.
The HTTP Operation component adds the following property
to the Binding Operation component of the WSDL component model (as defined in
{http location}, an absolute or relative URI as
defined by
If the resulting URI uses the https
scheme, then HTTP over TLS
{http method}, a string value indicating, if present, the
value for the HTTP Request Method for this specific operation. Otherwise,
the default HTTP method as defined in
{http input serialization}, a string value indicating, if present, 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. If not present, the default input serialization associated
with the {http method} property applies, as specified in
{http output serialization}, a string value indicating, if present, 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. If not present, the default output serialization associated with the {http method} property applies, as specified in
{http fault serialization}, a string value 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.
The XML representation for binding an Operation are four
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
A default value of
See
| Property | Mapping |
|---|---|
| {http location} | The actual value of the |
| {http method} | The actual value of the |
| {http input serialization} | The actual value of the |
| {http output serialization} | The actual value of the |
| {http fault serialization} | The actual value of the |
For every Interface Fault component contained in an Interface component, an HTTP error code MAY be defined. It represents the error code that will be used by the service in case the fault needs to be returned.
The HTTP Fault binding adds the following
property to the WSDL component model (as defined in
{http error status code}, an integer representing a
error Status-Code as defined by
The XML representation for binding a SOAP Fault are two
whttp:code OPTIONAL
A [local name] of
A [namespace name] of
A type of
See
| Property | Mapping |
|---|---|
| {http error status code} | The actual value of the |
The following serialization formats can be used to encode the
Other serialization formats may be used. Those MAY place restrictions on the style of the interface operation bound.
This serialization format is designed to allow a Web Service
to produce a URI based on the
Elements from the instance data can be inserted into the path of the request URI, or a query parameter, as shown in the example below:
The following instance data of an input message
with the following
and the following
will serialize the message in the URI as follow:
Element name and element content MUST be URI escaped when
inserted into the request, as defined in "
The
When constructing the request URI, each pair of curly braces (and enclosed element name) is replaced by the corresponding content of the element.
A double curly brace (i.e. "{{" or "}}") MAY be used to include a single, literal curly brace in the request URI.
An element MUST NOT be cited more than once within
the
An element name MAY be followed by a slash (i.e. "/")
inside curly braces
(e.g. location="temperature/{town/}") to indicate that
no other element must be serialized in the request URI
(see
Strings enclosed within single curly braces MUST be
element names from the
If not all elements from the
If an element name appears in the
All elements of the
If the
Uncited elements with single values (non-list) are serialized as a single name-value parameter pair. The name of the parameter is the name of the uncited element, and the value of the parameter is the value of the uncited element.
Uncited elements with list values are serialized as one name-value parameter pair per list value. The name of each parameter is the name of the uncited element, and the value of each parameter is the corresponding value in the list.
In addition to the serialization in the request URI
of the elements cited in the
The following instance data of an input message
with the following
and the following
will serialize the message in the URI as follow:
and in the message as follow:
The
The Content-Type HTTP header MUST have the value
application/xml, or a media type compatible with
application/xml. Other HTTP headers, such as
Content-Encoding or
Transfer-Encoding, MAY be used.
This format is for legacy compatibility to permit the use of
XForms clients with
Each element in the sequence is serialized into a part as follow:
The Content-Disposition header MUST have the
value form-data, and its name
parameter is the local name of the element.
The Content-Type header MUST have the value:
application/xml (or a media type
compatible with application/xml) if the
element has a complex type;
application/octet-stream if the element
is of type
xs:base64Binary,
xs:hexBinary, or a derived type;
text/plain if the element has a simple
type; The charset MUST be set appropriately. UTF-8 or
UTF-16 MUST be at least supported.
If the type is xs:base64Binary,
xs:hexBinary, xs:anySimpleType
or a derived type, the content of the part is the content
of the element. If the type is a complex type, the element
is serialized following the rules defined in the
The following instance data of an input message:
with the following
will serialize the message as follow:
This section defines operation styles in use in parallel to the HTTP 1.1 binding.
The URI style is selected by assigning the Interface
Operation component's
The URI style may only be used for Interface Operation
components whose
Use of this value indicates that XML Schema
The content model of input message elements are 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
0 or 1.
The localPart of input element's QName MUST be the same as the Interface operation component's name.
The complex types that defines the body of an input element or its children elements MUST NOT contain any attributes.
The input sequence MUST NOT contain multiple children element declared with the same local name.
If the children elements of the input 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.
The Multipart style is selected by assigning the Interface
Operation component's
The Multipart style may only be used for Interface Operation
components whose
Use of this value indicates that XML Schema
The content model of input message elements are 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
1.
The localPart of input element's QName MUST be the same as the Interface operation component's name.
The complex types that defines the body of an input element or its children elements MUST NOT contain any attributes.
The input sequence MUST NOT contain multiple children element declared with the same local name.
Every Binding Message Reference component MAY indicate which
transfer codings, as defined in section 3.6 of
The HTTP binding provides a mechanism for indicating a default value at the Binding component and Binding Operation levels.
If no value is specified, no claim is being made.
The HTTP binding specification adds the following
property to the WSDL component model (as defined in
{http transfer coding}, a string value to the Binding Message Reference component.
The XML representation for specifying the default
transfer coding is an OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
The XML representation for specifying the
transfer coding is an OPTIONAL
A [local name] of
A [namespace name] of
A type of
No default value
See
| Property | Mapping |
|---|---|
| {http transfer coding} | The actual value of the
|
Every Binding component MAY indicate whether HTTP cookies
(as defined by
The HTTP binding specification adds the following
property to the WSDL component model (as defined in
{http cookies}, a boolean value to the Binding component.
The XML representation for specifying the use of HTTP cookies
is an OPTIONAL
A [local name] of
A [namespace name] of
A type of
A default value of
See
| Property | Mapping |
|---|---|
| {http cookies} | The actual value of the |
Every Endpoint component MAY indicate the use of an HTTP
access authentication mechanism (as defined by
This binding specification allows the authentication scheme and realm to be specified.
The HTTP binding specification adds the following
property to the WSDL component model (as defined in
{http authentication scheme}, a string value to the Endpoint
component, corresponding to the HTTP authentication
scheme used. The valid values are "basic" for the "basic"
authentication scheme defined in
{http authentication realm}, a string value to the
Endpoint. It corresponds to the realm authentication
parameter defined in
The XML representation for specifying the use of HTTP
access authentication
is two OPTIONAL
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
A default value of
An OPTIONAL
A [local name] of
A [namespace name] of
A type of
A default value of
See
| Property | Mapping |
|---|---|
| {http authentication scheme} | The actual value of the |
| {http authentication realm} | The actual value of the |
This document is the work of the
Members of the Working Group are (at the time of writing, and by alphabetical order): David Booth (W3C), Allen Brookes (Rogue Wave Softwave), Helen Chen (Agfa-Gevaert N. V.), Roberto Chinnici (Sun Microsystems), Ugo Corda (SeeBeyond), Glen Daniels (Sonic Software), Paul Downey (British Telecommunications), Youenn Fablet (Canon), Martin Gudgin (Microsoft Corporation), Hugo Haas (W3C), Hao He (The Thomson Corporation), Tom Jordahl (Macromedia), Jacek Kopecky (Digital Enterprise Research Institute (DERI)), Amelia Lewis (TIBCO Software, Inc.), Kevin Canyang Liu (SAP), Jonathan Marsh (Microsoft Corporation), Peter Madziak (Agfa-Gevaert N. V.), Josephine Micallef (SAIC - Telcordia Technologies), Jeff Mischkinsky (Oracle Corporation), Dale Moberg (Cyclone Commerce), Jean-Jacques Moreau (Canon), Mark Nottingham (BEA Systems, Inc.), David Orchard (BEA Systems, Inc.), Bijan Parsia (University of Maryland), Arthur Ryman (IBM), Adi Sakala (IONA Technologies), Jeffrey Schlimmer (Microsoft Corporation), Igor Sedukhin (Computer Associates), Jerry Thrasher (Lexmark), William Vambenepe (Hewlett-Packard Company), Asir Vedamuthu (webMethods, Inc.), Sanjiva Weerawarana (IBM), Ümit Yalçınalp (Oracle Corporation), Prasad Yendluri (webMethods, Inc.).
Previous members were: Lily Liu (webMethods, Inc.), Don Wright (Lexmark), Joyce Yang (Oracle Corporation), Daniel Schutzer (Citigroup), Dave Solo (Citigroup), Stefano Pogliani (Sun Microsystems), William Stumbo (Xerox), Stephen White (SeeBeyond), Barbara Zengler (DaimlerChrysler Research and Technology), Tim Finin (University of Maryland), Laurent De Teneuille (L'Echangeur), Johan Pauhlsson (L'Echangeur), Mark Jones (AT&T), Steve Lind (AT&T), Sandra Swearingen (U.S. Department of Defense, U.S. Air Force), Philippe Le Hégaret (W3C), Jim Hendler (University of Maryland), Dietmar Gaertner (Software AG), Michael Champion (Software AG), Don Mullen (TIBCO Software, Inc.), Steve Graham (Global Grid Forum), Steve Tuecke (Global Grid Forum), Michael Mahan (Nokia), Bryan Thompson (Hicks & Associates), Ingo Melzer (DaimlerChrysler Research and Technology), Sandeep Kumar (Cisco Systems), Alan Davies (SeeBeyond), Jacek Kopecky (Systinet), Mike Ballantyne (Electronic Data Systems), Mike Davoren (W. W. Grainger), Dan Kulp (IONA Technologies), Mike McHugh (W. W. Grainger), Michael Mealling (Verisign), Waqar Sadiq (Electronic Data Systems), Yaron Goland (BEA Systems, Inc.).
The people who have contributed to
| Date | Author | Description |
|---|---|---|
| 20040730 | HH | Removed |
| 20040730 | HH | Removed AD Feature HTTP serialization. |
| 20040729 |