Copyright © 2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
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 1.2 Bindings describes how to use WSDL in conjunction with SOAP 1.2 [SOAP 1.2: Messaging Framework], HTTP/1.1 GET/POST [IETF RFC 2616], and MIME [IETF RFC 2045]. This specification depends on WSDL Version 1.2 [WSDL 1.2].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is the first W3C Working Draft of the WSDL Version 1.2 specification for review by W3C members and other interested parties.
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 is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the Web Services Description Working Group.
For a detailed list of changes since the last publication of this document, refer to appendix E. Part 2 Change Log. A list of open issues against this document can be found at http://www.w3.org/2002/ws/desc/2/06/issues.html.
Comments on this document are invited and are to be sent to public-ws-desc-comments@w3.org (public archive). It is inappropriate to send discussion emails to this address. Discussion of this document takes place on the public www-ws-desc@w3.org mailing list (public archive).
Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
1. Introduction
2. SOAP Binding
3. HTTP GET and POST Binding
4. MIME Binding
5. References
A. Notes on URIs (Non-Normative)
B. Wire format for WSDL examples
(Non-Normative)
C. Schemas (Non-Normative)
D. Acknowledgements (Non-Normative)
E. Part 2 Change Log (Non-Normative)
1. Introduction
1.1 Notational
Conventions
2. SOAP Binding
2.1 SOAP
Examples
2.2 How the SOAP Binding
Extends WSDL
2.3 soap:binding
2.4 soap:operation
2.5 soap:body
2.6 soap:fault
2.7 soap:header and
soap:headerfault
2.8 soap:address
3. HTTP GET and POST Binding
3.1 HTTP GET/POST
Examples
3.2 How the HTTP
GET/POST Binding Extends WSDL
3.3 http:address
3.4 http:binding
3.5 http:operation
3.6 http:urlEncoded
3.7 http:urlReplacement
4. MIME Binding
4.1 MIME Binding
example
4.2 How the
MIME Binding extends WSDL
4.3 mime:content
4.4 mime:multipartRelated
4.5 soap:body
4.6 mime:mimeXml
5. References
5.1 Normative
References
5.2 Informative
References
A. Notes on URIs
(Non-Normative)
A.1 XML namespaces and
schema locations
A.2 Relative
URIs
A.3 Generating
URIs
B. Wire format for WSDL examples
(Non-Normative)
B.1 Example 1
C. Schemas (Non-Normative)
C.1 SOAP Binding
Schema
C.2 HTTP Binding
Schema
C.3 MIME Binding
Schema
D. Acknowledgements (Non-Normative)
E. Part 2 Change Log (Non-Normative)
E.1 SOAP Specification
Changes
E.2 XML Schema
Changes
Editorial note: JJM | 20020628 |
This document is out of synch with Part 1. A number of changes have been made recently to Part 1 which are not yet reflected in this document. The WG is aware of this problem and expects to synchronise Part 1 and Part 2 at a later date. More generally, the sections in this document have hardly changed from the corresponding sections in WSDL 1.1. This may not be the case in a future revision. In particular, the WG anticipates that the SOAP section may change significantly as a result of supporting SOAP 1.2. |
The Web Services Description Language WSDL Version 1.2 (WSDL) [WSDL 1.2] defines an XML grammar [XML 1.0] 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. WSDL 1.2 Bindings (this document) defines binding extensions for the following protocols and message formats:
SOAP Version 1.2 [SOAP 1.2: Messaging Framework] (see 2. SOAP Binding).
HTTP/1.1 GET/POST [IETF RFC 2616] (see 3. HTTP GET and POST Binding).
MIME [IETF RFC 2045] (see 4. MIME Binding).
WSDL 1.2 Primer [WSDL 1.2 Primer] is a non-normative document intended to provide an easily understandable tutorial on the features of the WSDL Version 1.2 specifications.
WSDL 1.2 [WSDL 1.2] of the WSDL specification describes the core elements of the WSDL 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 [IETF RFC 2119].
This specification uses a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).
Prefix | Namespace | Notes |
---|---|---|
wsdl | "http://www.w3.org/2002/07/wsdl" | Defined by WSDL 1.2 [WSDL 1.2]. |
soap | "http://www.w3.org/2002/07/wsdl/soap12" | A normative XML Schema [XML Schema Structures], [XML Schema Datatypes] document for the "http://www.w3.org/2002/07/wsdl/soap12" namespace can be found at http://www.w3.org/2002/07/wsdl/soap12. |
http | "http://www.w3.org/2002/07/wsdl/http" | A normative XML Schema [XML Schema Structures], [XML Schema Datatypes] document for the "http://www.w3.org/2002/07/wsdl/http" namespace can be found at http://www.w3.org/2002/07/wsdl/http. |
mime | "http://www.w3.org/2002/07/wsdl/mime" | A normative XML Schema [XML Schema Structures], [XML Schema Datatypes] document for the "http://www.w3.org/2002/07/wsdl/mime" namespace can be found at http://www.w3.org/2002/07/wsdl/mime. |
xs | "http://www.w3.org/2001/XMLSchema" | Defined in the W3C XML Schema specification [XML Schema Structures], [XML Schema Datatypes]. |
xsi | "http://www.w3.org/2001/XMLSchema-instance" | Defined in the W3C XML Schema specification [XML Schema Structures], [XML Schema Datatypes]. |
Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs [IETF RFC 2396].
This specification uses the Extended Backus-Naur Form (EBNF) as described in XML 1.0 [XML 1.0].
With the exception of examples and sections explicitly marked as "Non-Normative", all parts of this specification are normative.
Editorial note: JJM | 20020222 |
This section currently describes the WSDL binding to SOAP 1.1, not to W3C SOAP Version 1.2. |
WSDL includes a binding for SOAP 1.2 endpoints, which supports the specification of the following protocol specific information:
An indication that a binding is bound to the SOAP 1.2 protocol.
A way of specifying an address for a SOAP endpoint.
The URI for the SOAPAction HTTP header for the HTTP binding of SOAP.
A list of definitions for Headers that are transmitted as part of the SOAP Envelope
This binding grammar is not an exhaustive specification since the set of SOAP bindings is evolving. Nothing precludes additional SOAP bindings to be derived from portions of this grammar. For example:
SOAP bindings that do not employ a URI addressing scheme may
substitute another addressing scheme by replacing the
soap:address
element defined in 2.8 soap:address.
SOAP bindings that do not require a SOAPAction
omit
the soapAction
attribute defined in 2.4 soap:operation.
In the following example, a SubscribeToQuotes SOAP 1.1 one- way message is sent to a StockQuote service via a SMTP binding. The request takes a ticker symbol of type string, and includes a header defining the subscription URI.
Header
<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://www.w3.org/2002/07/wsdl/soap11" xmlns="http://www.w3.org/2002/07/wsdl"> <message name="SubscribeToQuotes"> <part name="body" element="xsd1:SubscribeToQuotes"/> <part name="subscribeheader" element="xsd1:SubscriptionHeader"/> </message> <portType name="StockQuotePortType"> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"/> </operation> </portType> <binding name="StockQuoteSoap" type="tns:StockQuotePortType"> <soap:binding style="document" transport="http://example.com/smtp"/> <operation name="SubscribeToQuotes"> <input message="tns:SubscribeToQuotes"> <soap:body parts="body" use="literal"/> <soap:header message="tns:SubscribeToQuotes" part="subscribeheader" use="literal"/> </input> </operation> </binding> <service name="StockQuoteService"> <port name="StockQuotePort" binding="tns:StockQuoteSoap"> <soap:address location="mailto:subscribe@example.com"/> </port> </service> <types> <schema targetNamespace="http://example.com/stockquote.xsd" xmlns="http://www.w3.org/2000/10/XMLSchema"> <element name="SubscribeToQuotes"> <complexType> <all> <element name="tickerSymbol" type="string"/> </all> </complexType> </element> <element name="SubscriptionHeader" type="uriReference"/> </schema> </types> </definitions>
The following example describes that a GetTradePrice SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a ticker symbol of type string, a time of type timeInstant, and returns the price as a float in the SOAP response.
<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:xsd1="http://example.com/stockquote.xsd" xmlns:soap="http://www.w3.org/2002/07/wsdl/soap11" xmlns="http://www.w3.org/2002/07/wsdl"> <message name="GetTradePriceInput"> <part name="tickerSymbol" element="xsd:string"/> <part name="time" element="xsd:timeInstant"/> </message> <message name="GetTradePriceOutput"> <part name="result" type="xsd:float"/> </message> <portType name="StockQuotePortType"> <operation name="GetTradePrice"> <input message="tns:GetTradePriceInput"/> <output message="tns:GetTradePriceOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetTradePrice"> <soap:operation soapAction="http://example.com/GetTradePrice"/> <input> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation>> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>
The following example describes that a GetTradePrices SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a stock quote symbol string, an application defined TimePeriod structure containing a start and end time and returns an array of stock prices recorded by the service within that period of time, as well as the frequency at which they were recorded as the SOAP response. The RPC signature that corresponds to this service has in parameters tickerSymbol and timePeriod followed by the output parameter frequency, and returns an array of floats.
<?xml version="1.0"?> <definitions name="StockQuote" targetNamespace="http://example.com/stockquote.wsdl" xmlns:tns="http://example.com/stockquote.wsdl" xmlns:xsd="http://www.w3.org/2000/10/XMLSchema" xmlns:xsd1="http://example.com/stockquote/schema" xmlns:soap="http://www.w3.org/2002/07/wsdl/soap11" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns="http://www.w3.org/2002/07/wsdl"> <types> <schema targetNamespace="http://example.com/stockquote/schema" xmlns="http://www.w3.org/2000/10/XMLSchema"> <complexType name="TimePeriod"> <all> <element name="startTime" type="xsd:timeInstant"/> <element name="endTime" type="xsd:timeInstant"/> </all> </complexType> <complexType name="ArrayOfFloat"> <complexContent> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:float[]"/> </restriction> </complexContent> </complexType> </schema> </types> <message name="GetTradePricesInput"> <part name="tickerSymbol" element="xsd:string"/> <part name="timePeriod" element="xsd1:TimePeriod"/> </message> <message name="GetTradePricesOutput"> <part name="result" type="xsd1:ArrayOfFloat"/> <part name="frequency" type="xsd:float"/> </message> <portType name="StockQuotePortType"> <operation name="GetLastTradePrice" parameterOrder="tickerSymbol timePeriod frequency"> <input message="tns:GetTradePricesInput"/> <output message="tns:GetTradePricesOutput"/> </operation> </portType> <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="GetTradePrices"> <soap:operation soapAction="http://example.com/GetTradePrices"/> <input> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </input> <output> <soap:body use="encoded" namespace="http://example.com/stockquote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </output> </operation>> </binding> <service name="StockQuoteService"> <documentation>My first service</documentation> <port name="StockQuotePort" binding="tns:StockQuoteBinding"> <soap:address location="http://example.com/stockquote"/> </port> </service> </definitions>
The SOAP Binding extends WSDL with the following extension elements:
<definitions .... > <binding .... > <soap:binding style="rpc|document" transport="uri"> <operation .... > <soap:operation soapAction="uri"? style="rpc|document"?>? <input> <soap:body parts="nmtokens"? use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </input> <output> <soap:body parts="nmtokens"? use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </output> <fault>* <soap:fault name="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> </fault> </operation> </binding> <port .... > <soap:address location="uri"/> </port> </definitions>
Each extension element of the SOAP binding is covered in subsequent sections.
The purpose of the SOAP binding element is to signify that the
binding is bound to the SOAP protocol format: Envelope,
Header
and Body
. This element makes no
claims as to the encoding or format of the message (e.g. that it
necessarily follows section 5 of the SOAP 1.1 specification
[SOAP 1.1]).
The soap:binding
element MUST be present when using
the SOAP binding.
<definitions .... > <binding .... > <soap:binding transport="uri"? style="rpc|document"?> </binding> </definitions>
The value of the style
attribute is the default for
the style attribute for each contained operation. If the style
attribute is omitted, it is assumed to be "document". See section
2.4 soap:operation for more
information on the semantics of style
.
The value of the required transport
attribute
indicates which transport of SOAP this binding corresponds to. The
URI value "http://schemas.xmlsoap.org/soap/http " corresponds to
the HTTP binding in the SOAP specification. Other URIs may be used
here to indicate other transports (such as SMTP, FTP, etc.).
The soap:operation
element provides information for
the operation as a whole.
<definitions .... > <binding .... > <operation .... > <soap:operation soapAction="uri"? style="rpc|document"?>? </operation> </binding> </definitions>
The style
attribute indicates whether the operation
is RPC-oriented (messages containing parameters and return values)
or document-oriented (message containing document(s)). This
information may be used to select an appropriate programming model.
The value of this attribute also affects the way in which the
Fault
of the SOAP message is constructed, as explained
in section 2.5 soap:body. If the
attribute is not specified, it defaults to the value specified in
the soap:binding
element. If the
soap:binding
element does not specify a style, it is
assumed to be " "document"".
The soapAction
attribute specifies the value of the
SOAPAction
header for this operation. This URI value
should be used directly as the value for the
SOAPAction
header; no attempt should be made to make a
relative URI value absolute when making the request. For the HTTP
protocol binding of SOAP, this value is required (it has no default
value). For other SOAP protocol bindings, it MUST NOT be specified,
and the soap:operation
element MAY be omitted.
The soap:body
element specifies how the message
parts appear inside the SOAP Fault
element.
The parts of a message may either be abstract type definitions, or concrete schema definitions. If abstract definitions, the types are serialized according to some set of rules defined by an encoding style. Each encoding style is identified using a list of URIs, as in the SOAP specification. Since some encoding styles such as the SOAP Encoding ( http://schemas.xmlsoap.org/soap/encoding/) allow variation in the message format for a given set of abstract types, it is up to the reader of the message to understand all the format variations: "reader makes right". To avoid having to support all variations, a message may be defined concretely and then indicate it’s original encoding style (if any) as a hint. In this case, the writer of the message must conform exactly to the specified schema: "writer makes right".
The soap:body
binding element provides information
on how to assemble the different message parts inside the
Fault
element of the SOAP message. The
soap:body
element is used in both RPC-oriented and
document-oriented messages, but the style of the enclosing
operation has important effects on how the Fault
section is structured:
If the operation style is rpc each part is a parameter or a return value and appears inside a wrapper element within the body (following Section 7.1 of the SOAP specification). The wrapper element is named identically to the operation name and its namespace is the value of the namespace attribute. Each message part (parameter) appears under the wrapper, represented by an accessor named identically to the corresponding parameter of the call. Parts are arranged in the same order as the parameters of the call.
If the operation style is document there are no additional
wrappers, and the message parts appear directly under the SOAP
Fault
element.
The same mechanisms are used to define the content of the
Fault
and parameter accessor elements.
<definitions .... > <binding .... > <operation .... > <input> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> </input> <output> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> </output> </operation> </binding> </definitions>
The optional parts
attribute of type
nmtokens
indicates which parts appear somewhere within
the SOAP Fault
portion of the message (other parts of
a message may appear in other portions of the message such as when
SOAP is used in conjunction with the multipart/related MIME
binding). If the parts attribute is omitted, then all parts defined
by the message are assumed to be included in the SOAP
Body
portion.
The required use
attribute indicates whether the
message parts are encoded using some encoding rules, or whether the
parts define the concrete schema of the message.
If use is encoded
, then each message part
references an abstract type using the type
attribute.
These abstract types are used to produce a concrete message by
applying an encoding specified by the encodingStyle
attribute. The part names
, types
and
value of the namespace
attribute are all inputs to the
encoding, although the namespace attribute only applies to content
not explicitly defined by the abstract types. If the referenced
encoding style allows variations in it’s format (such as the
SOAP encoding does), then all variations MUST be supported ("reader
makes right").
If use is literal
, then each part references a
concrete schema definition using either the element
or
type
attribute. In the first case, the element
referenced by the part will appear directly under the
Body
element (for document style bindings) or under an
accessor element named after the message part (in rpc style). In
the second, the type referenced by the part becomes the schema type
of the enclosing element (Body
for document style or
part accessor element for rpc style). The value of the
encodingStyle
attribute MAY be used when the use is
literal to indicate that the concrete format was derived using a
particular encoding (such as the SOAP encoding), but that only the
specified variation is supported ("writer makes right").
The value of the encodingStyle
attribute is a list
of URIs, each separated by a single space. The URI's represent
encodings used within the message, in order from most restrictive
to least restrictive (exactly like the encodingStyle
attribute defined in the SOAP specification).
The soap:fault
element specifies the contents of
the SOAP Fault Details
element. It is patterned after
the soap:body
element (see section 2.5 soap:body).
<definitions .... > <binding .... > <operation .... > <fault>* <soap:fault name="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?> </fault> </operation> </binding> </definitions>
The name
attribute relates the
soap:fault
to the wsdl:fault
defined for
the operation.
The fault message MUST have a single part. The use
, encodingStyle
and namespace
attributes
are all used in the same way as with soap:body
(see
section 2.5 soap:body), only
"style="document"" is assumed since faults do not contain
parameters.
The soap:header
and soap:headerfault
elements allows header to be defined that are transmitted inside
the Header
element of the SOAP Envelope. It is
patterned after the soap:body
element (see section 2.5 soap:body).
It is not necessary to exhaustively list all headers that appear
in the SOAP Envelope using soap:header
. For example,
extensions (see
Language Extensibility and Binding, [WSDL 1.2], section 4) to WSDL may imply
specific headers should be added to the actual payload and it is
not required to list those headers here.
<definitions .... > <binding .... > <operation .... > <input> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </input> <output> <soap:header message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?>* <soap:headerfault message="qname" part="nmtoken" use="literal|encoded" encodingStyle="uri-list"? namespace="uri"?/>* <soap:header> </output> </operation> </binding> </definitions>
The use
, encodingStyle
and
namespace
attributes are all used in the same way as
with soap:body
(see section 2.5 soap:body), only "style="document"" is
assumed since headers do not contain parameters.
Together, the message
attribute (of type
QName
) and the part
attribute (of type
nmtoken
) reference the message part that defines the
header type. The schema referenced by the part MAY include
definitions for the soap:actor
and
soap:mustUnderstand
attributes if " use="literal"",
but MUST NOT if " use="encoded"". The referenced message need not
be the same as the message that defines the SOAP Body
.
The optional headerfault
elements which appear
inside soap:header
and have the same syntax as
soap:header
allows specification of the header type(s)
that are used to transmit error information pertaining to the
header defined by the soap:header
. The SOAP
specification states that errors pertaining to headers must be
returned in headers, and this mechanism allows specification of the
format of such headers.
The SOAP address binding is used to give a port an address (a
URI). A port using the SOAP binding MUST specify exactly one
address
. The URI scheme specified for the
address
must correspond to the transport specified by
the soap:binding
.
<definitions .... > <port .... > <binding .... > <soap:address location="uri"/> </binding> </port> </definitions>
WSDL includes a binding for HTTP 1.1's GET and POST [IETF RFC 2616] verbs in order to describe the interaction between a Web Browser and a web site. This allows applications other than Web Browsers to interact with the site. The following protocol specific information may be specified:
An indication that a binding uses HTTP GET or POST
An address for the port
A relative address for each operation (relative to the base address defined by the port)
The following example shows three ports that are bound differently for a given port type.
If the values being passed are "part1=1", "part2=2", "part3=3", the request format would be as follows for each port:
port1: GET, URL="http://example.com/o1/A1B2/3" port2: GET, URL="http://example.com/o1?p1=1&p2=2&p3=3 port3: POST, URL="http://example.com/o1", PAYLOAD="p1=1&p2=2&p3=3"
For each port, the response is either a GIF or a JPEG image.
<definitions .... > <message name="m1"> <part name="part1" type="xsd:string"/> <part name="part2" type="xsd:int"/> <part name="part3" type="xsd:string"/> </message> <message name="m2"> <part name="image" type="xsd:binary"/> </message> <portType name="pt1"> <operation name="o1"> <input message="tns:m1"/> <output message="tns:m2"/> </operation> </portType> <service name="service1"> <port name="port1" binding="tns:b1"> <http:address location="http://example.com/"/> </port> <port name="port2" binding="tns:b2"> <http:address location="http://example.com/"/> </port> <port name="port3" binding="tns:b3"> <http:address location="http://example.com/"/> </port> </service> <binding name="b1" type="pt1"> <http:binding verb="GET"/> <operation name="o1"> <http:operation location="o1/A(part1)B(part2)/(part3)"/> <input> <http:urlReplacement/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> <binding name="b2" type="pt1"> <http:binding verb="GET"/> <operation name="o1"> <http:operation location="o1"/> <input> <http:urlEncoded/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> <binding name="b3" type="pt1"> <http:binding verb="POST"/> <operation name="o1"> <http:operation location="o1"/> <input> <mime:content type="application/x-www-form-urlencoded"/> </input> <output> <mime:content type="image/gif"/> <mime:content type="image/jpeg"/> </output> </operation> </binding> </definitions>
The HTTP GET/POST Binding extends WSDL with the following extension elements:
<definitions .... > <binding .... > <http:binding verb="nmtoken"/> <operation .... > <http:operation location="uri"/> <input .... > <-- mime elements --> </input> <output .... > <-- mime elements --> </output> </operation> </binding> <port .... > <http:address location="uri"/> </port> </definitions>
These elements are covered in the subsequent sections.
The location
attribute specifies the base URI for
the port. The value of the attribute is combined with the values of
the location
attribute of the
http:operation
binding element. See section 3.5 http:operation for more
details.
The http:binding
element indicates that this
binding uses the HTTP protocol.
<definitions .... > <binding .... > <http:binding verb="nmtoken"/> </binding> </definitions>
The value of the required verb
attribute indicates
the HTTP verb. Common values are GET or POST, but others may be
used. Note that HTTP verbs are case sensitive.
The location
attribute specifies a relative URI for
the operation. This URI is combined with the URI specified in the
http:address
element to form the full URI for the HTTP
request. The URI value MUST be a relative URI.
<definitions .... > <binding .... > <operation .... > <http:operation location="uri"/> </operation> </binding> </definitions>
The urlEncoded
element indicates that all the
message parts are encoded into the HTTP request URI using the
standard URI- encoding rules
("name1=value&name2=value…"). The names of the
parameters correspond to the names of the message parts. Each value
contributed by the part is encoded using a "name=value" pair. This
may be used with GET to specify URL encoding, or with POST to
specify a FORM-POST. For GET, the "?" character is automatically
appended as necessary.
<http:urlEncoded/>
For more information on the rules for URI-encoding parameters, see Form submission ([HTML 4.01], section 17.13), Ampersands in URI ([HTML 4.01], section B.2.2), and Form content types ([HTML 4.01], section 17.13.4).
The http:urlReplacement
element indicates that all
the message parts are encoded into the HTTP request URI using a
replacement algorithm:
The relative URI value of http:operation
is
searched for a set of search patterns.
The search occurs before the value of the
http:operation
is combined with the value of the
location attribute from http:address
.
There is one search pattern for each message part. The search pattern string is the name of the message part surrounded with parenthesis "(" and ")".
For each match, the value of the corresponding message part is substituted for the match at the location of the match.
Matches are performed before any values are replaced (replaced values do not trigger additional matches).
Message parts MUST NOT have repeating values.
<http:urlReplacement/>
WSDL includes a way to bind abstract types to concrete messages in some MIME format. Bindings for the following MIME types are defined:
"multipart/related", defined in [IETF RFC 2387].
"text/xml", defined in [IETF RFC 3023].
"application/x-www-form-urlencoded", defined in Form content types ([HTML 4.01], section 17.13.4).
Others (by specifying the MIME type string)
The set of defined MIME types is both large and evolving, so it
is not a goal for WSDL to exhaustively define XML grammar for each
MIME type. Nothing precludes additional grammar to be added to
define additional MIME types as necessary. If a MIME type string is
sufficient to describe the content, the mime
element
defined below can be used.
Editorial note: JJM | 20020301 |
The following examples are SOAP 1.1 examples, not SOAP 1.2 examples. |
This example describes that a GetCompanyInfo SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding [SOAP 1.1]. The request takes a ticker symbol of type string. The response contains multiple parts encoded in the MIME format multipart/related: a SOAP Envelope containing the current stock price as a float, zero or more marketing literature documents in HTML format, and an optional company logo in either GIF or JPEG format.
<definitions .... > <types> <schema .... > <element name="GetCompanyInfo"> <complexType> <all> <element name="tickerSymbol " type="string"/> </all> </complexType> </element> <element name="GetCompanyInfoResult"> <complexType> <all> <element name="result" type="float"/> </all> </complexType> </element> <complexType name="ArrayOfBinary"> <complexContent> <restriction base="soapenc:Array"> <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/> </restriction> <complexContent> </complexType> </schema> </types> <message name="m1"> <part name="body" element="tns:GetCompanyInfo"/> </message> <message name="m2"> <part name="body" element="tns:GetCompanyInfoResult"/> <part name="docs" type="xsd:string"/> <part name="logo" type="tns:ArrayOfBinary"/> </message> <portType name="pt1"> <operation name="GetCompanyInfo"> <input message="m1"/> <output message="m2"/> </operation> </portType> <binding name="b1" type="tns:pt1"> <operation name="GetCompanyInfo"> <soap:operation soapAction="http://example.com/GetCompanyInfo"/> <input> <soap:body use="literal"/> </input> <output> <mime:multipartRelated> <mime:part> <soap:body parts="body" use="literal"/> </mime:part> <mime:part> <mime:content part="docs" type="text/html"/> </mime:part> <mime:part> <mime:content part="logo" type="image/gif"/> <mime:content part="logo" type="image/jpeg"/> </mime:part> </mime:multipartRelated> </output> </operation> </binding> <service name="CompanyInfoService"> <port name="CompanyInfoPort"binding="tns:b1"> <soap:address location="http://example.com/companyinfo"/> </port> </service> </definitions>
The MIME Binding extends WSDL with the following extension elements:
<mime:content part="nmtoken"? type="string"?/> <mime:multipartRelated> <mime:part> * <-- mime element --> </mime:part> </mime:multipartRelated> <mime:mimeXml part="nmtoken"?/>
They are used at the following locations in WSDL:
<definitions .... > <binding .... > <operation .... > <input .... > <-- mime elements --> </input> <output .... > <-- mime elements --> </output> </operation> </binding> </definitions>
MIME elements appear under input and output to specify the MIME format. If multiple appear, they are considered to be alternatives.
To avoid having to define a new element for every MIME format,
the mime:content
element may be used if there is no
additional information to convey about the format other than its
MIME type string.
<mime:content part="nmtoken"? type="string"?/>
The part
attribute is used to specify the name of
the message part. If the message has a single part, then the
part
attribute is optional. The type
attribute contains the MIME type string. A type
value
has two portions, separated by a slash (/), either of which may be
a wildcard (*). Not specifying the type
attribute
indicates that all MIME types are acceptable.
If the return format is XML [XML 1.0], but the schema is not known ahead of time, the generic mime element can be used indicating "text/xml" [IETF RFC 3023]:
<mime:content type="text/xml"/>
A wildcard (*) can be used to specify a family of mime types, for example all text types.
<mime:content type="text/*"/>
The following two examples both specify all mime types:
<mime:content type="*/*"/> <mime:content/>
The "multipart/related" MIME type aggregates an arbitrary set of
MIME formatted parts into one message using the MIME type
"multipart/related". The mime:multipartRelated
element
describes the concrete format of such a message:
<mime:multipartRelated> <mime:part> * <-- mime element --> </mime:part> </mime:multipartRelated>
The mime:part
element describes each part of a
"multipart/related" message [IETF RFC
2387]. MIME elements appear within
mime:part
to specify the concrete MIME type for the
part. If more than one MIME element appears inside a
mime:part
, they are alternatives.
When using the MIME binding with SOAP requests [SOAP 1.2: Messaging Framework], it is
legal to use the soap:body
element as a MIME element.
It indicates the content type is "text/xml", and there is an
enclosing SOAP Envelope.
To specify XML payloads that are not SOAP compliant (do not have
a SOAP Envelope), but do have a particular schema, the
mime:mimeXml
element may be used to specify that
concrete schema. The part
attribute refers to a
message part defining the concrete schema of the root XML element.
The part
attribute MAY be omitted if the message has
only a single part. The part references a concrete schema using the
element
attribute for simple parts or
type
attribute for composite parts .
<mime:mimeXml part="nmtoken"?/>
This section does not directly contribute to the specification, but provide background that may be useful when implementing the specification.
It is a common misperception to equate the
targetNamespace
of an XML schema or the value of the
xmlns
attribute in XML instances with the location of
the corresponding schema. Since namespaces are in fact URIs, and
URIs may be locations, and you may be able to retrieve a schema
from that location, it does not mean that is the only schema that
is associated with that namespace. There can be multiple schemas
associated with a particular namespace, and it is up to a processor
of XML to determine which one to use in a particular processing
context. The WSDL specification provides the processing context
here via the import
mechanism, which is based on the
XML schemas grammar for the similar concept.
Throughout this document you see fully qualified URIs used in WSDL and XSD documents. The use of a fully qualified URI is simply to illustrate the referencing concepts. The use of relative URIs is completely allowed and is warranted in many cases. For information on processing relative URIs, see [IETF RFC 2396].
When working with WSDL, it is sometimes desirable to make up a URI for an entity, but not make the URI globally unique for all time and have it "mean" that version of the entity (schema, WSDL document, etc.). There is a particular URI base reserved for use for this type of behavior. The base URI "http://tempuri.org/" can be used to construct a URI without any unique association to an entity. For example, two people or programs could choose to simultaneously use the URI " http://tempuri.org/myschema" for two completely different schemas, and as long as the scope of the use of the URIs does not intersect, then they are considered unique enough. This has the further benefit that the entity referred to by the URI can be versioned without having to generate a new URI, as long as it makes sense within the processing context. It is not recommended that " http://tempuri.org/" be used as a base for stable, fixed entities.
Editorial note: JJM | 20020222 |
The examples in this section are SOAP 1.1 examples. |
POST /StockQuote HTTP/1.1 Host: www.stockquoteserver.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "Some-URI" <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <m:GetLastTradePrice xmlns:m="Some-URI"> <m:tickerSymbol>DIS</m:tickerSymbol> </m:GetLastTradePrice> </soapenv:Body> </soapenv:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <m:GetLastTradePriceResponse xmlns:m="Some-URI"> <m:price>34.5</m:price> </m:GetLastTradePriceResponse> </soapenv:Body> </soapenv:Envelope>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema" xmlns:soap="http://www.w3.org/2002/07/wsdl/soap11" targetNamespace="http://www.w3.org/2002/07/wsdl/soap11"> <element name="binding" type="soap:bindingType"/> <complexType name="bindingType"> <attribute name="transport" type="uriReference" use="optional"/> <attribute name="style" type="soap:styleChoice" use="optional"/> </complexType> <simpleType name="styleChoice"> <restriction base="string"> <enumeration value="rpc"/> <enumeration value="document"/> </restriction> </simpleType> <element name="operation" type="soap:operationType"/> <complexType name="operationType"> <attribute name="soapAction" type="uriReference" use="optional"/> <attribute name="style" type="soap:styleChoice" use="optional"/> </complexType> <element name="body" type="soap:bodyType"/> <complexType name="bodyType"> <attribute name="encodingStyle" type="uriReference" use="optional"/> <attribute name="parts" type="NMTOKENS" use="optional"/> <attribute name="use" type="soap:useChoice" use="optional"/> <attribute name="namespace" type="uriReference" use="optional"/> </complexType> <simpleType name="useChoice"> <restriction base="string"> <enumeration value="literal"/> <enumeration value="encoded"/> </restriction> </simpleType> <element name="fault" type="soap:faultType"/> <complexType name="faultType"> <complexContent> <restriction base="soap:bodyType"> <attribute name="parts" type="NMTOKENS" use="prohibited"/> </restriction> </complexContent> </complexType> <element name="header" type="soap:headerType"/> <complexType name="headerType"> <all> <element ref="soap:headerfault"> </all> <attribute name="message" type="QName" use="required"/> <attribute name="parts" type="NMTOKENS" use="required"/> <attribute name="use" type="soap:useChoice" use="required"/> <attribute name="encodingStyle" type="uriReference" use="optional"/> <attribute name="namespace" type="uriReference" use="optional"/> </complexType> <element name="headerfault" type="soap:headerfaultType"/> <complexType name="headerfaultType"> <attribute name="message" type="QName" use="required"/> <attribute name="parts" type="NMTOKENS" use="required"/> <attribute name="use" type="soap:useChoice" use="required"/> <attribute name="encodingStyle" type="uriReference" use="optional"/> <attribute name="namespace" type="uriReference" use="optional"/> </complexType> <element name="address" type="soap:addressType"/> <complexType name="addressType"> <attribute name="location" type="uriReference" use="required"/> </complexType> </schema>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema" xmlns:http="http://www.w3.org/2002/07/wsdl/http" targetNamespace="http://www.w3.org/2002/07/wsdl/http"> <element name="address" type="http:addressType"/> <complexType name="addressType"> <attribute name="location" type="uriReference" use="required"/> </complexType> <element name="binding" type="http:bindingType"/> <complexType name="bindingType"> <attribute name="verb" type="NMTOKEN" use="required"/> </complexType> <element name="operation" type="http:operationType"/> <complexType name="operationType"> <attribute name="location" type="uriReference" use="required"/> </complexType> <element name="urlEncoded"> <complexType> </complexType> </element> <element name="urlReplacement"> <complexType> </complexType> </element> </schema>
<schema targetNamespace="http://www.w3.org/2002/07/wsdl/mime" xmlns:mime="http://www.w3.org/2002/07/wsdl/mime" xmlns="http://www.w3.org/2000/10/XMLSchema"> <element name="content" type="mime:contentType"/> <complexType name="contentType" content="empty"> <attribute name="type" type="string" use="optional"/> <attribute name="part" type="NMTOKEN" use="optional"/> </complexType> <element name="multipartRelated" type="mime:multipartRelatedType"/> <complexType name="multipartRelatedType" content="elementOnly"> <element ref="mime:part" minOccurs="0" maxOccurs="unbounded"/> </complexType> <element name="part" type="mime:partType"/> <complexType name="partType" content="elementOnly"> <any namespace="targetNamespace" minOccurs="0" maxOccurs="unbounded"/> <attribute name="name" type="NMTOKEN" use="required"/> </complexType> <element name="mimeXml" type="mime:mimeXmlType"/> <complexType name="mimeXmlType" content="empty"> <attribute name="part" type="NMTOKEN" use="optional"/> </complexType> </schema>
This document is the work of the W3C Web Services Description Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Adi Sakala (IONA Technologies), Allen Brookes (Rogue Wave Softwave), Arthur Ryman (IBM), Dale Moberg (Cyclone Commerce), Dan Kulp (IONA Technologies), Daniel Schutzer (Citigroup), Dave Solo (Citigroup), David Booth (W3C), Dietmar Gaertner (Software AG), Don Mullen (TIBCO Software), Don Wright (Lexmark), Glen Daniels (Macromedia), Igor Sedukhin (Computer Associates), Jacek Kopecky (Systinet), Jean-Jacques Moreau (Canon), Jeff Mischkinsky (Oracle Corporation), Jeffrey Schlimmer (Microsoft Corporation), Jerry Thrasher (Lexmark), Jochen Ruetschlin (DaimlerChrysler Research and Technology), Johan Pauhlsson (L'Échangeur), Jonathan Marsh (Chair, Microsoft Corporation), Joyce Yang (Oracle Corporation), Kevin Canyang Liu (SAP), Laurent De Teneuille (L'Échangeur), Mario Jeckle (DaimlerChrysler Research and Technology), Martin Gudgin (Microsoft Corporation), Michael Champion (Software AG), Michael Mahan (Nokia), Michael Mealling (Verisign), Mike Ballantyne (Electronic Data Systems), Mike Davoren (W. W. Grainger), Mike McHugh (W. W. Grainger), Pallavi Malu (Intel Corporation), Philippe Le Hégaret (W3C), Prasad Yendluri (webMethods, Inc.), Roberto Chinnici (Sun Microsystems), Sandeep Kumar (Cisco Systems), Sandra Swearingen (U.S. Department of Defense, U.S. Air Force), Sanjiva Weerawarana (IBM), Stefano Pogliani (Sun Microsystems), Steve Graham (Global Grid Forum), Steve Lind (AT&T), Steve Tuecke (Global Grid Forum), Tim Finin (University of Maryland), Tom Jordahl (Macromedia), Waqar Sadiq (Electronic Data Systems), William Stumbo (Xerox), William Vambenepe (Hewlett-Packard Company), Youenn Fablet (Canon)
Previous members were: Aaron Skonnard (DevelopMentor), Krishna Sankar (Cisco Systems)
The people who have contributed to discussions on www-ws-desc@w3.org are also gratefully acknowledged.
Date | Author | Description |
---|---|---|
20020702 | JJM | Added summary to prefix table. |
20020628 | JJM | Added out-of-synch-with-Part2 and not-soap12-yet ednote. |
20020621 | JJM | Commented out the link to the previous version. There is no previous version for 1.2 right now. |
20020621 | JJM | Rewrote the Notation Conventions section. |
20020621 | JJM | Added reference to part 0 in introduction. Renumbered references. |
20020621 | JJM | Simplified abstract and introduction. |
20020621 | JJM | Obtain the list of WG members from a separate file. |
20020621 | JJM | Updated stylesheet and DTDs to latest XMLP stylesheet and DTDs. |
20020621 | JJM | Deleted placeholder for appendix C "Location of Extensibility Elements", since this is part 1 stuff and extensibility has been reworked anyway. |
20020621 | JJM | Corrected link to issues lists |
20020621 | JJM | Updated title from "WSDL" to "Web Services Description Language". Now refer to part 1 as "Web Services... Part 1: Framework |
20020621 | JJM | Added Jeffrey as an editor :-). Removed Gudge (now on Part 2) :-( |
20020411 | JJM | Fixed typos noticed by Kevin Liu |
20020301 | JJM | Converted the "Schemas" sections |
20020301 | JJM | Converted the "Wire WSDL examples" sections |
20020301 | JJM | Converted the "Notes on URIs" sections |
20020301 | JJM | Converted the "Notational Conventions" sections |
20020301 | JJM | Converted the "References" sections |
20020301 | JJM | Converted the "MIME Binding" section to XML |
20020221 | JJM | Converted the "HTTP Binding" section to XML |
20020221 | JJM | Added placeholders for the "Wire examples" and "Schema" sections |
20020221 | JJM | Converted the "SOAP Binding" section to XML |
20020221 | JJM | Added the Change Log |
20020221 | JJM | Added the Status section |
20020221 | JJM | Simplified the introduction; referred to Part1 for a longer introduction |
20020221 | JJM | Renamed to "Part 2: Bindings" |
20020221 | JJM | Created from http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
The encoding schema has been updated to be compliant with the XML Schema Recommendations ([XML Schema Structures] and [XML Schema Datatypes]). The table below shows the categories of change.
Class | Meaning |
---|---|
@@@ | @@@ |
The table below lists the changes to the encoding schema.
Class | Description |
---|---|
@@@ | @@@ |