Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts

2.1.1 Pattern Name

This pattern consists of [number] message[s, in order] as follows:

[enumeration, specifying, for each message] A[n optional] message:

1. indicated by a Interface Message Reference component whose {message label} is "[label]" and direction is "[direction]"

2. [received from|sent to] ['some' if first mention] node [node identifier]

This pattern uses the rule [fault ruleset reference].

An operation using this message exchange pattern has a {message exchange pattern} property with the value "[pattern IRI]".

Note: In the template, the bracketed items indicate a replacement operation. Substitute the correct terms for each bracketed item.

Note: the "received from" and "sent to" are always from the point of view of the service, and participating nodes other than the service are implicitly identified as the originators of or destinations for messages in the exchange.

2.2.1 Fault Replaces Message

Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical direction. The fault message MUST be delivered to the same target node as the message it replaces, unless otherwise specified by an extension or binding extension. If there is no path to this node, the fault MUST be discarded.

2.2.2 Message Triggers Fault

Any message, including the first in the pattern, MAY trigger a fault message, which MUST have opposite direction. The fault message MUST be delivered to the originator of the triggering message, unless otherwise specified by an extension of binding extension. Any node MAY propagate a fault message, and MUST not do so more than once for each triggering message. If there is no path to the originator, the fault MUST be discarded.

2.2.3 No Faults

No faults may be propagated.

2.3.1 In-Only

This pattern consists of exactly one message as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • received from some node N

This pattern uses the rule 2.2.3 No Faults.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/in-only".

2.3.2 Robust In-Only

This pattern consists of exactly one message as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • received from some node N

This pattern uses the rule 2.2.2 Message Triggers Fault.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/robust-in-only".

2.3.3 In-Out

This pattern consists of exactly two messages, in order, as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • received from some node N

2. A message:

   • indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"

   • sent to node N

This pattern uses the rule 2.2.1 Fault Replaces Message.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/in-out".

2.3.4 In-Optional-Out

This pattern consists of one or two messages, in order, as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • received from some node N

2. An optional message:

   • indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"

   • sent to node N

This pattern uses the rule 2.2.2 Message Triggers Fault.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/in-opt-out".

2.3.5 Out-Only

This pattern consists of exactly one message as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "Out " and {direction} is "out"

   • sent to some node N

This pattern uses the rule 2.2.3 No Faults.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/out-only".

2.3.6 Robust Out-Only

This pattern consists of exactly one message as follows:

1. message:

   • indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"

   • sent to some node N

This pattern uses the rule 2.2.2 Message Triggers Fault.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/robust-out-only".

2.3.7 Out-In

This pattern consists of exactly two messages, in order, as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"

   • sent to some node N

2. A message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • sent from node N

This pattern uses the rule 2.2.1 Fault Replaces Message.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/out-in".

2.3.8 Out-Optional-In

This pattern consists of one or two messages, in order, as follows:

1. A message:

   • indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"

   • sent to some node N

2. An optional message:

   • indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"

   • sent from node N

This pattern uses the rule 2.2.2 Message Triggers Fault.

An operation using this message exchange pattern has a {message exchange pattern} property with the value "http://www.w3.org/2005/08/wsdl/out-opt-in".

3.1.1 Relationship to WSDL Component Model

The safety extension adds the following property to the Interface Operation component model (as defined in [WSDL 2.0 Core Language]):

• {safety} REQUIRED. An xs:boolean indicating whether the operation is asserted to be safe for users of the described service to invoke. If this property is "false", then no assertion has been made about the safety of the operation, thus the operation MAY or MAY NOT be safe. However, an operation SHOULD be marked safe if it meets the criteria for a safe interaction defined in Section 3.5 of [Web Architecture].

3.1.2 XML Representation

<description>
 <interface>
   <operation name="xs:NCName" pattern="xs:anyURI"
              wsdlx:safe="xs:boolean"? >
  </operation>
 </interface>
</description>

The XML representation for the safety extension is an attribute information item with the following Infoset properties:

• An OPTIONAL safe attribute information item with the following Infoset properties:

  • A [local name] of safe

  • A [namespace name] of "http://www.w3.org/2005/08/wsdl-extensions"

  • A type of xs:boolean

3.1.3 Mapping from XML Representation to Component Properties

See Table 3-1.

4.1.1 wrpc:signature Extension

The wrpc:signature extension attribute information item MAY be used in conjunction with the RPC style to describe the exact signature of the function represented by an operation that uses the RPC style.

When present, the wrpc:signature extension contributes the following property to the Interface Operation component it is applied to:

• {rpc signature} REQUIRED. A list of pairs (q, t) whose first component is of type xs:QName and whose second component is of type xs:token. Values for the second component MUST be chosen among the following four: "#in", "#out", "#inout" "#return".

The value of the {rpc signature} property MUST satisfy the following conditions:

• The value of the first component of each pair (q, t) MUST be unique within the list.

• For each child element of the input and output messages of the operation, a pair (q, t) whose first component q is equal to the qualified name of that element MUST be present in the list, with the caveat that elements that appear with cardinality greater than one MUST be treated as a single element.

• For each pair (q, #in), there MUST be a child element of the input element with a name of q and there MUST NOT be a child element of the output element with the same name.

• For each pair (q, #out), there MUST be a child element of the output element with a name of q and there MUST NOT be a child element of the input element with the same name.

• For each pair (q, #inout), there MUST be a child element of the input element with a name of q and there MUST be a child element of the output element with the same name. Furthermore, those two elements MUST have the same type.

• For each pair (q, #return), there MUST be a child element of the output element with a name of q and there MUST NOT be a child element of the input element with the same name.

The function signature defined by a wrpc:signature extension is determined as follows:

1. Start with the value of the {rpc signature} property, a (possibly empty) list of pairs of this form:

       [(q0, t0), (q1, t1), ...]

2. Filter the elements of this list into two lists, the first one (L1) comprising pairs whose t component is one of {#in, #out, #inout}, the second (L2) pairs whose t component is #return. During the composition of L1 and L2, the relative order of members in the original list MUST be preserved.

   For ease of visualization, let's denote the two lists as

       (L1)    [(a0, u0), (a1, u1),...]

   and

       (L2)    [(r0, #return), (r1, #return),...]

   respectively.

3. Then, if the input sequence ends with an element wildcard, the formal signature of the function is

       f([d0] a0, [d1] a1, ..., rest) => (r0, r1, ...)

   where rest is a formal parameter representing the elements in the input message matched by the element wildcard.

   Otherwise the formal signature of the function is

       f([d0] a0, [d1] a1, ...) => (r0, r1, ...)

   i.e.

   • the list of formal arguments to the function is [a0, a1, ...];

   • the direction d of each formal argument a is one of [in], [out], [inout], determined according to the value of its corresponding u token;

   • the list of formal return parameters of the function is [r0, r1, ...];

   • each formal argument and formal return parameter is typed according to the type of the child element identified by it (unique per the conditions given above).

4.1.2 XML Representation of the wrpc:signature Extension

The XML representation for the RPC signature extension is an attribute information item with the following Infoset properties:

• A [local name] of signature

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/rpc"

The type of the name attribute information item is a list type whose item type is the union of the xs:QName type and the subtype of the xs:token type restricted to the following four values: "#in", "#out", "#inout", "#return". See Example 4-1 for a definition of this type.

Additionally, each even-numbered item (0, 2, 4, ...) in the list MUST be of type xs:QName and each odd-numbered item (1, 3, 5, ...) in the list MUST be of the subtype of xs:token described in the previous paragraph.

<xs:attribute name="signature" type="wrpc:signatureType"/>

<xs:simpleType name="signatureType">
  <xs:list itemType="wrpc:signatureItemType"/>
</xs:simpleType>

<xs:simpleType name="signatureItemType">
  <xs:union memberTypes="wrpc:directionToken xs:QName"/>
</xs:simpleType>

<xs:simpleType name="directionToken">
  <xs:restriction base="xs:token">
    <xs:enumeration value="#in"/>
    <xs:enumeration value="#out"/>
    <xs:enumeration value="#inout"/>
    <xs:enumeration value="#return"/>
  </xs:restriction>
</xs:simpleType>
          
           

4.1.3 wrpc:signature Extension Mapping To Properties of an Interface Operation component

A wrpc:signature extension attribute information item is mapped to the following property of the Interface Operation component defined by its [owner].

5.4.1 Description

Every SOAP binding MUST indicate what version of SOAP is in use for the operations of the interface that this binding applies to.

By default, SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework] is used.

5.4.2 Relationship to WSDL Component Model

The SOAP protocol specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap version} REQUIRED. A xs:string, to the Binding component.

5.4.3 XML Representation

<description>
  <binding  name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
            wsoap:version="xs:string"? >
    ...
  </binding>
</description>

The XML representation for specifying the SOAP version is an optional attribute information item with the following Infoset properties:

• A [local name] of version

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

• A type of xs:string

5.4.4 Mapping from XML Representation to Component properties

See Table 5-1.

5.5.1 Description

Every SOAP binding MUST indicate what underlying protocol is in use.

5.5.2 Relationship to WSDL Component Model

The SOAP protocol specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap underlying protocol} REQUIRED. A xs:anyURI, which is an absolute IRI as defined by [IETF RFC 3987], to the Binding component.

5.5.3 XML Representation

<description>
  <binding  name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
            wsoap:protocol="xs:anyURI" >
    ...
  </binding>
</description>

The XML representation for specifying the SOAP protocol is a REQUIRED attribute information item with the following Infoset properties:

• A [local name] of protocol

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

• A type of xs:anyURI

5.5.4 Mapping from XML Representation to Component Properties

See Table 5-2.

5.6.1 Description

Every Binding Operation component of a SOAP binding MUST indicate the SOAP Message Exchange Pattern (MEP) to be used for that operation. This binding extension specification allows the user to indicate a default SOAP MEP to be used for all Binding Operation components of this Binding component.

5.6.2 Relationship to WSDL Component Model

The default SOAP MEP specification is a syntactic convenience and does not affect the underlying component model.

5.6.3 XML Representation

<description>
  <binding  name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
            wsoap:protocol="xs:anyURI"
            wsoap:mepDefault="xs:anyURI ?" >
    ...
  </binding>
</description>

The XML representation for specifying the default SOAP MEP is an OPTIONAL attribute information item with the following Infoset properties:

• A [local name] of mepDefault

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

• A type of xs:anyURI

5.7.1 Description

For every Interface Fault component contained in an Interface component, a mapping to a SOAP Fault must be described. This binding extension specification allows the user to indicate the SOAP fault code and subcodes that are transmitted for a given Interface Fault component.

5.7.2 Relationship to WSDL Component Model

The SOAP Fault binding extension adds the following properties to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap fault code} OPTIONAL. A xs:QName, to the Binding Fault component. The value of this property identifies a possible SOAP fault for the operations in scope. If this property is empty, no assertion is made about the value of the SOAP fault code.

• {soap fault subcodes} OPTIONAL. A list of xs:QName, to the Binding Fault component. The value of this property identifies one or more subcodes for this SOAP fault.

5.7.3 XML Representation

<description>
  <binding >
    <fault ref="xs:QName"
           wsoap:code="union of xs:QName, xs:token"?
           wsoap:subcodes="list of xs:QName"? >
      <documentation />*
      [ <feature /> | <property /> ]*
    </fault>*
  </binding>
</description>

The XML representation for binding a SOAP Fault are two attribute information items with the following Infoset properties:

• wsoap:code OPTIONAL attribute information item

  • A [local name] of code

  • A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

  • A type of union of xs:QName and xs:token where the allowed token value is "#any"

• wsoap:subcodes OPTIONAL attribute information item

  • A [local name] of subcodes

  • A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

  • A type of list of xs:QNames

5.7.4 Mapping XML Representation to Component Properties

See Table 5-3.

5.8.1 Description

For every Interface Operation component contained in an Interface component, in addition to the default binding rules (for SOAP 1.2, see 5.11.3 Default Binding Rules), there may be additional binding information to be specified. This binding extension specification allows the user to indicate the SOAP Message Exchange Pattern (MEP) and a value for the SOAP Action Feature on a per-operation basis.

5.8.2 Relationship to WSDL Component Model

The SOAP Operation binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap mep} REQUIRED. A xs:anyURI, which is an absolute IRI as defined by [IETF RFC 3987], to the Binding Operation component. The value of this property identifies the SOAP Message Exchange Pattern (MEP) for this specific operation. If no specific value is assigned, then the value assigned by the default rules apply (for SOAP 1.2, see 5.11.3 Default Binding Rules). It is an error for this property to not have a value (which MAY happen if the default rules are not applicable).

• {soap action} OPTIONAL. A xs:anyURI, which is an absolute IRI as defined by [IETF RFC 3987], to the Binding Operation component. The value of this property identifies the value of the SOAP Action Feature (as defined for this specific operation), as specified in the binding rules of bindings to specific versions of SOAP (see 5.11.3 Default Binding Rules for the SOAP 1.2 binding when the value of the {soap version} property of the Binding component is "1.2").

5.8.3 XML Representation

<description>
  <binding >
    <operation ref="xs:QName" 
               wsoap:mep="xs:anyURI"?
               wsoap:action="xs:anyURI"? >
    </operation>
  </binding>
</description>

The XML representation for binding an Operation are two attribute information items with the following Infoset properties:

• wsoap:mep OPTIONAL attribute information item

  • A [local name] of mep

  • A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

  • A type of xs:anyURI

• wsoap:action OPTIONAL attribute information item

  • A [local name] of action

  • A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

  • A type of xs:anyURI

5.8.4 Mapping from XML Representation to Component Properties

See Table 5-4.

5.9.1 Description

In SOAP, it is permissible for specification interaction to engage one or more additional features (typically implemented as one or more SOAP header blocks), as defined by SOAP Modules (see [SOAP 1.2 Part 1: Messaging Framework]). This binding extension specification allows users to indicate which SOAP Modules are in use across an entire binding, on a per operation basis or on a per message basis.

5.9.2 Relationship to WSDL Component Model

The SOAP Module component adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap modules} OPTIONAL. A set of SOAP Module components as defined in 5.9.3 SOAP Module component, to the Binding, Binding Operation, Binding Message Reference, Binding Fault and Binding Fault Reference components.

The SOAP modules applicable for a particular operation of any service consists of all modules specified in the input or output Binding Message Reference components, the infault or outfault Binding Fault Reference components, those specified within the Binding Fault components, those specified within the Binding Operation components and those specified within the Binding component. If any module is declared in multiple components, then the requiredness of that module is defined by the closest declaration, where closeness is defined by whether it is specified directly at the Binding Message Reference component or Binding Fault Reference component level, the Binding Fault level or the Binding Operation component level or the Binding component level, respectively.

5.9.3 SOAP Module component

The SOAP Module component identifies a SOAP module that is in use.

The properties of the SOAP Module component are as follows:

• {ref} REQUIRED. A xs:anyURI, which is an absolute IRI as defined by [IETF RFC 3987]. The value of this property identifies the specific SOAP module that is in use.

• {required} REQUIRED. A xs:boolean indicating if the SOAP module is required.

5.9.4 XML Representation

<description>
  <binding >
    <wsoap:module ref="anyURI"
                  required="boolean"? >
      <documentation ... />*
    </wsoap:module>
    <fault>
      <wsoap:module ... />*
    </fault>
    <operation>
      <wsoap:module ... />*
      <input>
        <wsoap:module ... />*
      </input>
      <output>
        <wsoap:module ... />*
      </output>
      <infault>
        <wsoap:module ... />*
      </infault>
      <outfault>
        <wsoap:module ... />*
      </outfault>
    </operation>
  </binding>
</description>

The XML representation for a SOAP Module component is an element information item with the following Infoset properties:

• A [local name] of module

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

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

  • A REQUIRED ref attribute information item with the following Infoset properties:

    • A [local name] of ref

    • A [namespace name] which has no value

    • A type of xs:anyURI

  • An OPTIONAL required attribute information item with the following Infoset properties:

    • A [local name] of required

    • A [namespace name] which has no value

    • A type of xs:boolean

  • Zero or more namespace qualified attribute information items. The [namespace name] of such attribute information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/soap".

• Zero or more element information item amongst its [children], in order, as follows:

  1. Zero or more documentation element information items as defined in [WSDL 2.0 Core Language].

  2. Zero or more namespace-qualified element information items amongst its [children]. The [namespace name] of such element information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/soap".

5.9.5 Mapping from XML Representation to Component Properties

See Table 5-5.

5.9.6 IRI Identification Of A SOAP Module component

WSDL Version 2.0 Part 1: Core Language [WSDL 2.0 Core Language] defines a fragment identifier syntax for identifying components of a WSDL 2.0 document.

A SOAP Module component can be identified using the wsdl.extension XPointer Framework scheme:

wsdl.extension(http://www.w3.org/2005/08/wsdl/soap, wsoap.module(parent/ref))

1. parent is the component identifier for the component under which the SOAP Module component is declared, as specified in WSDL Version 2.0 Part 1: Core Language.

2. ref is the value of the {ref} property of the component.

5.10.1 Description

SOAP allows the use of header blocks in the header part of the message. This binding extension allows users to declare the SOAP header blocks in use on a per message ond on a per fault basis.

5.10.2 Relationship to WSDL Component Model

The SOAP Header Blocks binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {soap headers} OPTIONAL. A set of SOAP Header Block components as defined in 5.10.3 SOAP Header Block component, to the Binding Fault and Binding Message Reference components.

5.10.3 SOAP Header Block component

A SOAP Header Block component describes an abstract piece of header data (message headers) that is associated with the exchange of messages between the communicating parties. The presence of a SOAP Header Block component in a WSDL description indicates that the service supports headers and MAY require a Web service consumer/client that interacts with the service to use the described header. Zero or more such headers may be used.

The properties of the SOAP Header Block component are as follows:

• {element} REQUIRED. A xs:QName, a reference to an XML element declaration in the {element declarations} property of the Description component. This element represents a SOAP header block.

• {mustUnderstand} REQUIRED. A xs:boolean. When its value is "true", the SOAP header block MUST be decorated with a SOAP mustUnderstand attribute information item with a value of "true"; if so, it is an error for the XML element declaration referenced by the {element} property not to allow this SOAP mustUnderstand attribute information item. Otherwise, no additional constraint is placed on the presence and value of a SOAP mustUnderstand attribute information item.

5.10.4 XML Representation

<description>
  <binding name="xs:NCName" type="http://www.w3.org/2005/08/wsdl/soap" >
    <fault ref="xs:QName" >
      <wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?>
        <documentation />*
      </wsoap:header>*
      ...
    </fault>*
    <operation ref="xs:QName" >
      <input messageLabel="xs:NCName"?>
        <wsoap:header ... />*
        ...
      </input>*
      <output messageLabel="xs:NCName"?>
        <wsoap:header ... />*
        ...
      </output>*
    </operation>*
  </binding>
</description>

The XML representation for a SOAP Header Block component is an element information item with the following Infoset properties:

• A [local name] of header

• A [namespace name] of "http://www.w3.org/2005/08/wsdl/soap"

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

  • A REQUIRED element attribute information item with the following Infoset properties:

    • A [local name] of element

    • A [namespace name] which has no value

    • A type of xs:QName

  • An OPTIONAL mustUnderstand attribute information item with the following Infoset properties:

    • A [local name] of mustUnderstand

    • A [namespace name] which has no value

    • A type of xs:boolean

  • Zero or more namespace qualified attribute information items. The [namespace name] of such attribute information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/soap".

• Zero or more element information item amongst its [children], in order, as follows:

  1. Zero or more documentation element information items as defined in [WSDL 2.0 Core Language].

  2. Zero or more namespace-qualified element information items amongst its [children]. The [namespace name] of such element information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/soap".

5.10.5 Mapping XML Representation to Component Properties

See Table 5-6.

5.10.6 IRI Identification Of A SOAP Header Block component

WSDL Version 2.0 Part 1: Core Language [WSDL 2.0 Core Language] defines a fragment identifier syntax for identifying components of a WSDL 2.0 document.

A SOAP Header Block component can be identified using the wsdl.extension XPointer Framework scheme:

wsdl.extension(http://www.w3.org/2005/08/wsdl/soap, wsoap.header(parent/namespace#name))

1. parent is the component identifier for the component under which the SOAP Header Block component is declared, as specified in WSDL Version 2.0 Part 1: Core Language.

2. namespace is the {element} property value's namespace URI.

3. name is the {element} property value's local name.

5.11.1 Identifying a WSDL SOAP 1.2 Binding

A WSDL SOAP Binding is identified as a SOAP 1.2 binding by assigning the value "1.2" to the {soap version} property of the Binding component.

5.11.2 Description

The WSDL SOAP 1.2 binding extension defined in this section is an extension of the 5. WSDL SOAP Binding Extension to enable Web Service applications to use SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework].

The WSDL SOAP 1.2 binding extension supports the SOAP 1.2 HTTP binding defined by the [SOAP 1.2 Part 2: Adjuncts] specification. This is indicated by assigning the URI "http://www.w3.org/2003/05/soap/bindings/HTTP/" (as defined by [SOAP 1.2 Part 2: Adjuncts]) to the {soap underlying protocol} property. Other values MAY be used for this property in conjunction with the SOAP 1.2 binding extension defined by this specification provided that the semantics of such protocols are consistent with this binding extension.

Default rules in section 5.11.3 Default Binding Rules define the relationship between SOAP message exchange patterns defined in [SOAP 1.2 Part 2: Adjuncts] and WSDL message exchange patterns defined in 2. Predefined Message Exchange Patterns.

When the SOAP Message Exchange Pattern is the SOAP 1.2 Response MEP and the underlying protocol is HTTP, the Binding Operation may use the {http location} property defined in 6.6 Binding Operations. When such a location is specified, the Endpoint component also follows the rules for constructing the address from the {address} property and the {http location} property values.

5.11.3 Default Binding Rules

These default binding rules are applicable to SOAP 1.2 bindings.

• SOAP Action Feature. If a value for the {soap action} property of a Binding Operation component has NOT been specified then the SOAP Action Feature (see [SOAP 1.2 Part 2: Adjuncts]) has NO value assigned by the Binding component. Otherwise, the value of the {soap action} property of a Binding Operation component is the value of the SOAP Action Feature for all messages of the corresponding Interface Operation component.

• SOAP MEP Selection. If the Interface Operation component's {message exchange pattern} property has the value "http://www.w3.org/2005/08/wsdl/in-out", then the default value of the {soap mep} property for the corresponding Binding Operation component is "http://www.w3.org/2003/05/soap/mep/request-response/" identifying the SOAP Request-Response Message Exchange Pattern as defined in [SOAP 1.2 Part 2: Adjuncts]. If the Interface Operation component has any other value for the {message exchange pattern} property, then no default value is defined for the {soap mep} property of the corresponding Binding Operation component.

  Editorial note: One-way MEP defaulting
  The Web Services Description Working Group would like to add a rule here defaulting to a standardized SOAP 1.2 one-way MEP for one-way operations if one becomes available. Feedback is sought on this topic.

• HTTP Method Selection. This default binding rule is applicable when the value of the {soap underlying protocol} property of the Binding component is "http://www.w3.org/2003/05/soap/bindings/HTTP/". If the {soap mep} property of the Binding Operation component has the value "http://www.w3.org/2003/05/soap/mep/request-response/" then the default value of the {http method} property is "POST". If the {soap mep} property of the Binding Operation component has the value "http://www.w3.org/2003/05/soap/mep/soap-response/" then the default value of the {http method} property is "GET".

• HTTP IRI Generation. This default binding rule is applicable when the value of the {soap underlying protocol} property of the Binding component is "http://www.w3.org/2003/05/soap/bindings/HTTP/". If the {soap mep} property of the Binding Operation component has the value "http://www.w3.org/2003/05/soap/mep/soap-response/" then the IRI to execute the HTTP GET against MUST be generated using the HTTP binding extension's rules for generating a IRI for HTTP GET (see 6.9.1 Serialization as application/x-www-form-urlencoded ). The input serialization format of x-www-form-urlencoded is the only supported serialization format for HTTP GET in the SOAP Response Message Exchange Pattern.

  Editorial note: Input serialization for HTTP GET in SOAP HTTP binding

  Use of a different input serialization format requires introduction of either a new MEP or a new binding. The Working Group considered the limitations of the x-www-form-urlencoded serialization format (see points #2 and #3 of Binding message content to IRI analysis). It decided that the limitations of the serialization format, which could potentially be solved by a serialization format extension, were not sufficiently broad enough to warrant allowing extensibility in input serialization for the soap-response MEP. The Working Group solicits the public's feedback on this decision.

6.4.1 Description

Every Binding component MUST indicate what version of HTTP is in use for the operations of the interface that this binding applies to.

By default, HTTP/1.1 [IETF RFC 2616] is used.

6.4.2 Relationship to WSDL Component Model

The HTTP binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http version} REQUIRED. A xs:string to the Binding component. The value of this property follows the "<major>.<minor>" numbering scheme defined in section 3.1 of Hypertext Transfer Protocol -- HTTP/1.1 [IETF RFC 2616].

6.4.3 XML Representation

<description>
  <binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
           whttp:version="xs:string"? >
  </binding>
</description>

The XML representation for specifying the HTTP version is an optional attribute information item with the following Infoset properties:

• A [local name] of version

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

• A type of xs:string whose pattern facet is "[0-9]+\.[0-9]+".

6.4.4 Mapping from XML Representation to Component Properties

See Table 6-2.

6.5.1 Description

Every Binding Operation component MUST indicate what HTTP method is in use for the operations of the interface that this binding applies to. This binding extension specification allows the user to indicate a default HTTP method to be used for all Binding Operation components of this Binding component.

6.5.2 Relationship to WSDL Component Model

The default HTTP method specification is a syntactic convenience and does not affect the underlying component model.

6.5.3 XML Representation

<description>
  <binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
           whttp:methodDefault="xs:string"? >
  </binding>
</description>

The XML representation for specifying the default HTTP method is an optional attribute information item with the following Infoset properties:

• A [local name] of methodDefault

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

• A type of xs:string

The methodDefault attribute information item does NOT have a default value.

6.6.1 Description

This binding extension specification provides a binding to HTTP of Interface Operation components whose {message exchange pattern} property has the value "http://www.w3.org/2005/08/wsdl/in-only", "http://www.w3.org/2005/08/wsdl/robust-in-only" or "http://www.w3.org/2005/08/wsdl/in-out". This HTTP binding extension MAY be used with other message exchange patterns such as outbound message exchange patterns, provided that additional semantics are defined, such as with an extension or with a Feature.

Each of the supported message exchange patterns involves one to two messages or faults being exchanged. The first is transmitted using an HTTP request, and the second is transmitted using the corresponding HTTP response. In cases where only one message is being sent, the message body of the HTTP response MUST be empty.

For every Binding Operation component corresponding to such Interface Operation components, this binding extension specification allows the user to indicate the HTTP method to use, the input, output and fault serialization, and the location of the bound operation.

6.6.2 Relationship to WSDL Component Model

The HTTP binding extension adds the following property to the Binding Operation component of the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http location} OPTIONAL. A xs:anyURI. This IRI is combined with the base IRI specified in the {address} property of the Endpoint component to form the full IRI for the HTTP request to invoke the operation. It MUST contain an absolute or a relative IRI, i.e. it MUST NOT include a fragment identifier in the IRI. Input serializations may define additional processing rules to be applied to the value of {http location} before combining it with the {address} property of the endpoint element to form the HTTP request IRI. For example, the application/x-www-form-urlencoded serialization defined in section 6.9.1 Serialization as application/x-www-form-urlencoded defines a syntax to use the {http location} as a template using elements of the instance data.

  If the resulting IRI uses the https scheme, then HTTP over TLS [IETF RFC 2818] is used to send the HTTP request.

• {http method} REQUIRED. A xs:string indicating the value for the HTTP Request Method for this specific operation.

• {http input serialization} REQUIRED. A xs:string indicating the value for the serialization of the HTTP Request message for this specific operation. Its value MUST be the name of a IANA media type token.

• {http output serialization} REQUIRED. A xs:string indicating the value for the serialization of the HTTP Response message for this specific operation. Its value MUST be the name of a IANA media type token.

• {http fault serialization} REQUIRED. A xs:string indicating the value for the serialization of the HTTP Response message for this specific operation in case a fault is returned. Its value MUST be the name of a IANA media type token.

• {http query parameter separator} REQUIRED. A xs:string indicating the query parameter separator character.

6.6.3 XML Representation

<description>
 <binding  whttp:queryParameterSeparatorDefault="xs:string"? >
   <operation ref="xs:QName" 
              whttp:location="xs:anyURI"?
              whttp:method="xs:string"? 
              whttp:inputSerialization="xs:string"? 
              whttp:outputSerialization="xs:string"? 
              whttp:faultSerialization="xs:string"?
              whttp:queryParameterSeparator="xs:string"? >
  </operation>
 </binding>
</description>
          

The XML representation for binding an Operation are four attribute information items with the following Infoset properties:

• An OPTIONAL location attribute information item with the following Infoset properties:

  • A [local name] of location

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

  • A type of xs:anyURI

• An OPTIONAL method attribute information item with the following Infoset properties:

  • A [local name] of method

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

  • A type of xs:string

• An OPTIONAL inputSerialization attribute information item with the following Infoset properties:

  • A [local name] of inputSerialization

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

  • A type of xs:string

• An OPTIONAL outputSerialization attribute information item with the following Infoset properties:

  • A [local name] of outputSerialization

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

  • A type of xs:string

• An OPTIONAL faultSerialization attribute information item with the following Infoset properties:

  • A [local name] of faultSerialization

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

  • A type of xs:string

• An OPTIONAL queryParameterSeparatorDefault attribute information item with the following Infoset properties:

  • A [local name] of queryParameterSeparatorDefault

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

  • A type of xs:string whose length facet value is "1"

6.6.4 Mapping from XML Representation to Component Properties

See Table 6-3.

6.7.1 Description

HTTP allows the use of headers in messages. This binding extension allows users to declare the HTTP headers in use on a per message ond on a per fault basis.

6.7.2 Relationship to WSDL Component Model

The HTTP Header binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http headers}, OPTIONAL. A set of HTTP Header components as defined in 6.7.3 HTTP Header component, to the Binding Fault and Binding Message Reference components.

6.7.3 HTTP Header component

A HTTP Header component describes an abstract piece of header data (message headers) that is associated with the exchange of messages between the communicating parties. The presence of a HTTP Header component in a WSDL description indicates that the service supports headers and MAY require a Web service consumer/client that interacts with the service to use the described header. Zero or more such headers may be used.

The properties of the HTTP Header component are as follows:

• {element}, REQUIRED. A xs:QName, a reference to an XML element declaration in the {element declarations} property of the Description component. This element represents a HTTP header.

6.7.4 XML Representation

<description>
  <binding name="xs:NCName" type="http://www.w3.org/2005/08/wsdl/http" >
    <fault ref="xs:QName">
      <whttp:header element="xs:QName">
        <documentation />*
      </whttp:header>*
      ...
    </fault>*
    <operation ref="xs:QName" >
      <input messageLabel="xs:NCName"?>
        <whttp:header ... />*
        ...
      </input>*
      <output messageLabel="xs:NCName"?>
        <whttp:header ... />*
        ...
      </output>*
    </operation>*
  </binding>
</description>

The XML representation for a HTTP Header component is an element information item with the following Infoset properties:

• A [local name] of header

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

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

  • A REQUIRED element attribute information item with the following Infoset properties:

    • A [local name] of element

    • A [namespace name] which has no value

    • A type of xs:QName

  • Zero or more namespace qualified attribute information items. The [namespace name] of such attribute information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/http".

• Zero or more element information item amongst its [children], in order, as follows:

  1. Zero or more documentation element information items as defined in [WSDL 2.0 Core Language].

  2. Zero or more namespace-qualified element information items amongst its [children]. The [namespace name] of such element information items MUST NOT be "http://www.w3.org/2005/08/wsdl" and MUST NOT be "http://www.w3.org/2005/08/wsdl/http".

6.7.5 Mapping from XML Representation to Component Properties

See Table 6-4.

6.7.6 IRI Identification Of A HTTP Header component

WSDL Version 2.0 Part 1: Core Language [WSDL 2.0 Core Language] defines a fragment identifier syntax for identifying components of a WSDL 2.0 document.

An HTTP Header component can be identified using the wsdl.extension XPointer Framework scheme:

wsdl.extension(http://www.w3.org/2005/08/wsdl/http, whttp.header(parent/namespace#name))

1. parent is the component identifier for the component under which the HTTP Header component is declared, as specified in WSDL Version 2.0 Part 1: Core Language.

2. namespace is the {element} property value's namespace URI.

3. name is the {element} property value's local name.

6.8.1 Description

For every Interface Fault component contained in an Interface component, an HTTP error code and error reason MAY be defined. They represents the error code and reason phrase that will be used by the service in case the fault needs to be returned.

The fault definition SHOULD NOT go against the definition of the HTTP error codes, as specified in section 8 of [IETF RFC 3205].

6.8.2 Relationship to WSDL Component Model

The HTTP Fault binding extension adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http error status code}, OPTIONAL. A xs:int representing an error Status-Code as defined by [IETF RFC 2616], to the Binding Fault component. The value of this property identifies the error code that the service will use in case the fault is returned. If empty, no claim is made by the service.

• {http error reason phrase}, OPTIONAL. A xs:string representing an error Reason-Phrase as defined by [IETF RFC 2616], to the Binding Fault component. The value of this property identifies the Reason-Phrase that the service will use in case the fault is returned. If empty, no claim is made by the service.

6.8.3 XML Representation

<description>
  <binding >
    <fault ref="xs:QName"
           whttp:code="union of xs:int, xs:token"?
           whttp:reasonPhrase="xs:string"? />
    </fault>*
  </binding>
</description>

The XML representation for binding an HTTP Fault are two attribute information items with the following Infoset properties:

• a code OPTIONAL attribute information item

  • A [local name] of code

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

  • A type of union of xs:int and xs:token where the allowed token value is "#any"

• a reasonPhrase OPTIONAL attribute information item

  • A [local name] of reasonPhrase

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

  • A type of xs:string

6.8.4 Mapping from XML Representation to Component Properties

See Table 6-5.

6.9.1 Serialization as "application/x-www-form-urlencoded"

This serialization format is designed to allow a Web service to produce a IRI based on the instance data of input messages. It may only be used for interface operation using the IRI Style format as defined in 4.2 IRI Style. Because the IRI Style constrains the instance data not to contain multiple children elements declared with the same local name, elements can be serialized in the request IRI with their local names unambiguously.

Elements from the instance data can be inserted into the path of the request IRI, or a query parameter, as shown in the example below:

<data>
  <town>Fréjus</town>
  <date>2004-01-16</date>
  <unit>C</unit>
</data>

<operation ref='t:data'
    whttp:location='temperature/{town}'
    whttp:method='GET' />

<endpoint name='e' binding='t:b'
    address='http://ws.example.com/service1/' />

http://ws.example.com/service1/temperature/Fr%C3%A9jus?date=2004-01-16&unit=C

In this serialization, the value of the {http location} property is used as a template which is combined with the {address} property of the endpoint element to form the full IRI to be used in an HTTP request, as specified in section 6.6.2 Relationship to WSDL Component Model.

This IRI MUST be mapped to an URI for use in the HTTP Request as per section 3.1 "Mapping of IRIs to URIs" of the IRI specification [IETF RFC 3987].

<data>
  <town>Fréjus</town>
  <date>2004-01-16</date>
  <unit>C</unit>
  <value>24</value>
</data>

<operation ref='t:data'
    whttp:inputSerialization='application/x-www-form-urlencoded'
    whttp:location='temperature/{town/}'
    whttp:method='POST' />

<endpoint name='e' binding='t:b'
    address='http://ws.example.com/service1/' />

http://ws.example.com/service1/temperature/Fréjus

http://ws.example.com/service1/temperature/Fr%C3%A9jus

Content-Type: application/xml
Content-Length: xxx

<data>
  <town>Fréjus</town>
  <date>2004-01-16</date>
  <unit>C</unit>
  <value>24</value>
</data>

6.9.2 Serialization as "application/xml"

The instance data of the input, output or fault message is serialized as an XML document in the message body of the HTTP request, following the serialization defined in [Canonical XML].

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.

6.9.3 Serialization as "multipart/form-data"

This format is for legacy compatibility to permit the use of XForms clients with [IETF RFC 2388] servers. This serialization format may only be used for interface operations using the Multipart Style format as defined in 4.3 Multipart style.

Each element in the sequence is serialized into a part as follow:

1. The Content-Disposition header MUST have the value form-data, and its name parameter is the local name of the element.

2. 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.

3. 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 6.9.2 Serialization as application/xml .

It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".

<data>
  <town>
    <name>Fréjus</name>
    <country>France</country>
  </town>
  <date>2004-01-16</date>
</data>

<operation ref='t:data'
    whttp:location='temperature'
    whttp:method='POST'
    whttp:inputSerialization='multipart/form-data'/>

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

6.10.1 Description

Every Binding Message Reference and Interface Fault Reference component MAY indicate which transfer codings, as defined in section 3.6 of [IETF RFC 2616], are available for this particular message.

The HTTP binding extension 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.

6.10.2 Relationship to WSDL Component Model

The HTTP binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http transfer coding}, OPTIONAL. A xs:string to the Binding Message Reference and Binding Fault Reference components. This property indicates the transfer codings available for a particular message. Its value is ignored when the value of the {http version} property is "1.0".

6.10.3 XML Representation

<description>
  <binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
           whttp:transferCodingDefault="xs:string"? >
    <operation location="xs:anyURI"?
               whttp:transferCodingDefault="xs:string" ? >
      <input messageLabel="xs:NCName"? 
             whttp:transferCoding="xs:string"? />

      <output messageLabel="xs:NCName"?
              whttp:transferCoding="xs:string"? />

      <infault ref="xs:QName" messageLabel="xs:NCName"? 
             whttp:transferCoding="xs:string"? />

      <outfault ref="xs:QName" messageLabel="xs:NCName"? 
             whttp:transferCoding="xs:string"? />
    </operation>
  </binding>
</description>

The XML representation for specifying the default transfer coding is an OPTIONAL attribute information item for the binding element information item or binding 's child operation element information items with the following Infoset properties:

• A [local name] of defaultTransferCoding

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

• A type of xs:string

The XML representation for specifying the transfer coding is an OPTIONAL attribute information item with the following Infoset properties:

• A [local name] of transferCoding

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

• A type of xs:string

6.10.4 Mapping from XML Representation to Component Properties

See Table 6-6.

6.11.1 Description

Every Binding component MAY indicate whether HTTP cookies (as defined by [IETF RFC 2965]) are used for some or all of operations of the interface that this binding applies to.

6.11.2 Relationship to WSDL Component Model

The HTTP binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http cookies} REQUIRED. A xs:boolean to the Binding component.

6.11.3 XML Representation

<description>
  <binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
           whttp:cookies="xs:boolean"? >
  </binding>
</description>

The XML representation for specifying the use of HTTP cookies is an OPTIONAL attribute information item with the following Infoset properties:

• A [local name] of cookies

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

• A type of xs:boolean

6.11.4 Mapping from XML Representation to Component Properties

See Table 6-7.

6.12.1 Description

Every Endpoint component MAY indicate the use of an HTTP access authentication mechanism (as defined by [IETF RFC 2616]) for the endpoint described.

This binding extension specification allows the authentication scheme and realm to be specified.

6.12.2 Relationship to WSDL Component Model

The HTTP binding extension specification adds the following property to the WSDL component model (as defined in [WSDL 2.0 Core Language]):

• {http authentication scheme} REQUIRED. xs:string to the Endpoint component, corresponding to the HTTP authentication scheme used. The valid values are "basic" for the "basic" authentication scheme defined in [IETF RFC 2617], "digest" for the Digest Access Authentication scheme as defined in [IETF RFC 2617], and "none" for no access authentication.

• {http authentication realm} REQUIRED. A xs:string to the Endpoint. It corresponds to the realm authentication parameter defined in [IETF RFC 2617]. If the value of the {http authentication scheme} property is not "none", it MUST not be empty.

6.12.3 XML Representation

<description>
  <service>
    <endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"? >
              whttp:authenticationType="xs:string"? 
              whttp:authenticationRealm="xs:string"? />
    </endpoint>
  </service>
</description>

The XML representation for specifying the use of HTTP access authentication is two OPTIONAL attribute information items with the following Infoset properties:

• An OPTIONAL authenticationType attribute information item with the following Infoset properties:

  • A [local name] of authenticationType

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

  • A type of xs:string

• An OPTIONAL authenticationRealm attribute information item with the following Infoset properties:

  • A [local name] of authenticationRealm

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

  • A type of xs:string

6.12.4 Mapping from XML Representation to Component Properties

See Table 6-8.