2007-03-26 diff-marked version: Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts

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

All parts of this specification are normative, with the EXCEPTION of pseudo-schemas, examples, and sections explicitly marked as "Non-Normative". Pseudo-schemas are provided for each component, before the description of this component. They provide visual help for the XML [XML 1.0] serialization. The syntax of BNF pseudo-schemas is the same as the one used in [WSDL 2.0 Core Language].

1.2 Assertions

Assertions about WSDL 2.0 documents and components that are not enforced by the normative XML schema for WSDL 2.0 are marked by a dagger symbol (†) at the end of a sentence. Each assertion has been assigned a unique identifier that consists of a descriptive textual prefix and a unique numeric suffix. The numeric suffixes are assigned sequentially and never reused so there may be gaps in the sequence. The assertion identifiers MAY be used by implementations of this specification for any purpose, e.g. error reporting.

The assertions and their identifiers are summarized in section C. Assertion Summary.

2.1 Template for Message Exchange Patterns

New message exchange patterns may be defined by any organization able and willing to do so. It is recommended that the patterns use the general template provided in 2.1.1 Pattern Name, after examination of existing predefined patterns.

2.2 Fault Propagation Rules

WSDL patterns specify their fault propagation model using standard rulesets to indicate where faults can occur. The most common patterns for fault propagation are defined in the following subsections, and referenced by the patterns in 2.3 Message Exchange Patterns. "Propagation" is defined as a best-effort attempt to transmit the fault message to its designated recipient.

WSDL patterns specify propagation of faults, not their generation. Nodes that generate faults MUST attempt to propagate the faults in accordance with the governing ruleset, but it is understood that any delivery of a network message is best effort, not guaranteed.^†The rulesets establish the direction of the fault message and the fault recipient; they do not provide reliability or other delivery guarantees. When a fault is generated, the generating node MUST attempt to propagate the fault, and MUST do so in the direction and to the recipient specified by the ruleset.^† However, extensions or binding extensions MAY modify these rulesets.^† For example, WS-Addressing [WSA 1.0 Core] defines a "FaultTo" address for messages, which is used in lieu of the recipient nominated by the ruleset.

Generation of a fault, regardless of ruleset, terminates the exchange.^†

Binding extensions, features, or extension specifications can override the semantics of a fault propagation ruleset, but this practice is strongly discouraged.

2.3 Message Exchange Patterns

WSDL patterns are described in terms of the WSDL component model, specifically the Interface Message Reference and Interface Fault Reference components.

This pattern consists of one or two messages, in order, as follows:†A message:indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"received from some node NAn optional message:indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"sent to node NThis 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/2006/01/wsdl/in-opt-out".2.3.5 Out-OnlyThis pattern consists of exactly one message as follows:†A message:indicated by a Interface Message Reference component whose {message label} is "Out " and {direction} is "out"sent to some node NThis 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/2006/01/wsdl/out-only".2.3.6 Robust Out-OnlyThis pattern consists of exactly one message as follows:†message:indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"sent to some node NThis 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/2006/01/wsdl/robust-out-only".2.3.7 Out-InThis pattern consists of exactly two messages, in order, as follows:†A message:indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"sent to some node NA message:indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"sent from node NThis 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/2006/01/wsdl/out-in".2.3.8 Out-Optional-InThis pattern consists of one or two messages, in order, as follows:†A message:indicated by a Interface Message Reference component whose {message label} is "Out" and {direction} is "out"sent to some node NAn optional message:indicated by a Interface Message Reference component whose {message label} is "In" and {direction} is "in"sent from node NThis 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/2006/01/wsdl/out-opt-in".2.4 Security Considerations

Note that many of the message exchange patterns defined above describe responses to an initial message (either a normal response message or a fault.)

Such responses can be used in attempts to disrupt, attack, or map a network, host, or services. When such responses are directed to an address other than that originating the initial message, the source of an attack can be obscured, or blame laid on a third party, or denial-of-service attacks can be enabled or exacerbated.

Security mechanisms addressing such attacks can prevent the delivery of response messages to the receiving node. Conformance to the message exchange pattern is measured prior to the application of these security mechanisms.

3.1 Operation safety

This section defines an extension to WSDL 2.0 [WSDL 2.0 Core Language] that allows marking an operation as a safe interaction, as defined in section 3.4. Safe Interactions of [Web Architecture].

This extension MAY be used for setting defaults in bindings, such as in the HTTP binding (see 6.5.5 Mapping from XML Representation to Component Properties).

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

4.1 RPC Style

The RPC style is selected by assigning to an Interface Operation component's {The RPC style is selected by including the value "http://www.w3.org/ns/wsdl/style/rpc" in the {style} property of an Interface Operation component.

An Interface Operation component conforming to the RPC style MUST obey the constraints listed further below. Furthermore, if the wrpc:signature extension is engaged simulatenously, the corresponding attribute information item MUST be valid according to the schema for the extension and additionally MUST obey the constraints listed in 4.1.1 wrpc:signature Extension and 4.1.2 XML Representation of the wrpc:signature Extension.

If the RPC style is used by an Interface Operation component then its {message exchange pattern} property MUST have the value either "http://www.w3.org/ns/wsdl/in-only" or "http://www.w3.org/ns/wsdl/in-out".^†

The RPC style places restrictions for Remote Procedure Call-types of interactions. When this value is used, the associated messages MUST conform to the rules below, described using XML Schema [XML Schema Structures]. Note that operations containing messages described by other type systems may also indicate use of the RPC style, as long as they are constructed in such a way as to follow these rules.

If the Interface Operation component uses a {message exchange pattern} for which there is no output element, i.e. "http://www.w3.org/ns/wsdl/in-only", then the conditions stated below that refer to output elements MUST be considered to be implicitly satisfied.

• The value of the {message content model} property for the Interface Message Reference components of the {interface message references} property MUST be "#element".^†

• The content model of input and output {element declaration} elements MUST be defined using a complex type that contains a sequence from XML Schema.^†

• The input sequence MUST only contain elements and element wildcards.^† It MUST NOT contain other structures such as xs:choice. The input sequence MUST NOT contain more than one element wildcard.^† The element wildcard, if present, MUST appear after any elements.^†

• The output sequence MUST only contain elements.^† It MUST NOT contain other structures such as xs:choice.

• Both the input and output sequences MUST contain only local element children.^† Note that these child elements MAY contain the following attributes: nillable, minOccurs and maxOccurs.

• The local name of input element's QName MUST be the same as the Interface Operation component's name.^†

• Input and output elements MUST both be in the same namespace.^†

• The complex type that defines the body of an input or an output element MUST NOT contain any local attributes.^† Extension attributes are allowed for purposes of managing the message infrastructure (e.g. adding identifiers to facilitate digitally signing the contents of the message). They must not be considered as part of the application data that is conveyed by the message. Therefore, they are never included in an RPC signature (see 4.1.1 wrpc:signature Extension).

• If elements with the same qualified name appear as children of both the input and output elements, then they MUST both be declared using the same named type.^†

• The input or output sequence MUST NOT contain multiple children elements declared with the same name.^†

<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="xs:QName wrpc:directionToken"/>
</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.2 IRI Style

The IRI style is selected by assigning the Interface Operation component's {The IRI style is selected by including the value "http://www.w3.org/ns/wsdl/style/iri" in the {style} property of an Interface Operation component.

When using this style, the value of the {message content model} property of the Interface Message Reference component corresponding to the initial message of the message exchange pattern MUST be "#element".^†

Use of this value indicates that XML Schema [XML Schema Structures] was used to define the schema of the {element declaration} property of the Interface Message Reference component of the Interface Operation component corresponding to the initial message of the message exchange pattern. This schema MUST adhere to the rules below:

• The content model of this element is 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. There are no occurence constraints on the sequence.

• The sequence MUST contain only local element children.^† Note these child elements can contain the nillable attribute.

  †

• The localPart of the element's QName MUST be the same as the Interface Operation component's {name}.^†

• The complex type that defines the body of the element or its children elements MUST NOT contain any attributes.^†

• The children elements of the sequence MUST derive from xs:simpleType, and MUST NOT be of the type or derive from xs:QName, xs:NOTATION, xs:hexBinary or xs:base64Binary.^†

4.3 Multipart style

The Multipart style is selected by assigning the Interface Operation component's {The Multipart style is selected by including the value "http://www.w3.org/ns/wsdl/style/multipart" in the {style} property of an Interface Operation component.

When using this style, the value of the {message content model} property of the Interface Message Reference component corresponding to the initial message of the message exchange pattern MUST be "#element".^†

Use of this value indicates that XML Schema [XML Schema Structures] was used to define the schema of the {element declaration} property of the Interface Message Reference component of the Interface Operation component corresponding to the initial message of the message exchange pattern. This schema MUST adhere to the rules below:

• The content model of this element is 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.^† The attributes minOccurs and maxOccurs for these child elements MUST have a value 1.^†Note these child elements can contain the nillableattribute.

• The localPart of the element's QName MUST be the same as the Interface Operation component's {name}.^†

• The complex type that defines the body of the element or its children elements MUST NOT contain any attributes.^†

• The sequence MUST NOT contain multiple children element declared with the same local name.^†

5.1 SOAP Syntax Summary (Non-Normative)

<description>
  <binding name="xs:NCName" interface="xs:QName"?
           type="http://www.w3.org/ns/wsdl/soap"
           whttp:queryParameterSeparatorDefault="xs:string"??
           whttp:contentEncodingDefault="xs:string"??
           whttp:cookies="xs:boolean"?
           wsoap:version="xs:string"?
           wsoap:protocol="xs:anyURI"
           wsoap:mepDefault="xs:anyURI"? >
    <documentation />*

    <wsoap:module ref="xs:anyURI" required="xs:boolean"? >
      <documentation />*
    </wsoap:module>*
    
    <fault ref="xs:QName"
           wsoap:code="union of xs:QName, xs:token"?
           wsoap:subcodes="union of (list of xs:QName), xs:token"?
           whttp:contentEncoding="xs:string"?? >

      <documentation />*

      <wsoap:module ... />*
      <wsoap:header element="xs:QName" mustUnderstand="xs:boolean"?
                    required="xs:boolean"? >
        <documentation />*
      </wsoap:header>*
      <whttp:header ... />*??

      [ <feature /> | <property /> ]*
    </fault>*

    <operation ref=">*
      <whttp:header ... />*??

    </fault>*

    <operation ref="xs:QName" 
               whttp:location="xs:anyURI"??
               whttp:contentEncodingDefault="xs:string"??
               whttp:queryParameterSeparator="xs:string"??
               whttp:ignoreUncited="xs:boolean"??
               wsoap:mep="xs:anyURI"?
               wsoap:action="xs:anyURI"? >

      <documentation />*

      <wsoap:module ... />*

      <input messageLabel="xs:NCName"?
             whttp:contentEncoding="xs:string"?? >
        <documentation />*
        <wsoap:module ... />*
        <wsoap:header ... />*
        <whttp:header ... />*??
      </input>*

      <output messageLabel="xs:NCName"?
             whttp:contentEncoding="xs:string"?? >
        <documentation />*
        <wsoap:module ... />*
        <wsoap:header ... />*
        <whttp:header ... />*??
      </output>*

      <infault ref="xs:QName"
                  messageLabel="xs:NCName"?>
        <documentation />*
        <wsoap:module ... />*
      </infault>*

      <outfault ref="xs:QName"
                   messageLabel="xs:NCName"?>
        <documentation />*
        <wsoap:module ... />*
      </outfault>*

    </operation>*

  </binding>

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

5.2 Identifying the use of the SOAP Binding

A Binding component (defined in [WSDL 2.0 Core Language]) is identified as a SOAP binding by assigning the value "http://www.w3.org/ns/wsdl/soap" to the {type} property of the Binding component.

5.3 SOAP Binding Rules

• Payload Construction. When formulating the SOAP envelope to be transmitted, the contents of the payload (i.e., the contents of the SOAP Body element information item of the SOAP envelope) MUST be what is defined by the corresponding Interface Message Reference component.^†This is further subject to optimization by a feature in use which affects serialization, such as MTOM [SOAP Message Transmission Optimization Mechanism]. The following binding rules MUST be adhered to:

  • If the value of the {message content model} property of the Interface Message Reference component is "#any", then the payload MAY be any one XML element.

  • If the value is "#none", then the payload MUST be empty.^†

  • If the value is "#element", then the payload MUST be the element information item identified by the {element declaration} property of the Interface Message Reference component.^†

  • If the Interface Message Reference component is declared using a non-XML type system (as considered in the Types section of [WSDL 2.0 Core Language]), then additional binding rules MUST be defined to indicate how to map those components into the SOAP envelope.^†

  Note:

  This SOAP binding extension only allows one single element in the SOAP body.

• SOAP Header Construction. If the {soap headers} property as defined in section 5.9 Declaring SOAP Header Blocks exists and is not empty in a Binding Message Reference or Binding Fault component, then an element information item conforming to the element declaration of a SOAP Header Block component's {element declaration} property, in the {soap headers} property, MAY be turned into a SOAP header block for the corresponding message.

  If the value of the SOAP Header Block component's {required} property is "true", the inclusion of this SOAP header block is REQUIRED, otherwise it is OPTIONAL.

  And, if the SOAP Header Block component's {mustUnderstand} property is present and its value is "true", that particular SOAP header block MUST be marked with a mustUnderstand attribute information item with a value of "true" or "1" as per the SOAP specification.

  SOAP header blocks other than the ones declared in the {soap headers} property may be present at run-time, such as the SOAP header blocks resulting from SOAP modules declared as explained in section 5.8 Declaring SOAP Modules.

5.4 Specifying the SOAP Version

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

5.5 Specifying the SOAP Underlying Protocol

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

5.6 Binding Faults

<description>
  <binding >
    <fault ref="xs:QName"
           wsoap:code="union of xs:QName, xs:token"?
           wsoap:subcodes="union of (list of xs:QName), xs:token"? >
      <documentation />*
    </fault>*
  </binding>
</description>