Web Services Addressing 1.0 - WSDL Binding

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 RFC 2119 [IETF RFC 2119].

When describing abstract data models, this specification uses the notational convention used by the XML Infoset [XML Information Set]. Specifically, abstract property names always appear in square brackets (e.g., [some property]).

When describing concrete XML schemas [XML Schema Structures, XML Schema Datatypes], this specification uses the notational convention of WS-Security [WS-Security]. Specifically, each member of an element's [children] or [attributes] property is described using an XPath-like notation (e.g., /x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates the presence of an element wildcard (<xs:any/>). The use of @{any} indicates the presence of an attribute wildcard (<xs:anyAttribute/>).

1.2 Namespaces

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 Namespaces]).

WS-Addressing is defined in terms of the XML Information Set [XML Information Set]. WS-Addressing may be used with SOAP [SOAP 1.2 Part 1: Messaging Framework] as described in Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP]. The examples in this specification use an XML 1.0 [XML 1.0] representation but this is not a requirement.

All information items defined by this specification are identified by the XML namespace URI [XML Namespaces] "http://www.w3.org/2005/03/addressing/wsdl". A normative XML Schema [XML Schema Structures, XML Schema Datatypes] document can be obtained by dereferencing the XML namespace URI.

2.1 Referencing WSDL Metadata from an EPR

The WSDL binding of Web Services Addressing introduces the following element and attribute information items for referencing WSDL metadata from an EPRs metadata section:

wsaw:InterfaceName

A QName identifying a description of the sequences of messages that a service sends and/or receives. This corresponds to a WSDL 2.0 interface and/or a WSDL 1.1 port type.

wsaw:ServiceName

A QName that identifies the set of endpoints at which a particular Web service is deployed. The set of endpoints is represented by a service in WSDL 2.0 and WSDL 1.1.

wsaw:ServiceName/@EndpointName

An NCName that identifies one endpoint amongst the set identified by by the service name above. An endpoint is represented by an endpoint in WSDL 2.0 and a port in WSDL 1.1.

The element information items defined above are used in an EPRs metadata section. The following shows an example endpoint reference. This references the interface named "fabrikam:Inventory" at the endpoint IRI "http://example.com/www.fabrikam/acct". Note the use of the WSDL[WSDL 2.0] wsdlLocation attribute.

<wsa:EndpointReference
    xmlns:wsa="http://www.w3.org/2005/03/addressing"
    xmlns:fabrikam="http://example.com/fabrikam">
  <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
  <wsa:Metadata
      xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance"
      wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam.wsdl">
    <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName>
  </wsa:Metadata>
</wsa:EndpointReference>

2.2 Embedding WSDL Metadata in an EPR

WSDL 1.1 or 2.0 definitions can be embedded in the metadata section of an EPR to provide a consuming application with WSDL information that applies to the referenced endpoint. To do so, the creator of an EPR MAY include a WSDL 2.0 description element (or a WSDL 1.1 definitions element) in the metadata property of the EPR. The semantics of the embedded WSDL is as defined by the WSDL 2.0 or 1.1 specifications.

In particular, embedding a WSDL service component description MAY be used by EPR issuers to indicate the presence of alternative addresses and protocol bindings to access the referenced endpoint. The alternatives are provided by the different endpoints of the embedded service. In the case of WSDL 1.1, additional ports may be conveyed by the WSDL 1.1 service definition which are not alternative access channels to the endpoint. In that case, if the InterfaceName or ServiceName elements are also included in the metadata section of the EPR, only the ports with the same interface as that specified are to be considered alternative access channels.

If the ServiceName element appears in the EPR’s [metadata] and an embedded WSDL service component is also provided inside a descriptions or definitions component, then the ServiceName SHOULD match the name of (one or more of) the WSDL service(s) included therein; the endpoint (port) name SHOULD match as well if present. The behavior of an EPR consumer when the ServiceName doesn’t match an embedded description is undefined.

<wsa:EndpointReference
    xmlns:wsa="http://www.w3.org/2005/03/addressing">
    
  <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
  <wsa:Metadata
      xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance"
      wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam.wsdl">
    <wsdl20:description  
        targetNamespace="http://example.com/fabrikam"
        xmlns:fabrikam="http://example.com/fabrikam"
        xmlns:abc="http://www.abccorp.com/"
        xmlns:wsdl20="http://www.w3.org/2004/08/wsdl">
      <wsdl20:import namespace="http://example.com/fabrikam/"
          location="http://example.com/fabrikam/fabrikam.wsdl/"/>
      <wsdl20:import namespace="http://www.abccorp.com/" 
          location="http://www.abccorp.com/abc.wsdl"/>
      <wsdl20:service name="InventoryService" 
          interface="fabrikam:Inventory">
        <wsdl20:endpoint name="ep1" binding="abc:soap-http-binding" 
            address="http://example.com/fabrikam/acct"/>
        <wsdl20:endpoint name="ep2" binding="abc:iiop" 
            address="..."/>
        <wsdl20:endpoint name="ep3" 
            binding="abc:soap-http-binding" 
            address="http://alt.example.com/fabrikam/acct"/>
      </wsdl20:service>
    </wsdl20:description>
  </wsa:Metadata>
</wsa:EndpointReference>

<wsa:EndpointReference
    xmlns:wsa="http://www.w3.org/2005/03/addressing">
  <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
  <wsa:Metadata>
    <wsdl11:definitions targetNamespace="http://example.com/fabrikam"
        xmlns:fabrikam="http://example.com/fabrikam"
        xmlns:abc="http://www.abccorp.com/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:iiop="http://www.iiop.org/"
        xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/">
      <wsdl11:import namespace="http://example.com/fabrikam"  
          location="http://example.com/fabrikam/fabrikam.wsdl"/>
      <wsdl11:import namespace="http://www.abccorp.com/" 
          location="http://www.abccorp.com/abc.wsdl"/>
      <wsdl11:service name="InventoryService">
        <wsdl11:port name="ep1" binding="abc:soap-http-binding"> 
          <soap:address location="http://example.com/fabrikam/acct"/>
        </wsdl11:port>
        <wsdl11:port name="ep2" binding="abc:iiop"> 
          <iiop:address location="..."/>
        </wsdl11:port>
      </wsdl11:service>
    </wsdl11:definitions>
  </wsa:Metadata>
</wsd:EndpointReference>

3.1 Explicit Association

WS-Addressing defines a global attribute, wsa:Action, that may be used to explicitly define the value of the [action] property for messages in a WSDL description. The type of the attribute is xs:anyURI and it is used as an extension on the WSDL input, output and fault elements.

For example consider the following WSDL excerpt:

<definitions targetNamespace="http://example.com/stockquote" ...>
  ...
  <interface name="StockQuoteInterface">
    <operation name="GetLastTradePrice" pattern="http://www.w3.org/2004/08/wsdl/in-out">
      <input element="tns:GetTradePricesInput" messageLabel="In"
            wsa:Action="http://example.com/GetQuote"/>
      <output element="tns:GetTradePricesOutput" messageLabel="Out"
            wsa:Action="http://example.com/Quote"/>
    </operation>
  </interface>
  ...
</definitions>

The action for the input of the GetLastTradePrice operation within the StockQuoteInterface is explicitly defined to be http://example.com/GetQuote. The action for the output of this same operation is http://example.com/Quote.

<definitions targetNamespace="http://example.com/stockquote" ...>
  ...
  <portType name="StockQuotePortType">
    <operation name="GetLastTradePrice">
      <input message="tns:GetTradePricesInput"
            wsa:Action="http://example.com/GetQuote"/>
      <output message="tns:GetTradePricesOutput"
            wsa:Action="http://example.com/Quote"/>
    </operation>
  </portType>
  ...
</definitions>
      

The action for the input of the GetLastTradePrice operation within the StockQuotePortType is explicitly defined to be http://example.com/GetQuote. The action for the output of this same operation is http://example.com/Quote.

3.2 Default Action Pattern for WSDL 2.0

In the absence of the wsa:Action attribute, the following pattern is used in WSDL 2.0 documents to construct a default action for inputs and outputs. The general form of an action URI is as follows:

[target namespace][delimiter][interface name][delimiter][operation name][direction token]

For fault messages, the general form of an action IRI is as follows:

[target namespace][delimiter][interface name][delimiter][fault name]

Where:

[delimiter]

is ":" when the [target namespace] is a URN, otherwise "/". Note that for IRI schemes other than URNs which aren't path-based (i.e. those that outlaw the "/" character), the default action value may not conform to the rules of the IRI scheme. Authors are advised to specify explicit values in the WSDL in this case.

[target namespace]

is the {target namespace} of the interface. If [target namespace] ends with a "/" an additional "/" is not added.

[interface name]

is the {name} of the interface.

[operation name]

is the {name} of the operation.

[fault name]

is the {name} of the fault.

[direction token]

• Empty ("") where the operation's {message exchange pattern} is "http://www.w3.org/2004/08/wsdl/in-only", "http://www.w3.org/2004/08/wsdl/robust-in-only", "http://www.w3.org/2004/08/wsdl/out-only", or "http://www.w3.org/2004/08/wsdl/robust-out-only".

• "Request" where the operation's {message exchange pattern} is "http://www.w3.org/2004/08/wsdl/in-out" or "http://www.w3.org/2004/08/wsdl/in-opt-out" and the message reference's {message label} = 'in'.

• "Solicit" where the operation's {message exchange pattern} is "http://www.w3.org/2004/08/wsdl/out-in" or "http://www.w3.org/2004/08/wsdl/out-opt-in" and the message reference's {message label} = 'out'.

• "Response" where the operation's {message exchange pattern} is "http://www.w3.org/2004/08/wsdl/in-out" or "http://www.w3.org/2004/08/wsdl/in-opt-out" and the message reference's {message label} = 'out'.

• "Response" where the operation's {message exchange pattern} is "http://www.w3.org/2004/08/wsdl/out-in", or "http://www.w3.org/2004/08/wsdl/out-opt-in" and the message reference's {message label} = 'in'.

• {message label} where the {message exchange pattern} is not one of the MEP IRIs defined in WSDL 2.0 Part 2.

For example consider the following WSDL excerpt:

<definitions targetNamespace="http://example.com/stockquote" ...>
  ...
  <interface name="StockQuoteInterface">
    <operation name="GetLastTradePrice" pattern="http://www.w3.org/2004/08/wsdl/in-out">
      <input element="tns:GetTradePricesInput" messageLabel="in" name="GetQuote"/>
      <output element="tns:GetTradePricesOutput" messageLabel="out" name="Quote"/>
    </operation>
  </portType>
  ...
</definitions>
      

3.3 Default Action Pattern for WSDL 1.1

In the absence of the wsa:Action attribute, the following pattern is used to construct a default action for inputs and outputs. The general form of an action IRI is as follows:

[target namespace][delimiter][port type name][delimiter][input|output name]

For fault messages, the general form of an action IRI is as follows:

[target namespace][delimiter][port type name][delimiter][operation name]Fault:[fault name]

Where:

[delimiter]

is ":" when the [target namespace] is a URN, otherwise "/". Note that for IRI schemes other than URNs which aren't path-based (i.e. those that outlaw the "/" character), the default action value may not conform to the rules of the IRI scheme. Authors are advised to specify explicit values in the WSDL in this case.

"Fault:"

is a literal character string to be included in the action.

[target namespace]

is the target namespace (/definition/@targetNamespace). If [target namespace] ends with a "/" an additional "/" is not added.

[port type name]

is the name of the port type (/definition/portType/@name).

[input|output name]

is the name of the element as defined in Section 2.4.5 of WSDL 1.1.

[fault name]

is the name of the fault (/definition/porttype/operation/fault/@name).

For example consider the following WSDL excerpt:

<definitions targetNamespace="http://example.com/stockquote" ...>
  ...
  <portType name="StockQuotePortType">
    <operation name="GetLastTradePrice">
      <input message="tns:GetTradePricesInput" name="GetQuote"/>
      <output message="tns:GetTradePricesOutput" name="Quote"/>
          <fault message="tns:ErrorMessage" name="Error"/>
    </operation>
  </portType>
  ...
</definitions>
      

WSDL defines rules for a default input or output name if the name attribute is not present. Consider the following example:

<definitions targetNamespace="http://example.com/stockquote" ...>
  ...
  <portType name="StockQuotePortType">
    <operation name="GetLastTradePrice">
      <input message="tns:GetTradePricesInput"/>
      <output message="tns:GetTradePricesOutput"/>
    </operation>
  </portType>
  ...
</definitions>
      

4.1 WSDL 1.1 Message Exchange Patterns

This section describes which of the core message properties are mandatory or optional for messages in the various MEPs defined by WSDL 1.1.

4.2 WSDL 2.0 Message Exchange Patterns

This section describes which of the core message properties are mandatory or optional for messages in the various MEPs defined by WSDL 2.0.