This document is also available in these non-normative formats: .
Copyright © @@@@ W3C® (MIT, ERCIM, 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. This document describes how to use WSDL in conjunction with HTTP/1.1 [IETF RFC 2616].
This document is an editors' copy that has no official standing.
1. Introduction
2. WSDL 2.0 Extension elements for HTTP
3. Operation Styles
4. Serialization format of instance data
5. References
1. Introduction
1.1 Origin and Goals
1.2 Notational Conventions
2. WSDL 2.0 Extension elements for HTTP
2.1
binding Element with binding [parent]
2.1.1 methodDefault Attribute with
binding [owner]
2.2
operation Element with operation
[parent]
2.2.1
location Attribute with operation
[owner]
2.2.2
method Attribute with operation
[owner]
2.2.3
separator Attribute with operation
[owner]
2.3
address Element with endpoint [parent]
2.3.1
location Attribute with address [owner]
3. Operation Styles
3.1 URI Style
3.2 Multipart style
4. Serialization format of instance data
4.1 Serialization as application/x-www-form-urlencoded
4.1.1 Case of elements cited in location attribute
4.1.2 Case of elements NOT cited in location
attribute
4.2 Serialization as application/xml
4.3 Serialization as multipart/form-data
5. References
5.1 Normative References
5.2 Informative References
The WSDL 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]. This
binding extends WSDL 2.0 by adding element information items and attribute information items to the
Infoset of the WSDL binding element information item and service
element information item (in the "http://www.w3.org/@@@@/@@/wsdl" namespace).
[Definition: The internal tree representation of an input or an output message is called an instance data, and is constrained by the schema definition associated the message.]
[SOAP 1.2 Part 1: Messaging Framework] is a "lightweight protocol intended for exchanging structured information in a decentralized, distributed environment", and defined an extensible messaging framework along a processing model. However, SOAP 1.2 applications use only the full potential of the protocol when extensions are being used (reliability, security, correlation, routing). Without those extensions, the use of SOAP 1.2 is purely limited to the exchange of structured information. HTTP 1.1 is widely deployed on the Web and can also be used for exchanging structured information, without adding an additional layer on top of it. Its extension mechanisms and its processing model are however limited and don't have the same flexibility as SOAP 1.2.
A Web Service that is using HTTP 1.1, without using any additional layer, is therefore limited in the set of capabilities and extensions but, because of the absence of the additional layer, is simpler to deploy and can use existing technologies.
The HTTP 1.1 binding takes also advantages of the existing architecture of the World Wide Web, by allowing the reuse of basic concepts, such as "Safe Interactions" ([Architecture of the World Wide Web], Section 3.5). Applications are encouraged to follow the finding of the W3C Technical Architecture Group on when to use the HTTP GET method [TAG Finding 10].
The HTTP 1.1 binding is intended to be used with the
"http" URI scheme [IETF RFC 2616], and
the "https" URI scheme [IETF RFC 2818].
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]).
| Prefix | Namespace | Notes |
|---|---|---|
| wsdl | "http://www.w3.org/@@@@/@@/wsdl" | A normative XML Schema [XML Schema Structures], [XML Schema Datatypes] document for the "http://www.w3.org/@@@@/@@/wsdl" namespace can be found at http://www.w3.org/@@@@/@@/wsdl. |
| http | "http://www.w3.org/@@@@/@@/wsdl/http" | A normative XML Schema [XML Schema Structures], [XML Schema Datatypes] document for the "http://www.w3.org/@@@@/@@/wsdl/http" namespace can be found at http://www.w3.org/@@@@/@@/wsdl/http. |
| xsd | "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].
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.
The HTTP binding for WSDL 2.0 contains the following extension elements:
<definitions>
<binding>
<http:binding methodDefault="xsd:string"? />
<operation>
<http:operation location="xsd:anyURI"?
method="xsd:string"? />?
separator="xsd:string"?/>?
</operation>
</binding>
<service>
<endpoint>
<http:address location="xsd:anyURI" />
</endpoint>
</service>
</definitions>binding Element with binding [parent]
<definitions>
<binding>
<http:binding methodDefault="xsd:string"? />
</binding>
</definitions>
The mandatory binding element information item indicates that messages
are HTTP messages [IETF RFC 2616].
The binding element information item has the following Infoset
properties:
A [local name] of binding
A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/http"
A [parent] of binding in the namespace named
"http://www.w3.org/@@@@/@@/wsdl"
Zero or one attribute information items amongst its [attributes] as follows:
An optional methodDefault attribute information item as
described below.
The binding element information item has no [children].
methodDefault Attribute with
binding [owner]
The methodDefault attribute information item indicates the HTTP method
used within a binding element information item, for example
"GET" or "POST".
The methodDefault attribute information item has the following Infoset
properties:
A [local name] of methodDefault
A [namespace name] which has no value
An [owner] of binding in the namespace named
"http://www.w3.org/@@@@/@@/wsdl/http"
The type of the methodDefault attribute information item is
xsd:string. The value of the
methodDefault attribute information item is a string that identifies a
specific method, as described below. Each value is
associated to two serialization formats (one for the input
messages, one of the output messages), and an HTTP
method. Refer to the section 4. Serialization format of instance data to find the corresponding
serialization formats.
| Method | Input serialization | Output serialization | HTTP Method | Message Patterns | Operation Style |
|---|---|---|---|---|---|
| "post" | application/xml |
application/xml |
HTTP POST | In-Only, Robust In-Only, In-Out | any |
| "get" | application/x-www-form-urlencoded |
application/xml |
HTTP GET | In-Only, Robust In-Only, In-Out | URI style |
| "form-data-post" | multipart/form-data |
application/xml |
HTTP POST | In-Only, Robust In-Only, In-Out | Multipart style |
The methods "put", "multipart-post", and "urlencoded-post", as defined in "Submission Options" ([XForms 1.0], Section 11.2) are not supported by this specification.
Doesn't list the Out patterns for the moment. Waiting to see how the dicussion on addressing is going to stabilize.
Mechanisms that are outside the scope of this specification
MAY modify the serialization format of the instance data corresponding to
the output message. An example of such modification is the
combinaison of the serialization as
application/x-www-form-urlencoded and the SOAP
Response Message Exchange Pattern ([SOAP 1.2 Part 2: Adjuncts], Section 6.3).
operation Element with operation
[parent]
<definitions>
<binding>
<operation>
<http:operation location="xsd:anyURI"?
method="xsd:string"?
separator="xsd:string"?/>?
</operation>
</binding>
</definitions>
The optional operation element information item provides
binding information to the [parent] operation.
The operation element information item has the following
Infoset properties:
A [local name] of operation
A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/http"
A [parent] of operation in the
namespace named "http://www.w3.org/@@@@/@@/wsdl"
Zero to two attribute information items amongst its [attributes] as follows:
An optional location attribute information item as
defined below.
An optional method attribute information item as
described below.
An optional separator attribute information item as
defined below.
The operation element information item has no [children].
If the operation element information item has no [attributes],
it MAY be omitted.
location Attribute with operation
[owner]
The location attribute information item indicates a relative URI for a
particular operation element information item. The location
attribute information item may also indicate which portions of an input message are
serialized in the path of the request URI (as opposed to
simply being serialized as query parameters of the request URI
or in the body of the request).
The location attribute information item has the following Infoset
properties:
A [local name] of location
A [namespace name] which has no value
An [owner] of operation in the namespace
named "http://www.w3.org/@@@@/@@/wsdl/http"
The type of the location attribute information item is
xsd:anyURI, and MUST contain an absolute or a
relative URI, i.e. it MUST NOT include a fragment identifier
in the URI.
Should it be relative to the address of the service or to
the [base URI] property of the location element information item?
The location attribute information item specifies a template for the
relative portion of the request URI for an operation. This URI
is combined with the base URI specified in the
address element information item to form the full URI for the HTTP
request to invoke the operation.
Message parts are serialized according to the rules of:
method Attribute with operation
[owner]
The method attribute information item indicates the method used by a
particular operation element information item.
The method attribute information item has the following Infoset
properties:
A [local name] of method
A [namespace name] which has no value
An [owner] of operation in the namespace named
"http://www.w3.org/@@@@/@@/wsdl/http"
The type of the method attribute information item is
xsd:string.
The value of the method attribute information item is a string that
identifies a specific method to be used with this
operation. The set of recognized methods is equivalent to the
set of recognized methods on the methodDefault
attribute information item (listed in Table 2-1).
If there is no method attribute information item, the method to be
used is specified by the methodDefault attribute information item with
[owner] binding . It is a fatal error if there is no
method attribute information item or methodDefault attribute information item.
If the result method is "get", the {style}
property of the interface
operation component associated with the binding
operation MUST have a value http://www.w3.org/@@@@/@@/wsdl/style/uri. If
the result method is "form-data-post", the
{style} property of the interface
operation component associated with the binding
operation MUST have a value http://www.w3.org/@@@@/@@/wsdl/style/uri.
separator Attribute with operation
[owner]
The separator attribute information item indicates the character to be
used to separate query parameter pairs if the serialization
format is application/x-www-form-urlencoded.
The separator attribute information item has the following Infoset
properties:
A [local name] of separator
A [namespace name] which has no value
An [owner] of operation in the namespace named
"http://www.w3.org/@@@@/@@/wsdl/http"
The type of the separator attribute information item is
xsd:string. The default value is ';' (the semi
colon character). If more than one character is contained in
the attribute, the first one is the separator charater and
others are ignored.
address Element with endpoint [parent]
<definitions>
<service>
<endpoint>
<http:address location="xsd:anyURI" />
</endpoint>
</service>
</definitions>
The mandatory address element information item contains the endpoint
address of an endpoint . The address element information item has
the following Infoset properties:
A [local name] of address.
A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/http."
A [parent] of endpoint in the namespace named
"http://www.w3.org/@@@@/@@/wsdl."
One attribute information item amongst its [attributes] as follows:
A required location attribute information item as described
below.
The address element information item has no [children].
location Attribute with address [owner]
The mandatory location attribute information item identifies the
endpoint address of an endpoint . The
location attribute information item has the following Infoset
properties:
A [local name] of location.
A [namespace name] which has no value.
An [owner] of address in the namespace named
"http://www.w3.org/@@@@/@@/wsdl/http".
The type of the location attribute information item is
xsd:anyURI . The value of the location
attribute information item is a URI that processes messages bound by the
endpoint . The URI scheme of the value of the
location attribute information item MUST correspond to the transport
specified by the value of the binding attribute information item of
the endpoint element information item.
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 {style} property the value http://www.w3.org/@@@@/@@/wsdl/style/uri.
The URI style may only be used for Interface Operation components whose {message exchange pattern} property has the value 'http://www.w3.org/@@@@/@@/wsdl/in-only', 'http://www.w3.org/@@@@/@@/wsdl/robust-in-only' or 'http://www.w3.org/@@@@/@@/wsdl/in-out'.
Use of this value indicates that XML Schema [XML Schema Structures] was used to define the schemas of the {message} properties of all {message reference} components of the Interface Operation component with {direction} property in. Those schemas MUST adhere to the rules below.
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
nillable attribute, and the attributes
minOccurs and maxOccurs MUST have
a value 0 or 1.
The localPart of input element's QName MUST be the same as the Interface operation component's name.
| Editorial note | |
| Not sure why we need this but we probably have good reasons to keep in RPC style, so I guess the reasons also apply here. | |
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
xsd:simpleType, and MUST NOT derive from
xsd:hexBinary or
xsd:base64Binary.
The Multipart style is selected by assigning the Interface Operation component's {style} property the value http://www.w3.org/@@@@/@@/wsdl/style/multipart.
The URI style may only be used for Interface Operation components whose {message exchange pattern} property has the value 'http://www.w3.org/@@@@/@@/wsdl/in-only', 'http://www.w3.org/@@@@/@@/wsdl/robust-in-only' or 'http://www.w3.org/@@@@/@@/wsdl/in-out'.
Use of this value indicates that XML Schema [XML Schema Structures] was used to define the schemas of the {message} properties of all {message reference} components of the Interface Operation component with {direction} property in. Those schemas MUST adhere to the rules below.
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
nillable attribute, and the attributes
minOccurs and maxOccurs MUST have
a value 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.
The following serialization formats are used to encode the instance data corresponding to the input and output message, as well as the media types and HTTP headers associated.
This serialization format is designed to allow a Web Service to produce a URI based on the instance data of input messages.
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:
Example 4-1. instance data serialized in a URI
The following instance data of an input message
<data> <town>Fréjus</town> <date>2004-01-16</date> <unit>C</unit> </data>
with the following operation element
<http:operation
location='temperature/{town}'
method='get' separator='&'/>will serialize the message in the URI as follow:
temperature/Fr%C3%A9jus?date=2004-01-16&unit=C
Note:
Element name and element content MUST be URI escaped when inserted into the request, as defined in "Serialization as application/x-www-form-urlencoded" ([XForms 1.0], Section 11.6).
location attributeThe inclusion of elements of the instance data in the path of the request URI, while supported by WSDL 1.1, is not supported by XForms 1.0. This mechanism MAY be removed in a future version of this specification and feedback from users and implementers is highly encouraged on this issue.
The location attribute information item MAY cite elements from the
instance data of the
input message to be serialized in the path of the request
URI ("URI Syntactic Components", [IETF RFC 2396],
Section 3) by enclosing the element name within curly braces
(e.g. location="temperature/{town}"):
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
location attribute information item.
Strings enclosed within single curly braces MUST be element names from the instance data of the input message; any other strings enclosed within single curly braces are a fatal error.
location
attribute
All elements of the instance
data from the input message NOT cited by the
location attribute information item are serialized as query parameters
appended to the request URI.
If the location attribute does not contain a '?'
(question mark) character, one is appended. If it does
already contain a question mark character, then a separator
character is appended. Each parameter pair is separated by
the separator character (see 2.2.3
separator Attribute with operation
[owner]
.
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 part, and the value of each parameter is the corresponding value in the list.
The instance data of the input or output message is serialized as an XML document in the message body of the HTTP request, following the serialization defined in [Canonical XML].
Not many serialization forms are defined for XML: XSLT 1.0 output method, XForms 1.0, and Canonical XML. Canonical XML has the advantage of removing the xml declaration and the document type declaration, but it only works with XML 1.0, requires UTF-8 and UTF-16 supports only. An other solution would be to follow XML Signature and includes the support to change the canonical algorithm. In any case, the best way is to say "see the serialization of the SOAP body".
The term instance data doesn't say anything
about xsi:type attributes and others. Do we
want to say something here?
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 [IETF RFC 2387] servers.
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
xsd:base64Binary,
xsd: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.
| Editorial note | |
| I definitively need media type handling here. | |
If the type is xsd:base64Binary,
xsd:hexBinary, xsd: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 4.2 Serialization as application/xml.
Example 4-2. Example of multipart/form-data
The following instance data of an input message:
<data>
<town>
<name>Fréjus</name>
<country>France</country>
</town>
<date>2004-01-16</date>
</data>
with the following operation element
<http:operation
location='temperature'
method='form-data-post'/>will serialize the message as follow:
Content-Type: multipart/form-data; boundary=AaB03x
Content-Length: xxx
--AaB03x
Content-Disposition: form-data; name="town"
Content-Type: application/xml
<town>
<name>Fréjus</name>
<country>France</country>
</town>
--AaB03x
Content-Disposition: form-data; name="date"
Content-Type: text/plain; charset=utf-8
2004-01-16
--AaB03x--