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

2.1.1 Example Scenario: The GreatH Hotel Reservation Service

Hotel GreatH (a fictional hotel) 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. The Web service will return a room rate (a floating point number in USD$) if such a room is available, or a zero room rate if not. 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.

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.

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

  <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"
        xmlns="http://greath.example.com/2004/schemas/resSvc">

      <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/2006/01/wsdl/in-out" 
            style="http://www.w3.org/2006/01/wsdl/style/iri"
            wsdlx:safe = "true">
        <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/2006/01/wsdl/soap"
          wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
 
    <fault ref="tns:invalidDataFault" 
      wsoap:code="soap:Sender"/>

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

  </binding>

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

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

</description>

2.1.2 Defining a WSDL 2.0 Target Namespace

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

The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSDL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 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 2.0 target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.

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

  . . .
</description>

2.1.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 processors are likely 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 2.0 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.

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

  ...

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

      <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.1.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 2.0 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 Adjuncts] 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). We will explain more about message exchange patterns in 2.4.4.3 Understanding Message Exchange Patterns (MEPs)

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 Adjuncts] 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 2.0 document.

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

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

    <fault name = "invalidDataFault"
            element = "ghns:invalidDataError"/> 
   
    <operation name="opCheckAvailability" 
            pattern="http://www.w3.org/2006/01/wsdl/in-out"
            style="http://www.w3.org/2006/01/wsdl/style/iri"
            wsdlx:safe = "true">
        <input messageLabel="In" 
              element="ghns:checkAvailability" />
        <output messageLabel="Out" 
              element="ghns:checkAvailabilityResponse" />
        <outfault ref="tns:invalidDataFault" messageLabel="Out"/>
    </operation>

  </interface>

  . . .
</description>

2.1.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 extension, for example, defines some defaulting rules for operations. (See Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts [WSDL 2.0 Adjuncts], 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. (See 4.1 Extensibility for more on extensibility.) WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines binding extensions 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 2.0 documents. However, other specifications could define new binding extensions that could also be used to define bindings. (As with any extension, other WSDL 2.0 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.

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

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

  <binding name="reservationSOAPBinding" 
          interface="tns:reservationInterface"
          type="http://www.w3.org/2006/01/wsdl/soap"
          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/soap-response"/>
  
    <fault ref="tns:invalidDataFault" 
      wsoap:code="soap:Sender"/>

  </binding>

  . . .
</description>

2.1.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 to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See 5.4 Multiple Interfaces for the Same Service for further discussion of this limitation.)

Here is a definition for our GreatH service.

<?xml version="1.0" encoding="utf-8" ?> 
<description 
    xmlns="http://www.w3.org/2006/01/wsdl"
    targetNamespace= "http://greath.example.com/2004/wsdl/resSvc" 
    xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
    xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
    xmlns:wsoap= "http://www.w3.org/2006/01/wsdl/soap"
    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>
  
</description>

2.1.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 documentation 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 2.0 author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external 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 (see 2.2.1 WSDL 2.0 Infoset), though in this example we have only demonstrated its use at the beginning.

<?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>
  . . .  
</description>

2.2.1 WSDL 2.0 Infoset

The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.

Figure 2-1. WSDL 2.0 Infoset Diagram

2.2.2 WSDL 2.0 Schema

The WSDL 2.0 specification supplies a normative WSDL 2.0 schema, defined in [XML Schema: Structures], which can be used as an aid in validating WSDL 2.0 documents. We say "as an aid" here because WSDL 2.0 specification [WSDL 2.0 Core] often provides further constraints to the WSDL 2.0 schema. In addition to being valid with the normative schema, a WSDL 2.0 document must also follow all the constraints defined by the WSDL 2.0 specification.

<description>
  <documentation />?
  [ <import /> | <include /> ]*
  <types />?
  [ <interface /> | <binding /> | <service /> ]*
</description>

2.2.3 WSDL 2.0 Component Model

The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a component model as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.

Figure 2-2. WSDL 2.0 Components Containment hierarchy

In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the Description, Interface, Binding, Service and Endpoint components correspond to the description, interface, binding, service, and endpoint element information items, respectively. Since WSDL 2.0 relies heavily on the component model to convey the meaning of the constructs in the WSDL 2.0 language, you can think of the Description component as representing the meaning of the description element information item, and hence, it represents the meaning of the WSDL 2.0 document as a whole.

Furthermore, each of these components has properties whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the service element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the endpoint element information item children of that service element information item. (Whew!).

2.3.1 Inlining XML Schema

We have already seen an example of using inlined schema definitions in section 2.1.3 Defining Message Types. When XML Schema is inlined directly in a WSDL 2.0 document, it uses the existing top-level xs:schema element defined by XML Schema to do so, as though a schema file had been copied and pasted into the types element. The schema components defined in the inlined schema are then available to the containing WSDL 2.0 description for reference by QName. For instance, in Example 2-1, the input message of the interface operation "opCheckAvailability" is defined by the "ghns:checkAvailability" element in the inlined schema.

2.3.2 Importing XML Schema

XML Schema components can be defined in separate schema files and be made available to a WSDL2.0 description by using xs:import directly under types.

There are many cases where one would prefer having schema definitions in separate schema files. One reason is the reusability of the schema definitions. Inlined schema definitions are only available to the containing WSDL 2.0 description. Although WSDL 2.0 provides a wsdl:import mechanism for importing other WSDL files, schema definitions inlined in an imported WSDL document are NOT automatically made available to the importing WSDL 2.0 document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if one wishes to share schema definitions across several WSDL 2.0 descriptions, these schema definitions should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 description using xs:import directly under types.

Let's see an example. Assuming the message types in Example 2-3 are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be brought into the WSDL 2.0 description using xs:import. Note that only components in the imported namespace "http://greath.example.com/2004/schemas/resSvc" are available for reference in the WSDL 2.0 document.

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

<types>
        <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" 
                schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>  
</types>

. . .
</description>

It's important to note that xs:import used directly under wsdl:types has been given a different visibility than xs:import used inside an inlined schema. An inlined schema may use native XML schema xs:import to bring in external schema definitions that are in different namespaces; However, though this is the schema importing mechanism recommended for WSDL 1.1 in WS-I Basic Profile, according to XML Schema specification, such enclosed message definitions are only visible to the importing schema (in this case, the inlined schema). They are not visible to the containing WSDL 2.0 description.

If we change Example 2-8 to use XML Schema's native xs:import element in an inlined schema, the schema components defined in the namespace http://greath.example.com/2004/schemas/resSvc are not available to our example WSDL 2.0 definition any more.

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

<types>
        <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvcWrapper">
                <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" 
                schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>  
        </xs:schema>
</types>

. . .
</description>

Of course, an inlined XML schema may also use XML Schema's native xs:include element to refer to schemas defined in separate files when the included schema has no namespace or has the same namespace as the including schema. In this case, according to XML Schema, the included schema components become a part of the including schema as though they had been copied and pasted into the including schema. Hence, the included schema components are also available to the containing WSDL 2.0 description for reference by QName.

The following example has the same effect as Example 2-3:

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

<types>
        <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvc">
                <xs:include schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>  
        </xs:schema>
</types>

. . .
</description>

2.3.3 Summary of Import and Include Mechanisms

So far we have briefly covered both WSDL import/include and schema import/include. The following table summarizes the similarities and differences between the WSDL 2.0 and XML Schema include and import mechanisms. We will talk a lot more about importing mechanisms in 3.1 Importing WSDL and 3.2 Importing Schemas

2.4.1 Interface Syntax

Below is the XML syntax summary of the interface element, simplified by omitting optional <documentation> elements and <feature> and <property> extension elements:

<description targetNamespace="xs:anyURI" >

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

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

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

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

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

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

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

    </operation>*

  </interface>*
  . . .

</description>
  

The interface element has two optional attributes: styleDefault and extends . The styleDefault attribute can be used to define a default value for the style attributes of all operations under this interface (see WSDL 2.0 Part 1 "styleDefault attribute information item"). The extends attribute is for inheritance, and is explained next.

2.4.2 Interface Inheritance

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

First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must NOT themselves extend that interface either directly or indirectly.

Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 [WSDL 2.0 Core] " Equivalence of Components ") then they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendants.) In the second case, if two operations have the same name in the same WSDL 2.0 target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely.

Finally, since faults can also be defined as children of the interface element (as described in the following sections), the same name-collision rules apply to those constructs.

Let's say the GreatH hotel wants to maintain a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service, the content of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a messageLog element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the reservationInterface now contains two operations: opCheckAvailability and opLogMessage

                                        
<description ...>
        ...
        <interface  name = "messageLogInterface" >
                                
                <operation name="opLogMessage" 
                                pattern="http://www.w3.org/2006/01/wsdl/out-only">
                        <output messageLabel="out" 
                                element="ghns:messageLog" />
                </operation>

        </interface>

        <interface  name="reservationInterface" extends="tns:messageLogInterface" >
   
                <operation name="opCheckAvailability" 
                                pattern="http://www.w3.org/2006/01/wsdl/in-out"
                                style="http://www.w3.org/2006/01/wsdl/style/iri"
                                wsdlx:safe = "true">
                        <input messageLabel="In" 
                                element="ghns:checkAvailability" />
                        <output messageLabel="Out" 
                                element="ghns:checkAvailabilityResponse" />
                        <outfault ref="tns:invalidDataFault" messageLabel="Out"/>

                </operation>
        </interface>
        ...
</description>

Now let's have a look at the element children of interface, beginning with fault.

2.4.3 Interface Faults

The fault element is used to declare faults that may occur during execution of operations of an interface. They are declared directly under interface, and referenced from operations where they apply, in order to permit reuse across multiple operations.

Faults are very similar to messages and can be viewed as a special kind of message. Both faults and messages may carry a payload that is normally described by an element declaration. However, WSDL 2.0 treats faults and messages slightly differently. The messages of an operation directly refer to their element declaration, however the faults of an operation indirectly refer to their element declaration via a fault element that is defined on the interface.

The reason for defining faults at the interface level is to allow their reuse across multiple operations. This design is especially beneficial when bindings are defined, since in binding extensions like SOAP there is additional information that is associated with faults. In the case of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with them, thereby ensuring consistency across all operations that use the faults

The fault element has a required name attribute that must be unique within the parent interface element, and permits it to be referenced from operation declarations. The optional element attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the types section. Please note that when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL 2.0's attribute extension mechanism to allow the schema to be associated with the fault.

2.4.4 Interface Operations

As shown earlier, the operation element is used to indicate an operation supported by the containing interface. It associates message schemas with a message exchange pattern (MEP), in order to abstractly describe a simple interaction with a Web service.

                                        
<description ...>
        ...
        <interface  name="reservationInterface">
                ...
                <operation name="opCheckAvailability" ... >
                
                <operation name="opLogInquiry" 
                                pattern="http://www.w3.org/2006/01/wsdl/out-only">
                        <output messageLabel="Out" element="ghns:customerData" />
                </operation>

        </interface>
        ...
</description>

2.5.1 Syntax Summary for Bindings

Since bindings are specified using extensions to the WSDL 2.0 language (i.e., binding extensions are not in the WSDL 2.0 namespace), the XML for expressing a binding will consist of a mixture of elements and attributes from WSDL 2.0 namespace and from the binding extension's namespace, using WSDL 2.0's open content model.

Here is a syntax summary for binding, simplified by omitting optional documentation, feature and property elements. Bear in mind that this syntax summary only shows the elements and attributes defined within the WSDL 2.0 namespace. When an actual binding is defined, elements and attributes from the namespace of the desired binding extension will also be intermingled as required by that particular binding extension.

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

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

    <operation ref="xs:QName" >
      <input messageLabel="xs:NCName"? > </input>*
      <output messageLabel="xs:NCName"? > </output>*
      <infault ref="xs:QName" messageLabel="xs:NCName"? > </infault>*
      <outfault ref="xs:QName" messageLabel="xs:NCName"? > </outfault>*
    </operation>*

  </binding>*
  . . .
</description>

The binding syntax parallels the syntax of interface: each interface construct has a binding counterpart. Despite this syntactic similarity, they are indeed different constructs, since they are in different symbol spaces and are designed for different purposes.

2.5.2 Reusable Bindings

A binding can either be reusable (applicable to any interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in 2.1.5 Defining a Binding.

To define a reusable binding, the binding element simply omits the interface attribute and omits specifying any operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.

2.5.3 Binding Faults

A binding fault associates a concrete message format with an abstract fault of an interface. It describes how faults that occur within a message exchange of an operation will be formatted, since the fault does not occur by itself. Rather, a fault occurs as part of a message exchange specified 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.

2.5.4 Binding Operations

A binding operation describes a concrete binding of an interface operation to a concrete message format. An interface operation is uniquely identified by the WSDL 2.0 target namespace of the interface and the name of the operation within that interface, via the required ref attribute of binding operation. As with faults, for each operation within a binding, the value of the ref attribute must be unique.

2.5.5 The SOAP Binding Extension

The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts]) was primarily designed to support the features of SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework]. However, for backwards compatibility, it also provides some support for SOAP 1.1 [SOAP 1.1].

An example using the WSDL 2.0 SOAP binding extension was already presented in 2.1.5 Defining a Binding, but some additional points are worth mentioning:

• Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a wsoap:version attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.

• The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a given interface defines any faults, then corresponding binding information must be explicitly provided for each such fault.

• If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See 2.5.7 HTTP GET Versus POST: Which to Use?.)

Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.

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

 ....

  <!-- SOAP 1.2 Binding -->
  <binding name="reservationSOAPBinding" 
    interface="tns:reservationInterface"
    type="http://www.w3.org/2006/01/wsdl/soap"
    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>
  
  <!-- SOAP 1.1 Binding -->
  <binding name="reservationSOAP11Binding" 
    interface="tns:reservationInterface"
    type="http://www.w3.org/2006/01/wsdl/soap"
    wsoap:version="1.1"
    wsoap:protocol="http://www.w3.org/2006/01/soap11/bindings/HTTP">
  
    <operation ref="tns:opCheckAvailability"/>
  
    <fault ref="tns:invalidDataFault" 
      wsoap:code="soap11:Client"/>

  </binding>


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

    <!-- SOAP 1.2 End Point -->
    <endpoint name="reservationEndpoint" 
      binding="tns:reservationSOAPBinding"
      address="http://greath.example.com/2004/reservation"/>

    <!-- SOAP 1.1 End Point -->
    <endpoint name="reservationEndpoint2"
      binding="tns:reservationSOAP11Binding"
      address="http://greath.example.com/2004/reservation"/>
  
  </service>  
</description>

2.5.6 The HTTP Binding Extension

In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines a binding extension for HTTP 1.1 [IETF RFC 2616] and HTTPS [IETF RFC 2818], so that these protocols can be used natively to send and receive messages, without first encoding them in SOAP.

The HTTP binding extension provides many features to control:

• Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP operations are supported.)

• Input, output and fault serialization

• Transfer codings

• Authentication requirements

• Cookies

• HTTP over TLS (https)

As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also provides defaulting rules to permit binding information to be specified at the interface level and used by default for each operation in the affected interface, however, defaulting rules are not provided for binding faults.

Here is an example of using the HTTP binding extension to check hotel room availability at GreatH.

<?xml version="1.0" encoding="utf-8" ?> 
<description xmlns="http://www.w3.org/2006/01/wsdl"
      . . .
      xmlns:whttp="http://www.w3.org/2006/01/wsdl/http" >

  . . .
  <binding name="reservationHTTPBinding"
      interface="tns:reservationInterface"
      type="http://www.w3.org/2006/01/wsdl/http"
      whttp:methodDefault="GET">

    <operation ref="tns:opCheckAvailability"
      whttp:location="{checkInDate}"  />
  </binding>

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

    <!-- HTTP 1.1 GET End Point -->
    <endpoint name="reservationEndpoint"
      binding="tns:reservationHTTPBinding"
      address="http://greath.example.com/2004/checkAvailability/"/>

  </service>
  . . .
</description>

. . .
<operation ref="tns:opCheckAvailability"
    whttp:location="bycheckInDate/{checkInDate/}"  >
. . .

2.5.7 HTTP GET Versus POST: Which to Use?

When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled URIs, Addressability, and the use of HTTP GET and POST ([W3C TAG Finding: Use of HTTP GET]). From the abstract:

". . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations."

Recall that the concept of a safe operation was discussed in 2.4.4.1 Operation Attributes. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the wsdlx:safe attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level:

• If the WSDL 2.0 SOAP binding extension is used (2.5.5 The SOAP Binding Extension), with HTTP as the underlying transport protocol, then GET may be specified by setting:

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

  on the binding element (to indicate the use of HTTP as the underlying protocol); and

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

  on the binding operation element, which causes GET to be used by default.

• If the WSDL 2.0 HTTP binding extension is used directly (2.5.6 The HTTP Binding Extension), GET may be specified by setting either:

  whttp:methodDefault="GET"

  on the binding element; or

  whttp:method="GET"

  on the binding operation element, which overrides whttp:methodDefault if set on the binding element; or

  wsdlx:safe="true"

  on the bound interface operation . When the above two items are not explicitly set, and when the bound interface operation is marked safe, the HTTP Binding will by default set the method to GET.

For example, in the GreatH interface definition shown in Example 2-4, the wsdlx:safe attribute is set to "true". The HTTP binding definition in Example 2-14 may take advantage of that and be simplified as below and still have the http method set to GET by default:

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

<binding name="reservationHTTPBinding"

      interface="tns:reservationInterface"

      type="http://www.w3.org/2006/01/wsdl/http" >

    <operation ref="tns:opCheckAvailability"

        whttp:location="{checkInDate}"/>

  </binding>

3.2.1 Schemas in Imported Documents

In this example, we consider some GreatH Hotel Web services that retrieve and update reservation details. The retrieval Web service is defined in the retrieveDetails.wsdl WSDL 2.0 document, along with a schema for the message format. The updating Web service is defined in the updateDetails.wsdl WSDL 2.0 document which imports the first document and refers to both WSDL 2.0 and schema definitions contained in the imported document.

Example 3-3 shows the definition of the retrieval Web service in the http://greath.example.com/2004/services/retrieveDetails namespace. This WSDL 2.0 document also contains an inline schema that describes the reservation detail in the http://greath.example.com/2004/schemas/reservationDetails namespace. This schema is visible to the retrieveDetailsInterface interface definition which refers to it in the retrieve operation's output message.

                                                        <?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Retrieve Reservation Details
                Web service.
        </documentation>

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

                        <xs:element name="reservationDetails">
                                <xs:complexType>
                                        <xs:sequence>
                                                <xs:element name="confirmationNumber"
                                                        type="string" />
                                                <xs:element name="checkInDate" type="date" />
                                                <xs:element name="checkOutDate" type="date" />
                                                <xs:element name="roomType" type="string" />
                                                <xs:element name="smoking" type="boolean" />
                                        </xs:sequence>
                                </xs:complexType>
                        </xs:element>
                </xs:schema>
        </types>

        <interface name="retrieveDetailsInterface">

                <operation name="retrieve"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="#none" />
                        <output messageLabel="Out"
                                element="wdetails:reservationDetails" />
                </operation>

        </interface>

</description>
                                                

Example 3-4 shows the definition of the updating Web service in the http://greath.example.com/2004/services/updateDetails namespace. The updateDetailsInterface interface extends the retrieveDetailsInterface interface. However, the retrieveDetailsInterface belongs to the http://greath.example.com/2004/services/retrieveDetails namespace, so updateDetails.wsdl must import retrieveDetails.wsdl to make that namespace visible.

The updateDetailsInterface interface also uses the reservationDetails element definition that is contained in the inline schema of the imported retrieveDetails.wsdl document. However, this schema is not automatically visible within the updateDetails.wsdl document. To make it visible, the updateDetails.wsdl document must import the namespace of the inline schema within the types element using the XML schema import element.

In this example, the schemaLocation attribute of the import element has been omitted. The schemaLocation attribute is a hint to the WSDL 2.0 processor that tells it where to look for the imported schema namespace. However, the WSDL 2.0 processor has already processed the retrieveDetails.wsdl document which contains the imported namespace in an inline schema so it should not need any hints. However, this behavior depends on the implementation of the processor and so cannot be relied on.

Although the WSDL 2.0 document may validly omit the schemaLocation attribute, it is a best practice to either provide a reliable value for it or move the inline schema into a separate document, say reservationDetails.xsd, and directly import it in the types element of both retrieveDetails.wsdl and updateDetails.wsdl. In general, schemas that are expected to be referenced from more than one WSDL 2.0 document should be defined in a separate schema document rather than be inlined.

<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/updateDetails"
        xmlns:tns="http://greath.example.com/2004/services/updateetails"
        xmlns:retrieve="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Update Reservation Details
                Web service.
        </documentation>

        <import
                namespace="http://greath.example.com/2004/services/retrieveDetails"
                location="retrieveDetails.wsdl" />

        <types>
                <xs:import
                        namespace="http://greath.example.com/2004/schemas/reservationDetails" />
        </types>

        <interface name="updateDetailsInterface"
                extends="retrieve:retrieveDetailsInterface">

                <operation name="update"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In"
                                element="details:reservationDetails" />
                        <output messageLabel="Out"
                                element="details:reservationDetails" />
                </operation>

        </interface>

</description>

3.2.2 Multiple Inline Schemas in One Document

A WSDL 2.0 document may define multiple inline schemas in its types element. The two or more schemas may have the same target namespace provided that they do not define the same elements or types. It is an error to define the same element or type more than once, even if the definitions are identical.

Each namespace of an inline schema becomes visible to the Web service definitions. However, the namespaces are not automatically visible to the other inline schemas. Each inline schema must explicitly import any other namespace it references. The schemaLocation attribute is not required in this case since the WSDL 2.0 processor knows the location of each schema by virtue of having processed the enclosing WSDL 2.0 document.

To illustrate this, consider Example 3-5 which contains two inline schemas. The http://greath.example.com/2004/schemas/reservationItems namespace contains some elements for items that appear in the reservation details. The http://greath.example.com/2004/schemas/reservationDetails namespace contains the reservationDetails element which refers to the item elements. The schema for the http://greath.example.com/2004/schemas/reservationDetails namespace contains an import element that imports the http://greath.example.com/2004/schemas/reservationItems namespace. No schemaLocation attribute is required for this import since the schema is defined inline in the importing document.

<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Retrieve Reservation Details
                Web service.
        </documentation>

        <types>

                <xs:schema targetNamespace="http://greath.example.com/2004/schemas/reservationItems">

                        <xs:element name="confirmationNumber" type="string" />
                        <xs:element name="checkInDate" type="date" />
                        <xs:element name="checkOutDate" type="date" />
                        <xs:element name="roomType" type="string" />
                        <xs:element name="smoking" type="boolean" />

                </xs:schema>

                <xs:schema targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
                        xmlns:items="http://greath.example.com/2004/schemas/reservationItems">

                        <xs:import
                                namespace="http://greath.example.com/2004/schemas/reservationItems" />

                        <xs:element name="reservationDetails">
                                <xs:complexType>
                                        <xs:sequence>
                                                <xs:element ref="items:confirmationNumber" />
                                                <xs:element ref="items:checkInDate" />
                                                <xs:element ref="items:checkOutDate" />
                                                <xs:element ref="items:roomType" />
                                                <xs:element ref="items:smoking" />
                                        </xs:sequence>
                                </xs:complexType>
                        </xs:element>
                </xs:schema>

        </types>

        <interface name="retrieveDetailsInterface">

                <operation name="retrieve"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="#none" />
                        <output messageLabel="Out"
                                element="wdetails:reservationDetails" />
                </operation>

        </interface>

</description>

3.2.3 The schemaLocation Attribute

In the preceding examples, schemas were defined inline in WSDL 2.0 documents. This section discusses the correct way to specify a schemaLocation attribute on a schema import element to provide a processor with a hint for locating these schemas.

Example 3-4 shows how one WSDL 2.0 document imports a schema defined in another, i.e. Example 3-3. Similarly, Example 3-5 shows how one schema in a WSDL 2.0 document imports another schema defined in the same document. In both of these examples, the schemaLocation attribute was omitted since the WSDL 2.0 processor was assumed to know how to locate the imported schemas because they were part of the WSDL 2.0 documents being processed. The schemaLocation attribute can be used to give the processor a URI reference that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify the schema element. The simplest way to accomplish this is to use the id attribute, however XPointer (see [XPointer Framework]) can also be used.

<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:tns="http://greath.example.com/2004/services/retrieveDetails"
        xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Retrieve Reservation Details
                Web service.
        </documentation>

        <types>

                <xs:schema id="items"
                        targetNamespace="http://greath.example.com/2004/schemas/reservationItems">

                        <xs:element name="confirmationNumber" type="string" />
                        <xs:element name="checkInDate" type="date" />
                        <xs:element name="checkOutDate" type="date" />
                        <xs:element name="roomType" type="string" />
                        <xs:element name="smoking" type="boolean" />

                </xs:schema>

                <xs:schema id="details"
                        targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
                        xmlns:items="http://greath.example.com/2004/schemas/reservationItems">

                        <xs:import
                                namespace="http://greath.example.com/2004/schemas/reservationItems"
                                schemaLocation="#items" />

                        <xs:element name="reservationDetails">
                                <xs:complexType>
                                        <xs:sequence>
                                                <xs:element ref="items:confirmationNumber" />
                                                <xs:element ref="items:checkInDate" />
                                                <xs:element ref="items:checkOutDate" />
                                                <xs:element ref="items:roomType" />
                                                <xs:element ref="items:smoking" />
                                        </xs:sequence>
                                </xs:complexType>
                        </xs:element>
                </xs:schema>

        </types>

        <interface name="retrieveDetailsInterface">

                <operation name="retrieve"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="#none" />
                        <output messageLabel="Out"
                                element="wdetails:reservationDetails" />
                </operation>

        </interface>

</description>

4.1.1 Optional Versus Required Extensions

Extensions can either be required or optional.

An optional extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute wsdl:required="false" or the absence of the wsdl:required attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the client -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document.

A required extension is one that must be supported and engaged by the client in order for the interaction to proceed properly, and is signaled by attribute wsdl:required="true". If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor.

4.2.1 SOAP Modules

The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:

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

  <endpoint name="reservationEndpoint" 
            binding="tns:reservationSOAPBinding"
            address ="http://greath.example.com/2004/reservation">
    <wsoap:module uri="http://features.example.com/2005/modules/Security"
              required="true"/>
  </endpoint>
        
</service>
. . .

This syntax indicates that a SOAP Module is required by this endpoint. This means that anyone using this endpoint must both understand the specification that the module URI references, and must use that specification when communicating with the endpoint in question, which typically means including appropriate SOAP headers on transmitted messages.

If the "required" attribute was not present, or if it was set to "false", then the <wsoap:module> syntax would indicate optional the availability of the referenced module, rather than a requirement to engage it, as explained in 4.1.1 Optional Versus Required Extensions.

4.2.2 Abstract Features

Since GreatH began the web service improvements, they have been talking to several travel agents. The possibility of making their simple hotel interface an industry standard amongst a consortium of hotels has come up, and as such they would like to enable specifying the requirement for the "makeReservation" operation to be secure at the interface level – in other words indicating that the operation must be secure, but without specifying exactly how that should concretely be achieved (to enable maximal reuse of the interface). The next example uses the WSDL 2.0 Feature element to indicate this.

. . .
<interface name="reservationInterface">
 <operation name="makeReservation">
  <feature uri="http://features.example.com/2005/securityFeature"
           required="true"/>
  . . . [The rest of the operation is unchanged] . . .
 </operation>
</interface>
. . .

This declaration indicates that understanding of, and compliance with, the specified security feature is required for all uses of the "makeReservation" operation. The security feature is abstract, which means that although it defines semantics and a level of detail about its general operation, it expects a concrete component (like a SOAP module or binding) to actually realize the functionality.

By definition, if you understand a SOAP module, you understand which (if any) abstract features it implements. Therefore, since the security module in this example is defined as an implementation of the abstract security feature, we know that the use of this module satisfies the requirement to implement the feature. Therefore users of the HTTP endpoint shown above (with the required SOAP module) will be able to make use of it. GreatH also defines a new endpoint:

. . .
<binding name="reservationSecureSOAPBinding"
    interface="tns:reservationInterface"
    type="http://www.w3.org/2006/01/wsdl/soap"
    wsoap:protocol="http://bindings.example.com/SOAPBindings/secureHTTP">
  . ..
</binding>
. . .
<service name="reservationService">
  . . .
  <endpoint name="secureReservationEndpoint"
            binding="tns:reservationSecureSOAPBinding"
            address="https://greath.example.com/2004/secureReservation"/>
</service>
. . .

The user will have a choice as to which of the endpoints, and therefore which binding, is to be used, but they both satisfy the abstract feature requirement specified in the interface.

Note that it is not necessary to declare the abstract feature in order to use/require the SOAP module, or in order to use/require the secure binding. Abstract feature declarations serve purely to indicate requirements which must be fulfilled by more concrete components such as modules or bindings. In other words, the abstract feature declaration allows components such as interfaces to be reused without caring exactly which SOAP modules or bindings satisfy the feature.

4.2.3 Properties

So far we've discussed how to indicate the availability or the "requiredness" of features and modules. Often it is not enough to indicate that a particular extension is available/required: you also need some way to control or parameterize aspects of its behavior. This is achieved by the use of WSDL 2.0 properties. Each feature, SOAP module, or SOAP binding may express a variety of properties in its specification. These properties are very much like variables in a programming language. If GreatH would like to indicate that the securityLevel property should be 5 for the "makeReservation" operation, it would look like this:

. . .
<interface name="reservationInterface">
 <operation name="makeReservation">
  <property
      uri="http://features.example.com/2005/securityFeature/securityLevel">
   <value>5</value>
  </property>
  . . . [rest of operation definition] . . .
 </operation>
</interface>
. . .

The property element specifies which property is to be set. By setting the value element, a toolkit processing this WSDL 2.0 document is informed that the securityLevel property must be set to 5. The particular meanings of any such values are up to the implementations of the modules/bindings that use them. The property element can be placed at many different levels in a WSDL 2.0 document (see "Property Composition Model" section in WSDL 2.0 Part 1 [WSDL 2.0 Core]).

It is also possible to provide a constraint on the value space for a given property. This allows the author of the WSDL 2.0 document to indicate that several valid values for the property are possible for a given scope, limiting the value space already described in the specification that defined the property. Let's extend our example to make this clearer.

The security feature specification defines securityLevel as an integer with values between 1 and 10, each of which indicates, according to the spec, a progressively higher level of security. The GreatH service authors, having read the relevant specifications, have decided that any security level between 3 and 7 will be supported by their infrastructure. Levels less than 3 are deemed unsafe for GreatH's purposes, and levels greater than 7 require too much in the way of resources to make it worthwhile. We can express this in WSDL 2.0 as follows:

. . .
<types>
 <schema>
  <simpleType name="securityLevelConstraint">
   <restriction base="xs:int">
    <min 3, max 7> <!-- check schema for syntax -->
   </restriction>
  </simpleType>
 </schema>
</types>
. . .
<property uri="http://features.example.com/2005/securityFeature/securityLevel">
  <constraint type="tns:securityLevelConstraint"/>
</property>
. . .

First we define, in the types section, an XML Schema restriction type over integers with minimum and maximum values, per our discussion above. Then instead of using the value element inside property, we use constraint and refer to the restriction type. This informs the implementation that the property must have the appropriate values. This information might be useful to a deployment user interface, for example, which might allow an administrator to set this value with a slider when deploying the service.

4.3.1 Confirmed Challenge

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

1. A message:

   • indicated by a Message Label component whose message label is "Request" and direction is "in"

   • received from some node N1

2. A message:

   • indicated by a Message Label component whose message label is "Challenge" and direction is "out"

   • sent to some node N2 (which may be the same node as N1)

3. An optional message:

   • indicated by a Message Label component whose message label is "Confirmation" and direction is "in"

   • received from node N2

4. An optional message:

   • indicated by a Message Label component whose message label is "Response" and direction is "out"

   • sent to node N2

This pattern uses the rule Message Triggers Fault.

An operation using this message exchange pattern has a pattern property with the value "http://www.example.com/webservices/meps/confirmed-challenge".

Once the MEP had been defined (and the email binding specification appropriately modified to indicate that this was a supported MEP), the service was redefined and redeployed. Only the changed operations are shown in the excerpt below.

<?xml version="1.0" encoding="utf-8" ?>
<description xmlns="http://www.w3.org/2006/01/wsdl"
      targetNamespace="http://greath.example.com/2004/wsdl/weathSvc.wsdl"
      xmlns:tns="http://greath.example.com/2004/wsdl/weathSvc.wsdl"
      xmlns:wsoap="http://www.w3.org/2006/01/wsdl/soap"
      xmlns:email="http://www.example.com/webservices/email" >

   . . .

    <interface name="weatherInterface">
        <operation name="opSubscribeWeather"
                   pattern="http://www.example.com/webservices/meps/confirmed-challenge">
            <input messageLabel="Request" element=". . ." />
            <output messageLabel="Challenge" element=". . ." />
            <input messageLabel="Confirmation" element=". . ." />
            <output messageLabel="Response" element=". . ." />
        </operation>
        <operation name="opUnsubscribeWeather"
                   pattern="http://www.example.com/webservices/meps/confirmed-challenge">
            <output messageLabel="Challenge" element=". . ." />
            <output messageLabel="Response" element=". . ." />
            <input messageLabel="Confirmation" element=". . ." />
            <input messageLabel="Request" element=". . ." />
        </operation>
        . . .
    </interface>

    . . .

</description>

Note: in the second example, the input and output examples are not in the sequence in which they occur in the pattern; this illustrates that the sequence is not significant. Note, however, that for this pattern, the messageLabel attribute is required on every input and output element.

5.2.1 Compatible Evolution

In compatible evolution, designers are expected to limit changes to those that are either backward or forward compatible, or both:

Backward compatible

The receiver behaves correctly if it receives a message in an older version of the interaction language.

Forward compatible

The receiver behaves correctly if it receives a message in a newer version of the interaction language.

Since Web services and their clients both send and receive messages, these concepts can apply to both parties. However, since WSDL 2.0 is service-centric, we will focus on the case of service evolution.

There are three critical areas in which a service described in WSDL 2.0 my evolve:

• The service now also supports additional binding. In compatible evolution, this should be a safe addition, given that adding a new binding should not impact any existing interactions using another transport.

• An interface supports new operations. Again, in compatible evolution this is usually safe, given that adding an additional operation to an abstract interface should not impact any existing interactions.

• The message bodies may include additional data. How the message contents may change within a description depends to a large extent upon the type system being used to describe the message contents. RelaxNG [RELAX NG] has good support for describing vocabularies that ignore unknown XML, as does OWL/RDF. XML Schema 1.0 has limited support for extending the description of a message via the xs:any and xs:anyAttribute constructs. XML Schema 1.1 has been chartered to provide "changes necessary to provide better support for versioning of schemas", and it is anticipated that this may include improved support for more "open content" and therefore better support for compatible evolution of messages.

• The protocol used to exchange messages may provide mechanisms for exchanging data outside of the message body. In the case of SOAP, the WSDL 2.0 binding provides the ability to describe application data to be exchanged as headers. The SOAP processing model has a very good extensibility model with unknown headers being ignored by a receiver by default. There is also a mechanism whereby headers which are required as a part of an incompatible change may be marked with a 'mustUnderstand' flag. Passing additional items as headers may be the only way to compatibly evolve messages with fixed bodies.

5.2.2 Big Bang

The big bang approach to versioning is the simplest to currently represent in WSDL 2.0. In this approach, any change to a WSDL 2.0 document implies a change to the document's namespace, a change to the interface implies a new interface namespace and a change to the message contents is communicated using a new message namespace. This approach has particular benefits where an agent may quickly tell if a service has changed by simply comparing the namespace value.

5.2.3 Evolving a Service

Compatible changes are far more easily managed than incompatible ones:

• With a compatible change the service need only support the latest version of a service. A client may continue to use a service adjusting to new version of the interface description at a time of its choosing.

• With an incompatible change, the client receives a new version of the interface description and is expected to adjust to the new interface before old interface is terminated. Either the service will need to continue to support both versions of the interface during the hand over period, or the service and the clients are coordinated to change at the same time. An alternative is for the client to continue until it encounters an error, at which point it uses the new version of the interface.

5.2.4 Combined Approaches

It is feasible to combine the "compatible evolution" and "big bang" approaches in a variety of different ways. For example, the namespace could be changed when message descriptions are changed, but the namespace could stay the same when new operations are added.

While the big bang approach is currently the easiest to implement in WSDL 2.0, it can lead to a large number of cloned interfaces that become difficult to manage, thus making the compatible approach preferable to many for widely distributed systems. In the end, the choice of a versioning strategy for Web services described in WSDL 2.0 is left as an exercise to the reader.

5.2.5 Examples of Versioning and Extending a Service

<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:element  name="numberOfGuests" type="xs:integer" minOccurs="0"/>
      <xs:any namespace="##other" processContents="lax"/>
    </xs:sequence>
</xs:complexType>     
        

<xs:element name="NumberOfGuests" type="tNumberOfGuests"/>
<xs:complexType name="tNumberOfGuests">     
    <xs:sequence>      
        <xs:element  name="numberOfGuests" type="xs:integer" minOccurs="0"/>
    </xs:sequence>
</xs:complexType>

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

    <operation ref="tns:opCheckAvailability">
       <input>
         <wsoap:header element="tns:NumberOfGuests"/>
       </input>
    </operation>
...
</binding>
    

<xs:complexType name="tCheckAvailabilityV2">     
    <xs:sequence>      
    <xs:element  name="checkInDate" type="xs:date"/>      
    <xs:element  name="checkOutDate" type="xs:date"/>      
    <xs:element  name="roomType" type="xs:string"/>
    <xs:element  name="numberOfGuests" type="xs:integer"/>
    <xs:any namespace="##other" processContents="lax"/>
    </xs:sequence>
</xs:complexType>     
            

<interface name="reservationWithConfirmation" extends="cc:creditCardFaults">
    ... 
    <operation name="makeReservation">
        <input messageLabel="In" element="ghns:makeReservation" />
        <output messageLabel="Out" element="ghns:makeReservationResponse" />
        <outfault ref="invalidDataFault" messageLabel="Out" />
        <outfault ref="cc:cancelledCreditCard" messageLabel="Out" />
        <outfault ref="cc:expiredCreditCard" messageLabel="Out" />
        <outfault ref="cc:invalidCreditCardNumber" messageLabel="Out" />
        <outfault ref="cc:invalidExpirationDate" messageLabel="Out" />
    </operation>
    <operation name="confirmReservation">
        <input messageLabel="In" element="ghns:makeReservationResponse" />
        <output messageLabel="Out" element="ghns:confirmReservationResponse" />
        <outfault ref="expiredReservation" messageLabel="Out" />
    </operation>
</interface>
            

<binding name="reservationSOAPBinding" 
        interface="tns:reservationInterface"
        type="http://www.w3.org/2006/01/wsdl/soap"
        wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
    <operation ref="tns:makeReservation"
        wsoap:action="tns:makeReservationV2"/>
    . . .
            

<xs:element name="ghns2:makeReservation" type="ghns:tmakeReservation"/>

<interface . . .>

   <operation name="makeReservation">

       <input messageLabel="In" element="ghns2:makeReservation" />

</interface>
    

5.3.1 The Reservation Details Web Service

When designing a Web application it is natural to give each important concept a URI. In the GreatH hotel reservation system, the important concepts are reservations, so we begin our design by assigning a URI to each reservation. Since each reservation has a unique confirmation number, e.g OMX736, we create a URI for each reservation by appending the confirmation number to a base URI, e.g. http://greath.example.com/2004/reservation/OMX736. This URI will be the endpoint address for a Reservation Details Web service that can retrieve and update the state of a reservation. Example 5-7 shows the format of the reservation detail.

<?xml version="1.0" encoding="UTF-8"?>
<reservationDetails
        xmlns="http://greath.example.com/2004/schemas/reservationDetails">

        <confirmationNumber>OMX736</confirmationNumber>
        <checkInDate>2005-06-01</checkInDate>
        <checkOutDate>2005-06-03</checkOutDate>
        <roomType>single</roomType>
        <smoking>false</smoking>

</reservationDetails>

The Reservation Details Web service provides operations for retrieving and updating the detail for a reservation. Example 5-8 shows the description for this Web service. Note that there is no service element in this description since the set of reservations is dynamic. Instead, the endpoints for the reservations will be returned by querying the Reservation List Web service.

<?xml version="1.0" encoding="utf-8" ?>
<description 
        xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/reservationDetails"
        xmlns:tns="http://greath.example.com/2004/services/reservationDetails"
        xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:wsoap="http://www.w3.org/2006/01/wsdl/soap"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Reservation Details Web
                services. Use these services to retrieve or update reservation
                details. Each reservation has its own service and endpoint. To
                obtain the reference for a reservation service, make a request to
                the GreatH Reservation List Web service. See
                reservationList.wsdl for a description of the Reservation List
                Web service.
        </documentation>

        <types>
                <xs:import
                        namespace="http://greath.example.com/2004/schemas/reservationDetails"
                        schemaLocation="reservationDetails.xsd" />
        </types>

        <interface name="reservationDetailsInterface">

                <operation name="retrieve"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="#none" />
                        <output messageLabel="Out"
                                element="wdetails:reservationDetails" />
                </operation>

                <operation name="update"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In"
                                element="wdetails:reservationDetails" />
                        <output messageLabel="Out"
                                element="wdetails:reservationDetails" />
                </operation>

        </interface>

        <binding name="reservationDetailsSOAPBinding"
                interface="tns:reservationDetailsInterface"
                type="http://www.w3.org/2006/01/wsdl/soap"
                wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">

                <operation ref="tns:retrieve"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

                <operation ref="tns:update"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

        </binding>

</description>

Example 5-9 shows the XML schema elements that are used in this Web service.

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:tns="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:wdetails="http://greath.example.com/2004/services/reservationDetails"
        xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance"
        xmlns:wsdlx="http://www.w3.org/2006/01/wsdl-extensions"
        wsdli:wsdlLocation="http://greath.example.com/2004/services/reservationDetails reservationDetails.wsdl">

        <element name="confirmationNumber" type="string" />

        <element name="checkInDate" type="date" />

        <element name="checkOutDate" type="date" />

        <element name="reservationDetails">
                <complexType>
                        <sequence>
                                <element ref="tns:confirmationNumber" />
                                <element ref="tns:checkInDate" />
                                <element ref="tns:checkOutDate" />
                                <element name="roomType" type="string" />
                                <element name="smoking" type="boolean" />
                        </sequence>
                </complexType>
        </element>

        <simpleType name="reservationDetailsSOAPEndpointType" wsdlx:binding="wdetails:reservationDetailsSOAPBinding">
                <restriction base="anyURI"/>
        </simpleType>

        <element name="reservationDetailsSOAPEndpoint" type="tns:reservationDetailsSOAPEndpointType" />

        <element name="reservationDetailsService">
                <annotation>
                        <documentation>
                                This element contains references to the Reservation
                                Details Web Service endpoints for this reservation.
                        </documentation>
                </annotation>
                <complexType>
                        <sequence>
                                <element name="soap" type="tns:reservationDetailsSOAPEndpointType"/>
                                <element name="secure-soap" type="tns:reservationDetailsSOAPEndpointType"/>
                        </sequence>
                </complexType>
        </element>

</schema>

This XML schema contains the usual definitions for the elements that appear in the messages of the Web service. For example, the reservationDetails element is used in the messages of the retrieve and update operations. In addition, the schema defines the simple type reservationDetailsSOAPEndpointType which is based on xs:anyURI and has the annotation wsdlx:binding = "wdetails:reservationDetailsSOAPBinding" which means that the URI is the address of a Reservation Details Web service endpoint that implements the wdetails:reservationDetailsSOAPBinding binding. Note that the wsdli:wsdlLocation attribute is used to define the location of the WSDL 2.0 document that defines the wdetails:reservationDetailsSOAPBinding binding. This annotated simple type is used to define the reservationDetailsSOAPEndpoint element which will be used in the Reservation List service.

5.3.2 The Reservation List Web Service

Since the set of reservations changes as reservations are made and cancelled, the Reservation Detail endpoints are not described in a fixed WSDL 2.0 document. Instead they are returned as references to endpoints in response to requests made on a Reservation List Web service. The endpoint address for the Reservation List service will be http://greath.example.com/2004/reservationList.

Example 5-10 shows the format of the response from the Reservation List service.

<?xml version="1.0" encoding="UTF-8"?>
<reservationList
        xmlns="http://greath.example.com/2004/schemas/reservationList"
        xmlns:details="http://greath.example.com/2004/schemas/reservationDetails">

        <reservation>
                <details:confirmationNumber>HSG635</details:confirmationNumber>
                <details:checkInDate>2005-06-27</details:checkInDate>
                <details:checkOutDate>2005-06-28</details:checkOutDate>
                <details:reservationDetailsSOAPEndpoint>
                        http://greath.example.com/2004/reservation/HSG635
                </details:reservationDetailsSOAPEndpoint>
        </reservation>

        <reservation>
                <details:confirmationNumber>OMX736</details:confirmationNumber>
                <details:checkInDate>2005-06-01</details:checkInDate>
                <details:checkOutDate>2005-06-03</details:checkOutDate>
                <details:reservationDetailsSOAPEndpoint>
                        http://greath.example.com/2004/reservation/OMX736
                </details:reservationDetailsSOAPEndpoint>
        </reservation>

        <reservation>
                <details:confirmationNumber>WUH663</details:confirmationNumber>
                <details:checkInDate>2005-06-11</details:checkInDate>
                <details:checkOutDate>2005-06-15</details:checkOutDate>
                <details:reservationDetailsSOAPEndpoint>
                        http://greath.example.com/2004/reservation/WUH663
                </details:reservationDetailsSOAPEndpoint>
        </reservation>

</reservationList>

Here, the <details:reservationDetailsSOAPEndpoint> elements contain references to the Reservation Details Web service endpoints for the reservations HSG635, OMX736, and WUH663.

Example 5-11 shows the description of the Reservation List Web service. Note that it contains operations to retrieve the entire list and to query for a list of reservations by confirmation number, check-in date, and check-out date. In each case, the operation returns a list of reservations.

<?xml version="1.0" encoding="utf-8" ?>
<description 
        xmlns="http://www.w3.org/2006/01/wsdl"
        targetNamespace="http://greath.example.com/2004/services/reservationList"
        xmlns:tns="http://greath.example.com/2004/services/reservationList"
        xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:list="http://greath.example.com/2004/schemas/reservationList"
        xmlns:wsoap="http://www.w3.org/2006/01/wsdl/soap"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">

        <documentation>
                This document describes the GreatH Reservation List Web
                services. Use this service to retrieve lists of reservations
                based on a variety of search criteria.
        </documentation>

        <types>
                <xs:import
                        namespace="http://greath.example.com/2004/schemas/reservationDetails"
                        schemaLocation="reservationDetails.xsd" />
                <xs:import
                        namespace="http://greath.example.com/2004/schemas/reservationList"
                        schemaLocation="reservationList.xsd" />
        </types>

        <interface name="reservationListInterface">

                <operation name="retrieve"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="#none" />
                        <output messageLabel="Out" element="list:reservationList" />
                </operation>

                <operation name="retrieveByConfirmationNumber"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In"
                                element="details:confirmationNumber" />
                        <output messageLabel="Out" element="list:reservationList" />
                </operation>

                <operation name="retrieveByCheckInDate"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="details:checkInDate" />
                        <output messageLabel="Out" element="list:reservationList" />
                </operation>

                <operation name="retrieveByCheckOutDate"
                        pattern="http://www.w3.org/2006/01/wsdl/in-out">
                        <input messageLabel="In" element="details:checkOutDate" />
                        <output messageLabel="Out" element="list:reservationList" />
                </operation>

        </interface>

        <binding name="reservationListSOAPBinding"
                interface="tns:reservationListInterface"
                type="http://www.w3.org/2006/01/wsdl/soap"
                wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">

                <operation ref="tns:retrieve"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

                <operation ref="tns:retrieveByConfirmationNumber"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

                <operation ref="tns:retrieveByCheckInDate"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

                <operation ref="tns:retrieveByCheckOutDate"
                        wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />

        </binding>

        <service name="reservationListService"
                interface="tns:reservationListInterface">

                <endpoint name="reservationListEndpoint"
                        binding="tns:reservationListSOAPBinding"
                        address="http://greath.example.com/2004/reservationList" />

        </service>

</description>

Example 5-12 shows the schema for the messages used in the Reservation List Web service.

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified"
        targetNamespace="http://greath.example.com/2004/schemas/reservationList"
        xmlns:tns="http://greath.example.com/2004/schemas/reservationList"
        xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
        xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance">

        <import
                namespace="http://www.w3.org/2006/01/wsdl-instance" />

        <import
                namespace="http://greath.example.com/2004/schemas/reservationDetails"
                schemaLocation="reservationDetails.xsd" />

        <element name="reservation">
                <annotation>
                        <documentation>
                                A reservation contains the confirmation number, check-in
                                and check-out dates, and a reference to a Reservation
                                Details Web service.
                        </documentation>
                </annotation>
                <complexType>
                        <sequence>
                                <element ref="details:confirmationNumber" />
                                <element ref="details:checkInDate" />
                                <element ref="details:checkOutDate" />
                                <element ref="details:reservationDetailsSOAPEndpoint" />
                        </sequence>
                </complexType>
        </element>

        <element name="reservationList">
                <annotation>
                        <documentation>
                                A reservation list contains a sequence of zero or more
                                reservations.
                        </documentation>
                </annotation>
                <complexType>
                        <sequence>
                                <element ref="tns:reservation" minOccurs="0"
                                        maxOccurs="unbounded">
                                </element>
                        </sequence>
                        <attribute ref="wsdli:wsdlLocation" />
                </complexType>
        </element>

</schema>

In the preceding example, there was a single endpoint associated with each Reservation Detail Web service. Suppose GreatH hotel decided to provide a second, secure endpoint. In this case, references to services would be used to collect together the endpoints for each reservation. The reservationDetails.xsd schema defines the reservationDetailsService element for this purpose. It contains the nested elements soap and secure-soap which are each of type reservationDetailsSOAPEndpointType and therefore contain the address of an endpoint that implements the wdetails:reservationDetailsSOAPBinding binding.

Example 5-13 shows an example of a message that contains a reference to the service for reservation HGS635. Note that the service contains two endpoints, one of which provides secure access to the Reservation Details Web service.

<?xml version="1.0" encoding="UTF-8"?>
<details:reservationDetailsService
        xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"

        <details:soap>
                http://greath.example.com/2004/reservation/HSG635
        </details:soap>

        <details:secure-soap>
                https://greath.example.com/2004/reservation/HSG635
        </details:secure-soap>
                        
</details:reservationDetailsService>

5.3.3 Reservation Details Web Service Using HTTP Transfer

This section presents a variation on the example in 5.3.1 The Reservation Details Web Service . It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding [REST] . REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalability.

Since each reservation in our example will have a distinct URI, the Reservation Details Web service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:

. . .
<binding name="reservationDetailsHTTPBinding"
        type="http://www.w3.org/2006/01/wsdl/http"
    interface="tns:reservationDetailsInterface" >

        <operation ref="tns:retrieve"
            whttp:method="GET" />

        <operation ref="tns:update"
            whttp:method="PUT" />

</binding>
. . .

As with the example in 5.3.1 The Reservation Details Web Service , service and endpoint elements are not provided because the Reservation List Web service provides the endpoints.

5.3.4 Reservation List Web Service Using HTTP GET

This section continues the REST-style example of 5.3.3 Reservation Details Web Service Using HTTP Transfer by modifying the example of 5.3.2 The Reservation List Web Service to use HTTP GET.

The SOAP version of the Reservation List Web service above offers four different search operations. These can also be expressed as various parameters in a URI used by HTTP GET:

. . .
<binding name="reservationListHTTPBinding"
        type="http://www.w3.org/2006/01/wsdl/http"
    interface="tns:reservationListInterface"
    whttp:methodDefault="GET">

  <operation ref="tns:retrieve"
      whttp:location="" />

  <operation ref="tns:retrieveByConfirmationNumber"
      whttp:location="reservationList/ConfirmationNumber/{confirmationNumber/}" />

  <operation ref="tns:retrieveByCheckInDate"
      whttp:location="reservationList/CheckInDate/{checkInDate/}" />

  <operation ref="tns:retrieveByCheckOutDate"
      whttp:location="reservationList/CheckOutDate/{checkOutDate/}" />
</binding>
. . .
<service . . . >

  <endpoint name="reservationListEndpoint"
    binding="tns:reservationListHTTPBinding"
    address="http://greath.example.com/2004/reservationList" />
. . .
</service>
. . .

A retrieval by Confirmation Number URI would look like: http://greath.example.com/2004/reservationList/ConfirmationNumber/HSG635 .

Alternatively, a single query type may be provided. This query type is a sequence of optional items. Any items in the sequence are serialized into the URI query string. A query sequence for any of ConfirmationNumber, checkInDate, checkOutDate would look like this:

<element name="reservationQuery">
  <annotation>
    <documentation>
      A reservation contains the confirmation number, check-in
      and check-out dates, and a reference to a Reservation
      Details Web service.
    </documentation>
  </annotation>
  <complexType>
    <sequence>
      <element ref="details:confirmationNumber" minOccurs="0"/>
      <element ref="details:checkInDate" minOccurs="0"/>/>
      <element ref="details:checkOutDate" minOccurs="0"/>/>
    </sequence>
    </sequence>
  </complexType>
</element>

The WSDL 2.0 service that offers this type serialized as a parameter would look like this:

. . .
<interface name="reservationListInterfaceWithQuery">

  <operation name="retrieveByReservationQuery"
                pattern="http://www.w3.org/2006/01/wsdl/in-out">
    <input messageLabel="In"
        element="details:ReservationQuery" />
    <output messageLabel="Out"
        element="list:reservationList" />
  </operation>

</interface>

<binding name="reservationListQueryHTTPBinding"
        type="http://www.w3.org/2006/01/wsdl/http"
    interface="tns:reservationListInterfaceWithQuery"
    whttp:methodDefault="GET">

  <operation ref="tns:retrieveByReservationQuery"
      whttp:location="reservationList/{ReservationQuery}}" />

</binding>

. . .
  <endpoint name="reservationListEndpoint"
      binding="tns:reservationListHTTPBinding"
      address="http://greath.example.com/2004/reservationList" />
. . .

Various URIs would be: http://greath.example.com/2004/reservationList/ReservationQuery?confirmationNumber=HSG635 http://greath.example.com/2004/reservationList/ReservationQuery?checkInDate=06-06-05 .

It is important to observe that using the URI serialization can result in very flexible queries and few operations. The previous discrete SOAP operations are collapsed into one "parameterized" operation.

5.5.1 RDF Representation of WSDL 2.0

WSDL 2.0: Mapping to RDF [WSDL 2.0 RDF Mapping] describes how WSDL 2.0 constructs can be expressed in RDF using classes of resources (described with an ontology expressed in OWL) and assertions over individual resources. As RDF represents knowledge using resources and relationships between them, we need to turn WSDL 2.0 concepts into this model. This is done as follows.

1. First, all components in WSDL 2.0 (like Interfaces, Operations, Bindings, Services, Endpoints etc., including extensions) are turned into resources identified with the appropriate URIs created according to Appendix C IRI-References for WSDL 2.0 Components of [WSDL 2.0 Core].

2. Further, things are represented as resources:

   1. Element declarations gathered from XML Schema (or similarly, other components from other type systems)

   2. Message content models

   3. Message exchange patterns (the URI identifying the MEP is the URI of the resource)

   4. Operation styles (similarly to MEPs, the URI of an operation style is the URI of the resource)

3. All the resources above are given the appropriate types using rdf:type statements (an interface will belong to the class Interface and an operation within an interface will belong to the class InterfaceOperation, for example).

4. All relationships in WSDL 2.0 (like an Operation belonging to an Interface and having a given operation style) are turned into RDF statements using appropriate properties, such as operation and operationStyle.

5.6.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 2.0 specification provides the processing context here via the import mechanism, which is based on XML Schema's term for the similar concept.

5.6.2 Relative URIs

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

5.6.3 Generating Temporary URIs

In general, when a WSDL 2.0 document is published for use by others, it should only contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.

However, it is sometimes desirable to make up a temporary URI for an entity, for use during development, but not make the URI globally unique for all time and have it "mean" that version of the entity (schema, WSDL 2.0 document, etc.). Reserved Top Level DNS Names [IETF RFC 2606] specifies some URI base names that are reserved for use for this type of behavior. For example, the base URI "http://example.org/" can be used to construct a temporary URI without any unique association to an entity. This means that two people or programs could choose to simultaneously use the temporary URI " http://example.org/userSchema" for two completely different schemas. As long as the scope of use of these URIs does not intersect, then they would be unique enough. However, it is not recommended that " http://example.org/" be used as a base for stable, fixed entities.