Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings

1.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 [IETF RFC 2119].

This specification uses a number of namespace prefixes throughout; they are listed in Table 1-1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).

Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs [IETF RFC 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.

2.1 How the SOAP Binding Extends WSDL (Non-normative)

<definitions >
 <binding>
  <wsoap:binding protocol="uri"/>
  <wsoap:module uri="uri"
               required="boolean"? >
   <wsoap:propertyConstraint uri="uri"
                            type="qname"? />?
  </wsoap:module>?
  <operation>
   <wsoap:operation soapAction="uri" /> ?
   <(in|out)put>
    <wsoap:header element="qname"
                 mustUnderstand="boolean"?
                 role="uri"? />*
   </(in|out)put>
  </operation>
 </binding>

 <service>
  <endpoint>
   <wsoap:address location="uri" />
  </endpoint>
 </service>
</definitions>

2.2 binding Element with binding [parent]

<definitions >
 <binding >
  <wsoap:binding protocol="uri"/>
 </binding>
</definitions>

The REQUIRED binding element information item indicates that messages are SOAP Envelopes [SOAP 1.2 Part 1: Messaging Framework].

The binding element information item has the following Infoset properties:

• A [local name] of binding

• A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/soap12"

• A [parent] of binding in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• One or more attribute information items amongst its [attributes] as follows:

  • A REQUIRED protocol attribute information item as described below.

The binding element information item has no [children].

2.3 module Element with binding [parent]

<definitions >
 <binding >
  <wsoap:module uri="uri"
               required="boolean"? >
  </wsoap:module>
 </binding>
</definitions>

The OPTIONAL module element information item indicates SOAP module(s) supported by a binding element information item. A SOAP module[SOAP 1.2 Part 1: Messaging Framework] realizes zero or more SOAP features implemented as one or more SOAP header blocks.

The module element information item has the following Infoset properties:

• A [local name] of module

• A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/soap12"

• A [parent] of binding in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• One or more attribute information items amongst its [attributes] as follows:

  • A required uri attribute information item as described below

  • An optional required attribute information item as described below

2.4 propertyConstraint Element with module [parent]

<definitions>
 <binding>
  <wsoap:module>
   <wsoap:propertyConstraint uri="uri"
                            type="qname"? />
  </wsoap:module>
 </binding>
</definitions>

The OPTIONAL propertyConstraint element information item indicates SOAP module(s) supported by a module element information item.

The propertyConstraint element information item has the following Infoset properties:

• A [local name] of propertyConstraint

• A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/soap12"

• A [parent] of module in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• One or more attribute information items amongst its [attributes] as follows:

  • A required uri attribute information item as described below

  • An optional type attribute information item as described below

The value of the propertyConstraint element information item is the value that is required for the SOAP property of the [parent] module .

The propertyConstraint element information item has no [children].

2.5 operation Element with operation [parent]

<definitions>
 <binding>
  <operation>
   <wsoap:operation soapAction="uri" /> ?
  </operation>
 </binding>
</definitions>

The OPTIONAL operation element information item provides binding information for 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/soap12"

• A [parent] of operation in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• Zero or more attribute information items amongst its [attributes] as follows:

  • A REQUIRED soapAction attribute information item as described below

The operation element information item has no [children].

2.6 header Element with input or output [parent]

<definitions>
 <binding>
  <operation>
   [ <input> | <output> ]
    <wsoap:header element="qname"
                 mustUnderstand="boolean"?
                 role="uri"? />*
   [ </input> | </output> ]
  </operation>
 </binding>
</definitions>

The OPTIONAL header element information item specifies SOAP header block(s) for the [ancestor] operation. The header element information item has the following Infoset properties:

• A [local name] of header

• A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/soap12"

• A [parent] of input or output in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• One or more attribute information items amongst its [attributes] as follows:

  • An REQUIRED element attribute information item as described below

  • An OPTIONAL mustUnderstand attribute information item as described below

  • An OPTIONAL role attribute information item as described below

The header element information item has no [children].

The header element information item allow headers to be defined that are transmitted as SOAP header blocks. It is not necessary to exhaustively list all header blocks that appear in the SOAP Envelope using header element information items. For example, extensions (see Language Extensibility and Binding, [WSDL 2.0 Core Language], 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.

2.7 headerfault Element with input or output [parent]

<definitions>
 <binding>
  <operation>
    [ <input> | <output> ]
    <wsoap:headerfault message="qname"
                      part="nmtoken"
                      namespace="uri"?
                      encodingStyle="uri"? />*
    [ </input> | </output> ]
  </operation>
 </binding>
</definitions>

The optional headerfault element information item specifies SOAP fault header block(s) for the [ancestor] operation. The SOAP specification states that errors pertaining to header blocks have to be returned in header blocks, and this mechanism allows specifying the format of such fault header blocks.

The headerfault element information item has the following Infoset properties:

• A [local name] of headerfault

• A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl/soap12"

• A [parent] of input or output in the namespace named "http://www.w3.org/@@@@/@@/wsdl"

• One or more attribute information items amongst its [attributes] as follows:

  • A mandatory message attribute information item as described below.

  • A mandatory part attribute information item as described below.

  • An optional namespace attribute information item as described below.

  • An optional encodingStyle attribute information item as described below.

The headerfault element information item has no [children].

The headerfault element information item allows fault headers to be defined that are transmitted as SOAP fault header blocks, and that carry information pertaining to the faulty SOAP header block defined by the corresponding header .

The namespace attribute information items MUST be specified if and only if the type attribute information item is specified.

2.8 address Element with endpoint [parent]

<definitions>
 <service>
  <endpoint>
   <wsoap:address location="uri" />
  </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/soap12"

• 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].

3.1 binding Element with binding [parent]

<definitions>
    <binding>
        <http:binding verbDefault="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 verbDefault attribute information item as described below.

The binding element information item has no [children].

3.2 operation Element with operation [parent]

<definitions>
    <binding>
        <operation>
            <http:operation location="xsd:anyURI"?
                            verb="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 verb attribute information item as described below.

The operation element information item has no [children].

If the operation element information item has no [attributes], it MAY be omitted.

3.3 Method is GET

The rules in this section MUST be followed when the HTTP method is "GET".

3.4 Method is POST

The rules in this section MUST be followed when the HTTP method is "POST".

3.5 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].

4.1 How the MIME Binding extends WSDL

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.

4.2 mime:content

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/>

4.3 mime:multipartRelated

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.

4.4 wsoap:body

When using the MIME binding with SOAP requests [SOAP 1.2 Part 1: Messaging Framework], it is legal to use the wsoap:body element as a MIME element. It indicates the content type is "text/xml", and there is an enclosing SOAP Envelope.

4.5 mime:mimeXml

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"?/>

5.1 Normative References

[HTML 4.01]

HTML 4.01 Specification, D. Raggett, A. Le Hors, I. Jacobs, Editors. World Wide Web Consortium, 24 December 1999. This version of the HTML 4.01 Recommendation is http://www.w3.org/TR/1999/REC-html401-19991224. The latest version of HTML 4.01 is available at http://www.w3.org/TR/html401.

[IETF RFC 2045]

Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, N. Freed, N. Borenstein, Authors. Internet Engineering Task Force, November 1996. Available at http://www.ietf.org/rfc/rfc2045.txt.

[IETF RFC 2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2119.txt.

[IETF RFC 2387]

The MIME Multipart/Related Content-type, E. Levinson, Authors. Internet Engineering Task Force, August 1998. Available at http://www.ietf.org/rfc/rfc2387.txt.

[IETF RFC 2396]

Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, Authors. Internet Engineering Task Force, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt.

[IETF RFC 2616]

Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, Authors. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt.

[IETF RFC 3023]

XML Media Types, M. Murata, S. St. Laurent, D. Kohn, Authors. Internet Engineering Task Force, January 2001. Available at http://www.ietf.org/rfc/rfc3023.txt.

[SOAP 1.2 Part 1: Messaging Framework]

SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World Wide Web Consortium, 24 June 2003. This version of the "SOAP Version 1.2 Part 1: Messaging Framework" Recommendation is http://www.w3.org/TR/2003/REC-soap12-part1-20030624/. The latest version of "SOAP Version 1.2 Part 1: Messaging Framework" is available at http://www.w3.org/TR/soap12-part1/.

[SOAP 1.2 Part 2: Adjuncts]

SOAP Version 1.2 Part 2: Adjuncts, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, and H. Frystyk Nielsen, Editors. World Wide Web Consortium, 7 May 2003. This version of the "SOAP Version 1.2 Part 2: Adjuncts" Recommendation is http://www.w3.org/TR/2003/REC-soap12-part2-20030624/. The latest version of "SOAP Version 1.2 Part 2: Adjuncts" is available at http://www.w3.org/TR/soap12-part2/.

[XML 1.0]

Extensible Markup Language (XML) 1.0 (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.

[XML Information Set]

XML Information Set, J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2001/REC-xml-infoset-20011024. The latest version of XML Information Set is available at http://www.w3.org/TR/xml-infoset.

[XML Schema Structures]

XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-1-20010502. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1.

[XML Schema Datatypes]

XML Schema Part 2: Datatypes, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-2-20010502. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2.

[WSDL 2.0 Core Language]

Web Services Description Language (WSDL) Version 2.0: Core Language, R. Chinnici, M. Gudgin, J-J. Moreau, S. Weerawarana, Editors. World Wide Web Consortium, @@ @@@@ @@@@. This version of the "Web Services Description Version 2.0: Core Language" Specification is available is available at wsdl20.html. The latest version of "Web Services Description Version 2.0: Core Language" is available at http://www.w3.org/2002/ws/desc/wsdl20.

5.2 Informative References

[WSDL 2.0 Primer]

Web Services Description (WSDL) Version 2.0: Primer, K. Sankar, K. Liu, D. Booth, Editors. World Wide Web Consortium, @@ @@@@ @@@@. The editors' version of the "Web Services Description Version 2.0: Primer" document is available from http://www.w3.org/2002/ws/desc/.