Web Services Description Language (WSDL) Version 2.0 Part 0: Primer

1. Introduction

1.1 Prerequisites

This primer assumes that the reader has the following prerequisite knowledge:

familiarity with XML (Extensible Markup Language (XML) 1.0 (Second Edition) [XML 1.0], XML Information Set [XML Information Set]) and XML Namespaces (Namespaces in XML [XML Namespaces]);
some familiarity with XML Schema (XML Schema Part 1: Structures [XML Schema: Structures] XML Schema Part 2: Datatypes [XML Schema: Datatypes]);
familiarity with basic Web services concepts such as Web service, client, and the purpose and function of a Web service description. (For an explanation of basic Web services concepts, see Web Services Architecture [WS Architecture] Section 1.4 and Web Services Glossary [WS Glossary] glossary. However, note the Web Services Architecture document uses the slightly more precise terms "requester agent" and "provider agent" instead of the terms "client" and "Web service" used in this primer.)

No previous experience with WSDL is assumed.

1.2 Structure of this Primer

Section 2 presents a hypothetical use case involving a hotel reservation service. It then proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:

The types element describes the kinds of messages that the service will send and receive.
The interface element describes what abstract functionality the Web service provides.
The binding element describes how to access the service.
The service element describes where to access the service.

Section 3 gives more information on defining message types.

Section 4 gives more information on interfaces.

Section 5 gives more information on bindings.

Section 6 gives more information on defining services.

Section 7 covers various advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc.

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

This document uses several XML namespaces, some of which are defined by standards, and some are application-specific. Namespace names of the general form "http://greath.example.com/..." represent application or context-dependent URIs [IETF RFC 2396].Note also that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).

2. WSDL 2.0 Basics

This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL2.0 features may be used.

2.1 Example Scenario: The GreatH Hotel Reservation Service

Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality:

CheckAvailability. To check availability, the client must specify a check-in date, a check-out date, and room type room, and the Web service will provide the room rate if such a room is available. If any input data is invalid, the service should return an error. Thus, the service will accept a checkAvailability message and return a checkAvailabilityResponse or invalidDataFault message.
MakeReservation. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a makeReservation message and return a makeReservationResponse or invalidCreditCardFault message.

We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the CheckAvailability operation.

The next several sections proceed step-by-step through the process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the WSDL 2.0 document that we'll be creating.

Example 2-1. WSDL 2.0 Document for the GreatH Web Service (Initial Example)

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope">

  <documentation>
    This document describes the GreatH Web service.  Additional 
    application-level requirements for use of this service -- 
    beyond what WSDL 2.0 is able to describe -- are available 
    at http://greath.example.com/2004/reservation-documentation.html
  </documentation>

  <types>
    <xs:schema 
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
        xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">

      <xs:element name="checkAvailability" type="tCheckAvailability"/>    
      <xs:complexType name="tCheckAvailability">     
        <xs:sequence>      
          <xs:element  name="checkInDate" type="xs:date"/>      
          <xs:element  name="checkOutDate" type="xs:date"/>      
          <xs:element  name="roomType" type="xs:string"/>      
        </xs:sequence>     
      </xs:complexType>   
            
      <xs:element name="checkAvailabilityResponse" type="xs:double"/>    
    
      <xs:element name="invalidDataError" type="xs:string"/>    

    </xs:schema>    
  </types>
  
  <interface  name = "reservationInterface" >

    <fault name = "invalidDataFault"
            element = "ghns:invalidDataError"/> 
   
    <operation name="opCheckAvailability" 
            pattern="http://www.w3.org/2004/03/wsdl/in-out" >
        <input messageLabel="In" 
              element="ghns:checkAvailability" />
        <output messageLabel="Out" 
              element="ghns:checkAvailabilityResponse" />
        <outfault ref="tns:invalidDataFault" messageLabel="Out"/>
    </operation>

  </interface>

  <binding name="reservationSOAPBinding" 
          interface="tns:reservationInterface"
          type="http://www.w3.org/2004/08/wsdl/soap12"
          wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">

    <operation ref="tns:opCheckAvailability" 
      wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"/>
  
    <fault ref="tns:invalidDataFault" 
      wsoap:code="soap:Sender"/>

  </binding>

  <service name="reservationService" 
       interface="tns:reservationInterface">

     <endpoint name="reservationEndpoint" 
               binding="tns:reservationSOAPBinding"
               address ="http://greath.example.com/2004/reservation"/>
        
  </service>

</description>

2.2 Getting Started: Defining a WSDL Target Namespace

Before writing our WSDL 2.0 document, we need to decide on a WSDL target namespace URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.)

The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should resolve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it being dereferenceable.

This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.

Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.

Example 2-2. An Initial Empty WSDL Document

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    . . . >

  . . .
</description>

2.2.1 Explanation of Example

<description: Every WSDL 2.0 document has a description element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.
xmlns="http://www.w3.org/2004/08/wsdl": This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the description element).
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl": This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather, it is a WSDL 2.0 attribute whose purpose is analogous to an XML Schema target namespace.
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl": This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the targetNamespace attribute. This will allow us later to use the tns: prefix in qnames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see [XML Namespaces] section 3 Qualified Names.)

Now we can start describing the GreatH service.

2.3 Defining Message Types

We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.

WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the types element, which is a child of the description element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's import mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need.

In WSDL 2.0, all normal and fault message types must be defined as single elements at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type.

Example 2-3. GreatH Message Types

Editorial note: dbooth
Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    . . . >

  , , ,

  <types>
    <xs:schema 
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
        xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">

      <xs:element name="checkAvailability" type="tCheckAvailability"/>    
      <xs:complexType name="tCheckAvailability">     
        <xs:sequence>      
          <xs:element  name="checkInDate" type="xs:date"/>      
          <xs:element  name="checkOutDate" type="xs:date"/>      
          <xs:element  name="roomType" type="xs:string"/>      
        </xs:sequence>     
      </xs:complexType>   
            
      <xs:element name="checkAvailabilityResponse" type="xs:double"/>    
    
      <xs:element name="invalidDataError" type="xs:string"/>    

    </xs:schema>    
  </types>
  . . .
</description>

2.3.1 Explanation of Example

xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd": We've added another namespace declaration. The ghns namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- not the target namespace of the WSDL document itself.
targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd": This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The checkAvailability, checkAvailability and invalidDataError element names will be associated with this XML Schema target namespace.
checkAvailability, checkAvailabilityResponse and invalidDataError: These are the message types that we'll use. Note that these are defined to be XML elements, as explained above.

Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section.

2.4 Defining an Interface

WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it.

A WSDL 2.0 interface defines the abstract interface of a Web service as a set of abstract operations, each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange pattern that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the in-out pattern (see WSDL 2.0 Predefined Extensions [WSDL 2.0 Predefined Extensions] section 2.2.3 In-Out) indicates that if the client sends a message in to the service, the service will either send a reply message back out to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).

For the GreatH service, we will (initially) define an interface containing a single operation, opCheckAvailability, using the checkAvailability and checkAvailabilityResponse message types that we defined in the types section. We'll use the in-out pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the in-only and out-only patterns (see WSDL 2.0 Predefined Extensions [WSDL 2.0 Predefined Extensions] section 2.2.1 In-Only and section 2.2.5 Out-Only), but that would just complicate matters for the client, because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.

In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the interface element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation.

Let's add these to our WSDL document.

Example 2-4. GreatH Interface Definition

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    . . . >

  . . .
  <types>
    <xs:schema 
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
        xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">

      <xs:element name="checkAvailability" type="tCheckAvailability"/>    
        . . .
            
      <xs:element name="checkAvailabilityResponse" type="xs:double"/>    
    
      <xs:element name="invalidDataError" type="xs:string"/>    

    </xs:schema>    
  </types>
  
  <interface  name = "reservationInterface" >

    <fault name = "invalidDataFault"
            element = "ghns:invalidDataError"/> 
   
    <operation name="opCheckAvailability" 
            pattern="http://www.w3.org/2004/03/wsdl/in-out" >
        <input messageLabel="In" 
              element="ghns:checkAvailability" />
        <output messageLabel="Out" 
              element="ghns:checkAvailabilityResponse" />
        <outfault ref="tns:invalidDataFault" messageLabel="Out"/>
    </operation>

  </interface>

  . . .
</description>

2.4.1 Explanation of Example

<interface name = "reservationInterface" >: Interfaces are declared directly inside the description element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").
<fault name = "invalidDataFault": The name attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must unique within an interface.
element = "ghns:invalidDataError"/>: The element attribute specifies the schema type of the fault message, as previously defined in the types section.
<operation name="opCheckAvailability": The name attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)
pattern="http://www.w3.org/2004/03/wsdl/in-out" >: This line specifies that this operation will use the in-out pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does not mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)
<input messageLabel="In": The input element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the messageLabel attribute. Since the in-out pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in WSDL 2.0 Predefined Extensions [WSDL 2.0 Predefined Extensions] section 2.2.3 In-Out for the in-out pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.
element="ghns:checkAvailability" />: This specifies the message type for this input message, as defined previously in the types section.
<output messageLabel="Out" . . .: This is similar to defining an input message.
<outfault ref="tns:invalidDataFault" messageLabel="Out"/>: This associates an output fault with this operation. Faults are declared a little differently than normal messages. The ref attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so indirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a message-triggers-fault rule; others use a fault-replaces-message rule. See WSDL 2.0 Predefined Extensions [WSDL 2.0 Predefined Extensions] section 2.1.2 Message Triggers Fault and section 2.1.1 Fault Replaces Message.)

Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.

Editorial note: dbooth
[This note is only relevant to the editors.] Hmm, I just realized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes.

2.5 Defining a Binding

Although we have specified what abstract messages can be exchanged with the GreatH Web service, we have not yet specified how those messages can be exchanged. This is the purpose of a binding. A binding specifies concrete message format and transmission protocol details for an interface, and must supply such details for every operation and fault in the interface.

In the general case, binding details for each operation and fault are specified using operation and fault elements inside a binding element, as shown in the example below. However, in some cases it is possible to use defaulting rules to supply the information. The WSDL 2.0 SOAP binding, for example, defines some defaulting rules for operations. (See Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings [WSDL 2.0 Bindings], section 2.3 Default Binding Rules.)

In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework] and HTTP 1.1 [IETF RFC 2616] as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.)

For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below.

Example 2-5. GreatH Binding Definition

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  . . .

  <types>
    . . .
  </types>
  
  <interface  name = "reservationInterface" >

    <fault name = "invalidDataFault"
            element = "ghns:invalidDataError"/> 
   
    <operation name="opCheckAvailability" 
            pattern="http://www.w3.org/2004/03/wsdl/in-out" >
       . . .
    </operation>

  </interface>

  <binding name="reservationSOAPBinding" 
          interface="tns:reservationInterface"
          type="http://www.w3.org/2004/08/wsdl/soap12"
          wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">

    <operation ref="tns:opCheckAvailability" 
      wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"/>
  
    <fault ref="tns:invalidDataFault" 
      wsoap:code="soap:Sender"/>

  </binding>

  . . .
</description>

2.5.1 Explanation of Example

xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"

We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 [SOAP 1.2 Part 1: Messaging Framework]. Elements and attributes prefixed with wsoap: are constructs defined there.

xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the soap: prefix when we need to refer to one of those terms.

<binding name="reservationSOAPBinding"

Bindings are declared directly inside the description element. The name attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct.

interface="tns:reservationInterface"

This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in 5. More on Bindings, a reusable binding can be defined by omitting the interface attribute. Note also the use of the tns: prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the tns: prefix, but in 7.3 Import mechanism and authoring stylewe will see how WSDL 2.0's import mechanism can be used to combine components that are defined in different WSDL target namespaces.

type="http://www.w3.org/2004/08/wsdl/soap12"

This specifies the type of concrete message format to use, in this case SOAP 1.2.

wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"

This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the wsoap: prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP.

<operation ref="tns:opCheckAvailability"

This not defining a new operation. Rather, it is referencing the previously defined opCheckAvailability operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See the SOAP binding in WSDL 2.0 Bindings [WSDL 2.0 Bindings] section 2.3 Default Binding Rules.)

wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">

This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (in-out) that was specified when the opCheckAvailability operation was defined.

<fault ref="tns:invalidDataFault"

As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (invalidDataFault) that was previously defined in the opCheckAvailability interface, in order to specify binding details for it.

wsoap:code="soap:Sender"/>

This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent.

Editorial note
Need to verify that this explanation is correct. See http://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.html

If desired, an list of subcodes can also be specified using the optional wsoap:subcodes attribute.

2.6 Defining a Service

Now that our binding has specified how messages will be transmitted, we are ready to specify where the service can be accessed, by use of the service element.

A WSDL 2.0 service specifies a single interface that the service will support, and a list of endpoint locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See 7.4 Multiple Logical WSDL Documents Describing the Same Service.)

Here is a definition for our GreatH service.

Example 2-6. GreatH Service Definition

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  . . .

  <types>
    . . .
  </types>
  
  <interface  name = "reservationInterface" >
    . . .
  </interface>

  <binding name="reservationSOAPBinding" 
          interface="tns:reservationInterface"
        . . . >
    . . .
  </binding>

  <service name="reservationService" 
       interface="tns:reservationInterface">

     <endpoint name="reservationEndpoint" 
               binding="tns:reservationSOAPBinding"
               address ="http://greath.example.com/2004/reservation"/>
        
  </service>

2.6.1 Explanation of Example

<service name="reservationService": This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required in order to facilitate the use of URIs to indentify components in WSDL 2.0 documents. (See WSDL 2.0 Core Language [WSDL 2.0 Core Language] appendix C URI References for WSDL constructs.)
interface="tns:reservationInterface">: This specifies the name of the previously defined interface that these service endpoints will support.
<endpoint name="reservationEndpoint": This defines an endpoint for the service, and a name for this endpoint, which must be unique within this service.
binding="tns:reservationSOAPBinding": This specifies the name of the previously defined binding to be used by this endpoint.
address ="http://greath.example.com/2004/reservation"/>: This specifies the physical address at which this service can be accessed using the binding specified by the binding attribute.

That's it! Well, almost.

2.7 Documenting the Service

As we have seen, a WSDL 2.0 document is inherently only a partial description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.

The documentation element allows the WSDL author to include some human-readable documentation inside a WSDL document. It is a convenient place to reference any additional documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (as can be seen in the syntax summary presented later), though in this example we have only demonstrated its use at the beginning.

Example 2-7. Documenting the GreatH Service

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    . . . >

  <documentation>
    This document describes the GreatH Web service.  Additional 
    application-level requirements for use of this service -- 
    beyond what WSDL 2.0 is able to describe -- are available 
    at http://greath.example.com/2004/reservation-documentation.html
  </documentation>

  <types>
    . . .
  </types>

  . . .  
</description>

2.7.1 Explanation of Example

<documentation>: This element is optional, but a good idea to include. It can contain arbitrary mixed content.
at http://greath.example.com/2004/reservation-documentation.html: The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service.

This completes our presentation of the GreatH example. Let's summarize the syntax we've seen.

2.8 XML Syntax Summary

In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components. The following conventions are followed for the syntax:

The syntax appears as an XML instance, but the values indicate the data types instead of values.
Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).
Elements names ending in "..." (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.

Editorial note: dbooth
To do: check the above elipses (...), as they weren't rendering properly at one point.

2.8.1 Brief Syntax Summary

Editorial note
To do: Insert short summary here

2.8.2 Longer Syntax Summary

Editorial note: dbooth
To do: Update this, and delete the <documentation>, <feature> and <property> elements, because they're mentioned below.

<description targetNamespace="xs:anyURI" >
  <documentation />?

  <import namespace="xs:anyURI" location="xs:anyURI"? >
    <documentation />?
  </import>*

  <include location="xs:anyURI" >
    <documentation />?
  </include>*

  <types>
    <documentation />?
  </types>

  <interface name="xs:NCName" extends="list of xs:QName"? styleDefault="list of xs:anyURI"? >
    <documentation />?

    <fault name="xs:NCName" element="xs:QName"? >
      <documentation />?

      <feature ... />*

      <property ... />*
    </fault>*

    <operation name="xs:NCName" pattern="xs:anyURI" style="list of xs:anyURI"? safe="xs:boolean"? >
      <documentation />?

      <input messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </input>*

      <output messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </output>*

      <infault ref="xs:QName" messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </infault>*

      <outfault ref="xs:QName" messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </outfault>*

      <feature ... />*

      <property ... />*
    </operation>*

    <feature uri="xs:anyURI" required="xs:boolean"? >
      <documentation />?
    </feature>*

    <property uri="xs:anyURI" required="xs:boolean"? >
      <documentation />?

      <value> xs:anyType </value>?
      
      <constraint> xs:QName </constraint>?
    </property>*
  </interface>*

  <binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI" >
    <documentation />?

    <fault ref="xs:QName" >
      <documentation />?

      <feature ... />*

      <property ... />*
    </fault>*

    <operation ref="xs:QName" >
      <documentation />?

      <input messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </input>*

      <output messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </output>*

      <feature ... />*

      <property ... />*
    </operation>*

    <feature ... />*

    <property ... />*
  </binding>*

  <service name="xs:NCName" interface="xs:QName" >
    <documentation />?

    <endpoint name="xs:NCName" binding="xs:QName" address="xs:anyURI"? >
      <documentation />?

      <feature ... />*

      <property ... />*
    </endpoint>*

    <feature ... />*

    <property ... />*
  </service>*
</description>

In addition, feature and property elements are allowed inside most WSDL elements. Also, an optional documentation element is allowed inside any WSDL element as a container for human readable and/or machine processable documentation. The content of documentation is arbitrary characters and elements ("mixed" content in XML Schema).

3. More on Message Types

3.1 Defining Messages Using XML Schema

As we saw previously, WSDL 2.0 provides a types element for enclosing messages definitions in a WSDL document. There are two ways to enclose messages definitions within the types element: use xs:import mechanism provided by XML Schema, or embed the schemas within xs:schema elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for the types element:

<description>
  <types>
    <documentation />?
    <xs:import namespace="xs:anyURI" schemaLocation= "xs:anyURI"?/>*
    <xs:schema targetNamespace="xs:anyURI" />*
    
    [extension elements]*
  </types>
</description>

A WSDL description MUST NOT refer to XML Schema components in a given namespace unless an xs:import and/or xs:schema statement for that namespace is present. In other words, using the xs:import and/or xs:schema constructs is a necessary condition for making XML Schema components available to a WSDL description.

Please note the use of type system other than XML Schema is indicated by the extension elements in the above syntax. (See WSDL 2.0 Core Language [WSDL 2.0 Core Language] appendix E Examples of Specifications of Extension Elements for Alternative Schema Language Support.)

3.1.1 Importing XML Schema

Let's examine the XML Schema import first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in 7.3 Import mechanism and authoring style. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components included by it via xs:include are available to WSDL. Specifically, components that the schema imports via xs:import are NOT available to WSDL.

Editorial note: dbooth
Check this. An issue was recently raised about import not being transitive.

A types element can contain zero or more import s which may have one or two attributes as follows:

A REQUIRED namespace attribute of type xs:anyURI.

The namespace attribute defines the namespace of the element declarations imported from the referenced schema. As mandated in Section 3 of the Part 1 specification, the referenced schema MUST contain an XML Schema targetNamespace attribute on its xs:schema element and the values of these two attributes MUST be identical. It is an error to import a schema that does not have an XML Schema target namespace. Such schemas must first be included (using xs:include ) in a schema that contains a targetNamespace attribute; on its xs:schema element, which can then be either imported or inlined in the WSDL document.
An OPTIONAL schemaLocation attribute of type xs:anyURI.

The schemaLocation attribute, if present, provides a hint to the WSDL processor as to where the schema may be located. It's optional since the WSDL may have better ways to locate the schema files, for example, caching and cataloging technologies may provide better information than this hint.

3.1.2 Embedding XML Schema

Embedding an XML schema uses the existing top-level xs:schema element defined by XML Schema [XML Schema: Structures]. It comparable to simply cutting and pasting an existing, stand-alone schema to a location inside the types element.

The schema components defined in the embedded schema are available to WSDL for reference by QName (see @@@@). Note that only components defined in the schema itself and components included by it via xs:include are available to WSDL. Specifically, components that the schema imports via xs:import are NOT available to WSDL.

Similarly, components defined in an embedded XML schema are NOT automatically made available to a WSDL description that imported (using wsdl:import ) the description that embeds the schema (see section @@@@ for more details). For this reason, it is recommended that XML schema documents intended to be shared across several WSDL descriptions be placed in separate documents and imported using xs:import , rather than embedded inside a WSDL document.

Inside an embedded XML schema, the xs:import and xs:include elements MAY be used to refer to other XML schemas embedded in the same WSDL description, provided that an appropriate value is specified for their schemaLocation attributes. The semantics of such elements are governed solely by the XML Schema specification [XML Schema: Structures].

Editorial note: KevinL	20040517
Add Example - illustrate use of xs:import and xs:include for embedded schema Clarification - what should be the "appropriate value" for schemalocation, especially when its's xs:include?

A types element can contain zero or more schema s which may have the following attributes:

A REQUIRED targetNamespace attribute of type xs:anyURI.

It defines the XML Schema target namespace of the element declarations embedded in its owner xs:schema . Note that WSDL modifies the XML Schema definition of XML Schema xs:schema to make the targetNamespace attribute required.
Additional OPTIONAL attributes as specified for the xs:schema element by the XML Schema specification.
Zero or more child elements as specified for xs:schema by the XML Schema specification.

Here is an example of importing a schema.

Example 3-1. Importing Message Definitions into WSDL 2.0

Example 3-2. Importing Message Definitions

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2004/08/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    . . . >
  . . .
  
  <types>
    <documentation>
        Messages definitions of the reservation Web service of GreatH hotel. 
    </documentation>
    
    <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd" 
        schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>  
  </types>

  . . .
</description>

4. More on Interfaces

We previously mentioned that a WSDL 2.0 interface is basically a set of operation s. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for interface .

4.1 Interface Syntax

Editorial note: dbooth
To do: Simplify this syntax summary.

Below is the XML syntax summary of the interface element:

<description targetNamespace="xs:anyURI" >

  <interface name="xs:NCName" extends="list of xs:QName"? styleDefault="list of xs:anyURI"? >
    <documentation />?

    <fault name="xs:NCName" element="xs:QName"? >
      <documentation />?

      <feature ... />*

      <property ... />*
    </fault>*

    <operation name="xs:NCName" pattern="xs:anyURI" style="list of xs:anyURI"? safe="xs:boolean"? >
      <documentation />?

      <input messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </input>*

      <output messageLabel="xs:NCName"? element="union of xs:QName, xs:Token"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </output>*

      <infault ref="xs:QName" messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </infault>*

      <outfault ref="xs:QName" messageLabel="xs:NCName"? >
        <documentation />?

        <feature ... />*

        <property ... />*
      </outfault>*

      <feature ... />*

      <property ... />*
    </operation>*

    <feature uri="xs:anyURI" required="xs:boolean"? >
      <documentation />?
    </feature>*

    <property uri="xs:anyURI" required="xs:boolean"? >
      <documentation />?

      <value> xs:anyType </value>?
      
      <constraint> xs:QName </constraint>?
    </property>*
  </interface>*


</description >

One WSDL description element may contain zero or more interface elements as its direct children. Zero interface elements are permitted since a description element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL description via import/include mechanisms.

Let's have a look at the attributes of interface first. It has one required name attribute. Within the same WSDL target namespace (might be in different wsdl documents, see section @@@@), each interface must have a unique name. The interface element has two optional attributes:extends and styleDefault . extends will be explained in the next section. We will explain what a style later. For now, keep in mind that the optional styleDefault attribute of interface can be used to define a default value for the style attribute of all operation s under this interface , if any of the operations do not specify a value for its style .

4.1.1 Interface Inheritance

The optional extends attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention.

First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly.

Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in question have same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same WSDL target namespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the interface element (as descrbed later), the same name-collision resolution rules apply to those constructs.

Editorial note: KevinL	20040910
Add Example - illustrate use extends attribute

Now let's have a look at the children of interface . An interface can contain zero or more fault , zero or more operation , zero or more feature , and zero or more property . feature and property will be examined in section @@@@. We will explain the fault and operation constructs in the following sections.

4.1.2 Reusable Faults

The fault element can be used to declare faults that may occur during execution of operations of an interface. Declaring fault s directly under interface and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations.

The fault element has a required name attribute. Within a same namespace, all faults must be named uniquely. The optional element attribute can be used to indicate the content or playload of the fault message. Its value should be the QName of the XML schema global element declaration which defines the fault message. Please note when other type systems are used to define a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow associating such a message definition with the fault.

Here is an example of reusing faults.

Editorial note: dbooth
To do: Update this example

Example 4-1. Declaring interface faults


<description 
        targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
        xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns = "http://www.w3.org/2004/08/wsdl" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <documentation>
        Description: The definition of the reservation Web service of GreatH hotel. 
        Author: Joe Somebody
        Date: 05/17/2004
  </documentation>
  
  <types>

    <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd" 
                schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
                
  </types>
  
  < interface  name = "reservation" >
                
        <fault name = "invalidCreditCardFault"
                        element = "ghns:invalidCreditCardError">     
                <documentation>
                        falut declaration for invalid credit card information. 
                </documentation>

        </fault>   

        <fault name = "invalidDataFault"
                        element = "ghns:invalidDataError">   
                <documentation>
                        falut declaration for invalid data. 
                </documentation>

        </fault>   

  </interface>


</description>

Editorial note: KevinL	20040520
Need clarification - fault must be named uniquely across interfaces?

4.1.3 Interface Operations

Now we are ready to take a close look at the operation element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The operation element is the glue that brings all the pieces together for an abstract interaction. The service indicates its participation in a MEP by using the MEP in its operations. Message placeholders defined in a MEP are associated with specific message types in operations.

WSDL 2.0 defines two required and two optional attributes for an operation :

A required name attribute

Operation names must be unique within an interface. Beware that operations are local to an interface ,so two interface elements sharing the same WSDL target namespace but with different name MAY contain operations which share the same name. Thus, operations cannot be referenced by QName since the name and WSDL target namespace are not sufficient to uniquely identify an operation . In order to uniquely identify an operation , one must first identify the interface by QName and then identify the operation within that interface by a further QName. As explained in section @@@, this fact has compound impact when an interface extends other interfaces. It is considered good practice to name operations uniquely within same namespace whenever possible.
A required pattern attribute

it identifies the MEP a given operation uses. Its value must be an absolute URI.
An optional style attribute

it's an absolute URI identifying the rules that were used to construct the message type definitions used by the operation . Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages (See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for the RPC style must be followed. We will have a closer look at RPC style in section@@@.

Editorial note: KevinL 20040910

Add Example and more text - illustrate use of RPC style
An optional safety attribute

A boolean indicating whether the operation is asserted to be safe (as defined in Section 3.5 of Web Architecture for users of the described service to invoke. An operation SHOULD be marked safe by setting the safty to true if it meets all the criteria for a safe interaction defined in Section 3.5 of Web Architecture. The default value of this attribute is false. If it is false or is not set, then no assertion is made about the safety of the operation, thus the operation MAY or MAY NOT be safe.

An operation references a set of ordinary and fault messages it accepts or sends via zero or more input , output ,infault , and outfault element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@, an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The input and output element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:messageLabel and element . The messageLabel attribute is used to identify the role this message plays in the MEP. Its value must match the name of the MEP place holder message. Note that the messageLabel is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The element attribute can be used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values #any, #none, or #element. A value of #any indicates that the message content is any single element. A value of #none indicates there is no message content. It means that the payload will be empty. When the value is set to a Qname, it indicates that the message consists of a single element described by the referenced global element declaration reference by Qname. In addition, the direction implied by the input, and output must also match the direction of the placeholder message identified by messageLabel .

We have already talked about how to associate a message type with a reusable interface fault . We have also covered the fault generation rules a MEP may use. Here under operation , the infault and outfault elements can be used to associate an interface fault with a specific message in the MEP used by an operation . Such association is done via a few attributes: the now familiar messageLabel attribute, the direction implied by the infault and outfault, and a required ref attrbiute which points to the Qname of an interface fault . When infault and/or outfault occur multiple times within an operation , they define alternative fault message.

Editorial note: dbooth
To do: Update this example. Also: which features should it illustrate?

Example 4-2. Defining Interface Operations

<description 
        targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
        xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns = "http://www.w3.org/2004/08/wsdl" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <documentation>
        Description: The definition of the reservation Web service of GreatH hotel. 
        Author: Joe Somebody
        Date: 05/17/2004
  </documentation>
  
  <types>
    
    <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd" 
                schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
                
  </types>
  
  < interface  name = "reservation" >
                
        <fault name = "invalidCreditCardFault"
                        element = "ghns:invalidCreditCardError"/>    

        <fault name = "invalidDataFault"
                        element = "ghns:invalidDataError"/>  

        <operation name="checkAvailability" pattern="http://www.w3.org/2004/03/wsdl/in-out" >
                
                <input messageLabel="In" element="ghns:checkAvailability"/ >

                <output messageLabel="Out" element="ghns:checkAvailabilityResponse"/ >

                <outfault ref="invalidDataFault" messageLabel="Out"/>

        </operation>

        <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" >
                
                <input messageLabel="In" element="ghns:makeReservation"/ >

                <output messageLabel="Out" element="ghns:makeReservationResponse"/ >

                <outfault ref="invalidDataFault" messageLabel="Out"/>

                <outfault ref="invalidCreditCardFault" messageLabel="Out"/>

        </operation>

  </interface>

</description>

Note that in the above example, the invalidDataFault is re-used by both operations. In the makeReservation operation, two alternative outgoing faults are defined which means either a invalidDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.

An operation can also contain zero or more feature and property elements. We defer the explanation for feature and property to section @@@@.

4.2 Understanding Message Exchange Patterns

WSDL 2.0 message exchange patterns (MEPs) are used to defines the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation specifies which MEP to use. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.

It's worth pointing out that like interfaces and operations, WSDL MEPs do not exhaustively describe the set of messages exchanged between a service and other nodes. By some prior agreement, another node and/or the service may send other messages (to each other or to other nodes) that are not described by the pattern. For instance, even though a pattern may define a single message sent from a service to one other node, the Web Service may multicast that message to other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.

A total of 8 MEPs are defined in Part 2 of the WSDL 2.0 specification. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties.

Editorial note: dbooth
Add info about how to define a new MEP?

For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified.

Fault Replaces Message: Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces.
Message Triggers Fault: Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP.
No Faults: No faults will be delivered.

Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL2.0 defines four in-bound MEPS:

In-Only ("http://www.w3.org/2004/03/wsdl/in-only")

This patten consists of exactly one message received by a service from some other node. No fault maybe generated.
Robust In-Only ("http://www.w3.org/2004/03/wsdl/robust-in-only")

This pattern can be considered as a variation of In-only. It also consists of exactly one message received by a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model.
In-Out ("http://www.w3.org/2004/03/wsdl/in-out")

This patten consists of exactly two message: a message received by a service from some other node, followed by a message sent to the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model.
In-Optional-Out ("http://www.w3.org/2004/03/wsdl/in-opt-out")

This patten consists of one or two messages: a message received by a service from some other node, optionally followed by a message sent to the other node from the service. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model.

WSDL2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:

Out-Only ("http://www.w3.org/2004/03/wsdl/out-only")

This patten consists of exactly one message sent to some other node from a service. No fault maybe generated.
Robust Out-Only ("http://www.w3.org/2004/03/wsdl/robust-out-only")

This pattern can be considered as a variation of Out-only. It also consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model.
Out-in ("http://www.w3.org/2004/03/wsdl/out-in")

This patten consists of exactly two message: a message sent to some other node from a service, followed by a message received by the service from the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model.
Out-Optional-In ("http://www.w3.org/2004/03/wsdl/out-opt-in")

This patten consists of one or two messages: a message sent to some other node from a service, optionally followed by a message received by the service from the other node. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model.

While the in-bound MEPs are easier to understand, there have been questions concerning the usefulness of out-bound MEPs, especially how a service can specify the endpoint information for the target node of the initial out-bound message. In their typical use cases, such as in large scale intergration projects where endpoint information is most likely specified at deployment or runtime by mapping and routing facilities, or/and in languages that facilitate services composition where only abstract interfaces are concerned, Out-bound MEPs are useful in the abstract level for fully specifying the functionality of a service, including its requirements for its potential customers, so application integrator can gain a better understanding of how multiple services may be used together, whereas binding and endpoint information may be provided by integration infrastructure in application deployment and runtime.

Editorial note: KevinL	20040910
Add more use cases and example - illustrate use of outbound meps?

5. More on Bindings

A binding can be defined for different levels of reusability. It can be used to describe binding information in a re-usable manner for any interface or specifically for a given interface. Furthermore, binding information MAY be specified on a per-operation basis if needed. If a binding specifies any operation-specific binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from.Conversely, a binding that omits any operation-specific binding details and any fault binding details MAY omit specifying an interface. bindings that do not specify an interface MAY be used to specify operation-independent binding details for Service components with different interfaces. That is, such bindings are reusable across one or more interfaces.

A binding tied to a particular interface MUST define bindings for all the operations of that interface. The bindings may occur via defaulting rules which allow one to specify default bindings for all operations (for example, see the SOAP binding in WSDL 2.0 Bindings [WSDL 2.0 Bindings] section 2.3 Default Binding Rules) or by directly listing each operation of the interface and defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.

The binding constructs can be grouped into two categories: those in the WSDL namespace of "http://www.w3.org/2004/08/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.

5.1 Binding Constructs in WSDL Namespace

Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:

<description targetNamespace="xs:anyURI" >
  
  <binding name="xs:NCName" interface="xs:QName"? >
    <documentation />?

    <fault ref="xs:QName" >
      <documentation />?
    </fault>*

    <operation ref="xs:QName" >
      <documentation />?

      <input messageLabel="xs:NCName"? >
        <documentation />?
      </input>*

      <output messageLabel="xs:NCName"? >
        <documentation />?
      </output>*

      <feature ... />*

      <property ... />*
    </operation>*

    <feature ... />*

    <property ... />*
  </binding>*

</description>

Editorial note: KevinL	20040527
Need clarification - infault outfault are missing from the binding operation syntax. Is it an oversight?

Editorial note: dbooth
Trim some of this? Redundant?

One WSDL description element may contain zero or more binding elements as its direct children.

The binding element has a required name attribute. Within the same WSDL target namespace , each binding must have a unique name. The optional interface attribute refers, by QName, to an interface . See the previous section for how the interface attribute can be used to achieve different levels of reusability of the binding .

Careful readers may have already noticed that the binding syntax is to some extent symmetric with the syntax of interface , in other words, each interface construct has a binding counterpart. Simliar to interface ,a binding element can contain zero or more fault , zero or more operation , zero or more feature , and zero or more property . Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol spaces and are designed for different purpose. The feature and property element will be examined in section @@@@. We will explain the binding fault and operation constructs in the following sections.

5.1.1 Binding Faults

A binding fault describes a concrete binding of an abstract fault within an interface to a particular concrete message format. More precisely, it describes how faults that occur within a message exchange of an operation will be formatted since the fault does not occur by itself - it occurs as part of a message exchange as defined by an interface operation and its binding counterpart the binding operation .

A binding fault has one required ref attribute which is a reference, by Qname, to an interface fault . It identifies the abstract interface fault for which binding information is being specified. Be aware that the value of ref attribute of all the faults under a binding MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given binding .

5.1.2 Binding Operations

A binding operation describes a concrete binding of a particular operation of an interface to a particular concrete message format.A particular operation of an interface is uniquely identified by the WSDL target namespace of the interface and the name of the operation within that interface, via the required ref attribute of binding operation . For each operation within a binding , the value of ref attribute MUST be unique. That is, one cannot define multiple bindings for the same interface operation within a given binding .

Editorial note: KevinL	20040527
Need clarification - wording about QName uniqueness in part 1 section 2.10.1 and 2.11.1 need to change. it's not correct to say "A particular operation of an interface is uniquely identified by the WSDL target namespace of the interface and the name of the operation within that interface"

Corresponding to its interface operation counterpart, binding operation may also have zero or more input ,output , infault , and/or outfault . The presence or absence of these message and/or fault reference constructs within a particular binding operation is governed by the interface operation counterpart.

5.2 Extensions for SOAP Binding

Example 5-1. SOAP binding example placeholder - to be completed


<description 
        targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
        xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns = "http://www.w3.org/2004/08/wsdl" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

</description>

5.3 Extensions for HTTP Binding

Example 5-2. HTTP Binding example placeholder - to be completed

<description 
        targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl" 
        xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
    xmlns = "http://www.w3.org/2004/08/wsdl" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">

</description>

6. More on Service Endpoints

Editorial note: dbooth
This section now seems largely redundant. Perhaps we should reduce or eliminate it.

As described previously, the service construct specifies a set of alternate endpoints at which a service is available. Zero or more services can be defined within a description element. However, each service is limited to a single interface. The XML syntax of service is summarized below:

<description targetNamespace="xs:anyURI" >

  <service name="xs:NCName" interface="xs:QName" 
    <documentation />?

    <endpoint name="xs:NCName" binding="xs:QName" >
      <documentation />?
    </endpoint>+
  </service>*

</description>

A service has a required name attribute (also see section @@@@ for service reference). Each service within a same namespace must be named uniquely. A service can only implement one single interface, and it must specify the single interface it implements via the interface attribute.

A service may contain one or more alternate endpoints . An endpoint defines the particulars of a specific endpoint at which a given service is available.

An endpoint has two required attributes: name and binding . All endpoints within a service must be named uniquely via the name attribute. The required binding attribute refers to, via Qname, a binding definition. Note that if the refered binding specifies a particular interface, that interface MUST be the same as the one implmented by the parent service .

Like the WSDL binding constructs explained in section @@@@, the WSDL endpoint construct is also like an anchor for hosting extension elements that are used to provide information specific to a particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL endpoint construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service endpoint .

7. Advanced Topics - TBD

Editorial note: KevinL	20040526
This section is very incomplete, and topics are still TBD.

7.1 Extensibility

WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and Features and Properties. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.

In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the W3C TAG has been discussing the issue (see TAG issue namespaceDocument-8) and is likely to provide guidance at some point.

7.1.1 Optional Versus Required Extensions

Extensions can either be required or optional: An optional extension is one that the requester agent may either engage or ignore, entirely at its discretion, and is signaled by attribute wsdl:required="false"; whereas a required extension is one that MUST be supported and engaged by the requester agent in order for the interaction to succeed properly, and is signaled by attribute wsdl:required="true".

The optionality signaled by wsdl:required="false" pertains only to the requester agent -- not the provider agent. The provider agent MUST support both optional and required extensions that it advertises in its WSDL document.

A WSDL processor (acting to realize a requester agent) need not support every conceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault.

7.1.2 Scoping of the wsdl:required Attribute

Editorial note
To do: Need to check the scoping rules to see if this is correct.

As a convenience mechanism, the wsdl:required attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to false.

Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting wsdl:required="false" when an outer scope, written by someone else, had set wsdl:required="true".

7.2 Features and Properties

[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0144.html ]

7.3 Import mechanism and authoring style

[Discuss how WSDL documents should be factored to allow significant components to be reused.]

7.4 Multiple Logical WSDL Documents Describing the Same Service

[Acknowledge that multiple logical WSDL documents might try to describe the same service. Explain why some might do this intentionally, why it might cause problems for some systems, and explain that this is outside scope of the WSDL language. See thread starting at http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html ]

7.5 Versioning and Service Equivalency

Per decision 2004-03-04 to add the results of the Versioning Task Force also.

7.6 MTOM Support

This section shows how Features and Properties can be used to indicate the use of MTOM. @@ Example from GlenD: http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0076.html @@

7.7 Security Considerations

7.8 Operation Style and RPC

7.9 Enabling Easy Message Dispatch

Suppose a WSDL document has two input-output operation and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at designtime, without access to the runtime messages.) This is the problem of dispatch. How can a WSDL document be written to ensure easy message dispatch?

One technique is to ensure that the top-level elements declared in the message schema are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.

Another technique is to define a required feature that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit.

7.10 GET Versus POST: Which to Use?

[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html that prescribes when to use GET versus POST as well as some useful example]

7.11 Service References

[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]

7.12 XML Schema Examples

[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]

7.13 Multiple In-Line Schemas

[Need to explain that this can be done. See http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html ]

7.14 The schemaLocation Attribute

[ACTION: 2003-11-13: David to add discussion / example(s) re: @schemaLocation for embedded schemas to the primer. See discussion in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html and thread called "Schemas in imported WSDL" in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html ]

7.15 Mapping to RDF and Semantic Web

7.16 Notes on URIs

This section does not directly contribute to the specification, but provides background that may be useful when implementing the specification.

7.16.1 XML Namespaces and Schema Locations

It is a common misperception to equate either the target namespace of an XML Schema or the value of the xmlns attribute in XML instances with the location of the corresponding schema. Even though namespaces are URIs, and URIs may be locations, and it may be possible to retrieve a schema from such a location, this does not mean that the retrieved schema is the only schema that is associated with that namespace. There can be multiple schemas associated with a particular namespace, and it is up to a processor of XML to determine which one to use in a particular processing context. The WSDL specification provides the processing context here via the import mechanism, which is based on XML Schema's term for the similar concept.

7.16.2 Relative URIs

Throughout this document there are fully qualified URIs used in WSDL and XSD examples. The use of a fully qualified URI is simply to illustrate the referencing concepts. The use of relative URIs is allowed and warranted in many cases. For information on processing relative URIs, see RFC2396.

7.16.3 Generating URIs

Editorial note: dbooth
Is this convention vendor-specific? http://tempuri.org only seems to mention MS tools. If so, this section needs to be further edited or removed.

When working with WSDL, it is sometimes desirable to make up a URI for an entity, but not make the URI globally unique for all time and have it "mean" that version of the entity (schema, WSDL document, etc.). There is a particular URI base reserved for use for this type of behavior. The base URI "http://tempuri.org/" can be used to construct a URI without any unique association to an entity. For example, two people or programs could choose to simultaneously use the URI " http://tempuri.org/userSchema" for two completely different schemas, and as long as the scope of the use of the URIs does not intersect, then they are considered unique enough. This has the further benefit that the entity referenced by the URI can be versioned without having to generate a new URI, as long as it makes sense within the processing context. It is not recommended that " http://tempuri.org/" be used as a base for stable, fixed entities.

8. References

@@ To do: Enable the reference to the RDF mapping when it's done. @@

8.1 Normative References

[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 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.
[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 Namespaces]: Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[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.
[RFC 3023]: IETF "RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July 1998. (See http://www.ietf.org/rfc/rfc3023.txt.)
[WSDL MediaType]: IETF Internet Draft "The 'application/wsdl+xml' media type", @@@. (Work to be done once we have consensus on the media type).
[WSDL 2.0 Core Language]: Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, R. Chinnici, M. Gudgin, J-J. Moreau, A. Ryman, J. Schlimmer, S. Weerawarana, Editors. World Wide Web Consortium, 3 August 2004. This version of the "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language" Specification is available at http://www.w3.org/TR/2004/WD-wsdl20-20040803. The latest version of "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language" is available at http://www.w3.org/TR/wsdl20.
[WSDL 2.0 Predefined Extensions]: Web Services Description Language (WSDL) Version 2.0 Part 2: Predefined Extensions, M. Gudgin, A. Lewis, and J. Schlimmer, Editors. World Wide Web Consortium, 3 August 2004. This version of the "Web Services Description Language (WSDL) Version 2.0 Part 2: Predefined Extensions" Specification is available at http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803. The latest version of "Web Services Description Language (WSDL) Version 2.0 Part 2: Predefined Extensions" is available at http://www.w3.org/TR/wsdl20-extensions.
[WSDL 2.0 Bindings]: Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings, H. Haas, P. Le Hégaret, J-J. Moreau, D. Orchard, J. Schlimmer, S. Weerawarana, Editors. World Wide Web Consortium, 3 August 2004. This version of the "Web Services Description Version 2.0: Bindings" Specification is available at http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803. The latest version of "Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings" is available at http://www.w3.org/TR/wsdl20-bindings.
[Web Architecture]: Architecture of the World Wide Web, Volume One, Ian Jacobs, Norman Walsh, Editors. W3C Technical Architecture Group, 15 December, 2004. Available at http://www.w3.org/TR/2004/REC-webarch-20041215/ .
[WS Architecture]: Web Services Architecture, David Booth, Hugo Haas, Francis McCabe, Eric Newcomer, Michael Champion, Chris Ferris, David Orchard, Editors. W3C Web Services Architecture Working Group, 11 February 2004. Available at http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/ .
[WS Glossary]: Web Services Glossary, Hugo Haas, Allen Brown, Editors. W3C Web Services Architecture Working Group, 11 February 2004. Available at http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/ .

8.2 Informative References

[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 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.
[SOAP 1.1]: Simple Object Access Protocol (SOAP) 1.1, D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. Frystyk Nielsen, S. Thatte, D. Winer, Editors. World Wide Web Consortium, 8 May 2000. This version of the Simple Object Access Protocol 1.1 Note is http://www.w3.org/TR/2000/NOTE-SOAP-20000508.
[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/.
[XML Linking]: XML Linking Language (XLink) Version 1.0, S. DeRose, E. Maler, D. Orchard, Editors. World Wide Web Consortium, 27 June 2001. This version of the XML Linking Language 1.0 Recommendation is http://www.w3.org/TR/2001/REC-xlink-20010627. The latest version of XML Linking Language 1.0 is available at http://www.w3.org/TR/xlink.
[WSDL 1.1]: Web Services Description Language (WSDL) 1.1, E. Christensen, F. Curbera, G. Meredith, and S. Weerawarana, Authors. World Wide Web Consortium, 15 March 2002. This version of the Web Services Description Language 1.1 Note is http://www.w3.org/TR/2001/NOTE-wsdl-20010315. The latest version of Web Services Description Language 1.1 is available at http://www.w3.org/TR/wsdl.
[WSD Requirements]: Web Services Description Requirements, J. Schlimmer, Editor. World Wide Web Consortium, 28 October 2002. This version of the Web Services Description Requirements document is http://www.w3.org/TR/2002/WD-ws-desc-reqs-20021028. The latest version of Web Services Description Requirements is available at http://www.w3.org/TR/ws-desc-reqs.
[XPointer Framework]: XPointer Framework,Paul Grosso, Eve Maler, Jonathan Marsh, Norman Walsh, Editors. World Wide Web Consortium, 22 November 2002. This version of the XPointer Framework Proposed Recommendation is http://www.w3.org/TR/2003/REC-xptr-framework-20030325/ The latest version of XPointer Framework is available at http://www.w3.org/TR/xptr-framework/.

Editorial note: KevinL	20040910
Add Example and more text - illustrate use of RPC style