WSDL 2.0规范

来源：互联网发布：淘宝卖家哪个软件好用编辑：程序博客网时间：2024/05/26 19:15

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

W3C Working Draft 21 December 2004

This version:: http://www.w3.org/TR/2004/WD-wsdl20-primer-20041221
Latest version:: http://www.w3.org/TR/wsdl20-primer
Editors:: David Booth, W3C Fellow / Hewlett-Packard; Canyang Kevin Liu, SAP Labs

Abstract

This document is a companion to the WSDL 2.0 specification(Web Services Description Language (WSDL) Version 2.0 Part 1:Core Language [WSDL 2.0 CoreLanguage], Web Services Description Language (WSDL)Version 2.0 Part 2: Predefined Extensions [WSDL 2.0 Predefined Extensions], WebServices Description Language (WSDL) Version 2.0 Part 3:Bindings [WSDL 2.0Bindings]). It is intended for readers who wish to havean easier, less technical introduction to the main features of thelanguage.

This primer is only intended to be a starting point toward useof WSDL 2.0, and hence does not describe every feature of thelanguage. Users are expected to consult the WSDL 2.0 specificationif they wish to make use of more sophisticated features ortechniques.

Finally, this primer is non-normative. Any specificquestions of what WSDL 2.0 requires or forbids should be referredto the WSDL 2.0 specification.

Status of this Document

This section describes the status of this document at thetime of its publication. Other documents may supersede thisdocument. A list of current W3C publications and the latestrevision of this technical report can be found in the W3C technical reports index athttp://www.w3.org/TR/.

This is a W3CFirst Public Working Draft. It has been produced by theW3C Web ServicesDescription Working Group, which is part of the W3C Web ServicesActivity. The Working Group expects to publish an updated draftin the future.

Because this is a work in progress, portions of thisdocument and the related WSDL 2.0 specification may not correspondexactly with the most recent decisions of the WorkingGroup. (For example, the previous"definitions" element was later renamed to"description".) The latest editors' copies of the WSDL2.0 specification may be available from the Web Services Description WorkingGroup home page.

Comments on this document are invited and should be sent to thepublic public-ws-desc-comments@w3.orgmailing list (publicarchive).

Publication as a Working Draft does not imply endorsement by theW3C Membership. This is a draft document and may be updated,replaced or obsoleted by other documents at any time. It isinappropriate to cite this document as other than work inprogress.

This document has been produced under the 24January 2002 Current Patent Practice as amended by the W3C Patent PolicyTransition Procedure. Patent disclosures relevant to thisspecification may be found on the Working Group's patentdisclosure page. An individual who has actual knowledge of apatent which the individual believes contains Essential Claim(s)with respect to this specification should disclose the informationin accordance with section 6 of the W3C Patent Policy.

Short Table ofContents

1. Introduction
2. WSDL 2.0 Basics
3. More on Message Types
4. More on Interfaces
5. More on Bindings
6. More on Service Endpoints
7. Advanced Topics - TBD
8. References

1. Introduction
    1.1 Prerequisites
    1.2 Structure ofthis Primer
    1.3 NotationalConventions
2. WSDL 2.0 Basics
    2.1 Example Scenario: The GreatH HotelReservation Service
    2.2 Getting Started: Defining a WSDL TargetNamespace
        2.2.1 Explanation of Example
    2.3 DefiningMessage Types
        2.3.1 Explanation ofExample
    2.4 Defining anInterface
        2.4.1 Explanation ofExample
    2.5 Defining aBinding
        2.5.1 Explanation ofExample
    2.6 Defining aService
        2.6.1 Explanation ofExample
    2.7 Documenting the Service
        2.7.1 Explanation ofExample
    2.8 XML SyntaxSummary
        2.8.1 Brief Syntax Summary
        2.8.2 Longer Syntax Summary
3. More on Message Types
    3.1 DefiningMessages Using XML Schema
        3.1.1 Importing XML Schema
        3.1.2 Embedding XML Schema
4. More on Interfaces
    4.1 Interface Syntax
        4.1.1 Interface Inheritance
        4.1.2 Reusable Faults
        4.1.3 Interface Operations
    4.2 Understanding Message ExchangePatterns
5. More on Bindings
    5.1 BindingConstructs in WSDL Namespace
        5.1.1 Binding Faults
        5.1.2 Binding Operations
    5.2 Extensions for SOAP Binding
    5.3 Extensions for HTTP Binding
6. More on Service Endpoints
7. Advanced Topics - TBD
    7.1 Extensibility
        7.1.1 Optional Versus RequiredExtensions
        7.1.2 Scoping of the wsdl:requiredAttribute
    7.2 Features andProperties
    7.3 Import mechanism and authoringstyle
    7.4 Multiple Logical WSDLDocuments Describing the Same Service
    7.5 Versioningand Service Equivalency
    7.6 MTOMSupport
    7.7 SecurityConsiderations
    7.8 Operation Styleand RPC
    7.9 Enabling Easy Message Dispatch
    7.10 GET VersusPOST: Which to Use?
    7.11 Service References
    7.12 XMLSchema Examples
    7.13 Multiple In-Line Schemas
    7.14 TheschemaLocation Attribute
    7.15 Mapping toRDF and Semantic Web
    7.16 Notes onURIs
        7.16.1 XML Namespaces and SchemaLocations
        7.16.2 Relative URIs
        7.16.3 Generating URIs
8. References
    8.1 Normative References
    8.2 Informative References

1.Introduction

1.1Prerequisites

This primer assumes that the reader has the followingprerequisite knowledge:

familiarity with XML (Extensible Markup Language (XML) 1.0(Second Edition) [XML 1.0],XML Information Set [XMLInformation Set]) and XML Namespaces (Namespaces inXML [XML Namespaces]);
some familiarity with XML Schema (XML Schema Part 1:Structures [XML Schema:Structures] XML Schema Part 2: Datatypes[XML Schema:Datatypes]);
familiarity with basic Web services concepts such as Webservice, client, and the purpose and function of a Web servicedescription. (For an explanation of basic Web services concepts,see Web Services Architecture [WSArchitecture] Section1.4 and Web Services Glossary [WS Glossary] glossary.However, note the Web Services Architecture document usesthe slightly more precise terms "requesteragent" and "provideragent" instead of the terms "client" and "Web service" used inthis primer.)

No previous experience with WSDL is assumed.

1.2Structure of this Primer

Section 2 presents a hypothetical use case involving a hotelreservation service. It then proceeds step-by-step through thedevelopment of a simple example WSDL 2.0 document that describesthis service:

The types element describes the kinds of messagesthat the service will send and receive.
The interface element describes whatabstract functionality the Web service provides.
The binding element describes how toaccess the service.
The service element describes where toaccess the service.

Section 3 gives more information on defining message types.

Section 4 gives more information on interfaces.

Section 5 gives more information on bindings.

Section 6 gives more information on defining services.

Section 7 covers various advanced topics, including features andproperties, flexible authoring styles, service references, use ofURIs, etc.

1.3 NotationalConventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALLNOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"in this document are to be interpreted as described in RFC2119.

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

2. WSDL 2.0 Basics

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

2.1 Example Scenario: The GreatH HotelReservation Service

Hotel GreatH is located in a remote island. It has been relyingon fax and phone to provide room reservations. Even though thefacilities and prices at GreatH are better than what its competitoroffers, GreatH notices that its competitor is getting morecustomers than GreatH. After research, GreatH realizes that this isbecause the competitor offers a Web service that permits travelagent reservation systems to reserve rooms directly over theInternet. GreatH then hires us to build a reservation Web servicewith the following functionality:

CheckAvailability. To check availability, the clientmust specify a check-in date, a check-out date, and room type room,and the Web service will provide the room rate if such a room isavailable. If any input data is invalid, the service should returnan error. Thus, the service will accept acheckAvailability message and return acheckAvailabilityResponse orinvalidDataFault message.
MakeReservation. To make a reservation, a client mustprovide a name, address, and credit card information, and theservice will return a confirmation number if the reservation issuccessful. The service will return an error message if the creditcard number or any other data field is invalid. Thus, the servicewill accept a makeReservation message and return amakeReservationResponse orinvalidCreditCardFault message.

We know that we will later need to build a complete system thatsupports transactions and secured transmission, but initially wewill implement only minimal functionality. In fact, to simplify ourfirst example, we will implement only theCheckAvailability operation.

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

Example2-1. WSDL 2.0 Document for the GreatH Web Service (InitialExample)

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

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

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

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

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

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

  </interface>

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

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

  </binding>

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

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

</description>

2.2 Getting Started: Defining a WSDLTarget Namespace

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

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

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

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

Example2-2. An Initial Empty WSDL Document

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

  . . .
</description>

2.2.1 Explanation ofExample

<description: Every WSDL 2.0 document has a description elementas its top-most element. This merely acts as a container for therest of the WSDL 2.0 document, and is used to declare namespacesthat will be used throughout the document.
xmlns="http://www.w3.org/2004/08/wsdl": This is the XML namespace for WSDL 2.0 itself. Because we havenot defined a prefix for it, any unprefixed elements or attributesare expected to be WSDL 2.0 elements or attributes (such as thedescription element).
targetNamespace="http://greath.example.com/2004/wsdl/resSvc.wsdl": This defines the WSDL target namespace that we have chosen forthe GreatH reservation service, as described above. Note that thisis not an actual XML namespace declaration. Rather, it is a WSDL2.0 attribute whose purpose is analogous to an XML Schematarget namespace.
xmlns:tns="http://greath.example.com/2004/wsdl/resSvc.wsdl": This is an actual XML namespace declaration for use in ourGreatH service description. Note that this is the same URI that wasspecified above as the value of the targetNamespaceattribute. This will allow us later to use the tns:prefix in qnames, to refer to the WSDL target namespace of theGreatH service. (For more on QNames see [XMLNamespaces] section 3 QualifiedNames.)

Now we can start describing the GreatH service.

2.3 DefiningMessage Types

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

WSDL 2.0 allows message types to be defined directly within theWSDL document, inside the types element, which is achild of the description element. (Later we'll see howwe can provide the type definitions in a separate document, usingXML Schema's import mechanism.) The following schemadefines checkAvailability, checkAvailabilityResponse andinvalidDataError message types that we'll need.

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

Example 2-3. GreatHMessage Types

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

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

  , , ,

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

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

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

2.3.1 Explanation ofExample

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

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

2.4Defining an Interface

WSDL 2.0 enables one to separate the description of a Webservice's abstract functionality from the concrete details of howand where that functionality is offered. This separationfacilitates different levels of reusability and distribution ofwork in the lifecycle of a Web service and the WSDL document thatdescribes it.

A WSDL 2.0 interface defines the abstract interfaceof a Web service as a set of abstract operations, eachoperation representing a simple interaction between the client andthe service. Each operation specifies the types of messages thatthe service can send or receive as part of that operation. Eachoperation also specifies a message exchange pattern thatindicates the sequence in which the associated messages are to betransmitted between the parties. For example, the in-outpattern (see WSDL 2.0 Predefined Extensions[WSDL 2.0 PredefinedExtensions] section 2.2.3 In-Out)indicates that if the client sends a message in to theservice, the service will either send a reply message backout to the client (in the normal case) or it will send afault message back to the client (in the case of an error).

For the GreatH service, we will (initially) define an interfacecontaining a single operation, opCheckAvailability,using the checkAvailability andcheckAvailabilityResponse message types that wedefined in the types section. We'll use the in-outpattern for this operation, because this is the most natural way torepresent a simple request-response interaction. We could haveinstead (for example) defined two separate operations using thein-onlyand out-only patterns (see WSDL 2.0 Predefined Extensions[WSDL 2.0 PredefinedExtensions] section 2.2.1 In-Onlyand section 2.2.5 Out-Only), but that would just complicate matters for theclient, because we would then have to separately indicate to theclient developer that the two operations should be used together asa request-response pair.

In addition to the normal input and output messages, we alsoneed to specify the fault message that we wish to use in the eventof an error. WSDL 2.0 permits fault messages to be declared withinthe interface element in order to facilitate reuse offaults across operations. If a fault occurs, it terminates whatevermessage sequence was indicated by the message exchange pattern ofthe operation.

Let's add these to our WSDL document.

Example 2-4. GreatHInterface Definition

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

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

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

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

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

  </interface>

  . . .
</description>

2.4.1 Explanation ofExample

<interface name = "reservationInterface">: Interfaces are declared directly inside thedescription element. In this example, we are declaringonly one interface, but in general a WSDL document may declare morethan one interface (each one for use with a different service).Thus, each interface must be given a name that is unique within theset of interfaces defined in this WSDL target namespace. Interfacenames are tokens that must not contain a space or colon (":").
<fault name ="invalidDataFault": The name attribute defines a name for this fault.The name is required so that when an operation is defined, it canreference the desired fault by name. Fault names must unique withinan interface.
element ="ghns:invalidDataError"/>: The element attribute specifies the schema type ofthe fault message, as previously defined in the typessection.
<operationname="opCheckAvailability": The name attribute defines a name for thisoperation, so that it can be referenced later when bindings aredefined. Operation names must also be unique within an interface.(WSDL 2.0 uses separate symbol spaces for operation and faultnames, so operation name "foo" is distinct from fault name"foo".)
pattern="http://www.w3.org/2004/03/wsdl/in-out">: This line specifies that this operation will use the in-outpattern as described above. WSDL 2.0 uses URIs to identify messageexchange patterns in order to ensure that they are uambiguouslyidentified, while also permitting future new patterns to be definedby anyone. (However, just because someone defines a new pattern andcreates a URI to identify it, that does not mean thatother WSDL processors will automatically recognize or understandthat pattern. As with any other extension, it can be used amongprocessors that do recognize and understand it.)
<input messageLabel="In": The input element specifies an input message. Eventhough we have already specified which message exchange pattern theoperation will use, a message exchange pattern represents atemplate for a message sequence, and in general it may consist ofmultiple input and/or output messages. Thus we must also indicatewhich potential input message in the pattern this particular inputmessage represents. This is the purpose of themessageLabel attribute. Since the in-outpattern that we've chosen to use only has one input message, it istrivial in this case: we simply fill in the message label "In" thatwas defined in WSDL 2.0 Predefined Extensions[WSDL 2.0 PredefinedExtensions] section 2.2.3 In-Outfor the in-outpattern. However, in theory, new patterns could be defined thatinvolve multiple input messages, and the different input messagesin the pattern would be distinguished by having differentlabels.
element="ghns:checkAvailability"/>: This specifies the message type for this input message, asdefined previously in the types section.
<output messageLabel="Out" . ..: This is similar to defining an input message.
<outfault ref="tns:invalidDataFault"messageLabel="Out"/>: This associates an output fault with this operation. Faults aredeclared a little differently than normal messages. Theref attribute refers to the name of a previouslydefined fault in this interface -- not a message schema typedirectly. Since message exchange patterns could in general involvea sequence of several messages, a fault could potentially occur atvarious points within the message sequence. Because one may wish toassociate a different fault with each permitted point in thesequence, the messageLabel is used to indicate the desired pointfor this particular fault. It does so indirectly by specifying themessage that will either trigger this fault or that this fault willreplace, depending on the pattern. (Some patterns use a message-triggers-fault rule; others use a fault-replaces-message rule. See WSDL 2.0 PredefinedExtensions [WSDL 2.0 PredefinedExtensions] section 2.1.2 Message Triggers Fault and section 2.1.1 Fault Replaces Message.)

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

Editorial note:dbooth [This note is onlyrelevant to the editors.] Hmm, I just realized that in the sourceXML for this primer, in some cases we've been using <el> toindicate an element name, and in other cases we've been using<code>. At present, the xmlspec XSLT script seems totranslate them both into <code> elements in the generatedHTML, but we should probably make them consistent, in case thatchanges.

2.5 Defining aBinding

Although we have specified what abstract messages canbe exchanged with the GreatH Web service, we have not yet specifiedhow those messages can be exchanged. This is the purposeof a binding. A binding specifies concrete message formatand transmission protocol details for an interface, and must supplysuch details for every operation and fault in the interface.

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

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

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

Example 2-5. GreatHBinding Definition

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

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

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

  </interface>

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

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

  </binding>

  . . .
</description>

2.5.1 Explanation ofExample

xmlns:wsoap="http://www.w3.org/2004/08/wsdl/soap12": We've added two more namespace declarations. This one is thenamespace for the SOAP 1.2 binding construct that is defined inWSDL 2.0 Part 3 [SOAP 1.2 Part 1:Messaging Framework]. Elements and attributes prefixedwith wsoap: are constructs defined there.
xmlns:soap="http://www.w3.org/2003/05/soap-envelope": This namespace is defined by the SOAP 1.2 specification itself.The SOAP 1.2 specification defines certain terms within thisnamespace to unambiguously identify particular concepts. Thus, wewill use the soap: prefix when we need to refer to oneof those terms.
<bindingname="reservationSOAPBinding": Bindings are declared directly inside thedescription element. The name attributedefines a name for this binding. Each name must be unique among allbindings in this WSDL target namespace, and will be used later whenwe define a service endpoint that references this binding. WSDL 2.0uses separate symbol spaces for interfaces, bindings and services,so interface "foo", binding "foo" and service "foo" are alldistinct.
interface="tns:reservationInterface": This is the name of the interface whose message format andtransmission protocols we are specifying. As discussed in 5. More on Bindings, a reusable bindingcan be defined by omitting the interface attribute.Note also the use of the tns: prefix, which refers tothe previously defined WSDL target namespace for this WSDLdocument. In this case it may seem silly to have to specify thetns: prefix, but in 7.3 Import mechanism and authoringstylewe will see how WSDL 2.0's import mechanism can beused to combine components that are defined in different WSDLtarget namespaces.
type="http://www.w3.org/2004/08/wsdl/soap12": This specifies the type of concrete message format to use, inthis case SOAP 1.2.
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP": This attribute is specific to WSDL 2.0's SOAP binding (thus ituses the wsoap: prefix). It specifies the underlyingtransmission protocol that should be used, in this case HTTP.
<operationref="tns:opCheckAvailability": This not defining a new operation. Rather, it is referencing thepreviously defined opCheckAvailability operation inorder to specify binding details for it. This element can beomitted if defaulting rules are instead used to supply thenecessary information. (See the SOAP binding in WSDL 2.0Bindings [WSDL 2.0Bindings] section 2.3 Default Binding Rules.)
wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response">: This attribute is also specific to WSDL 2.0's SOAP binding. Itspecifies the SOAP message exchange pattern that will be used toimplement the abstract WSDL 2.0 message exchange pattern (in-out)that was specified when the opCheckAvailabilityoperation was defined.
<faultref="tns:invalidDataFault": As with a binding operation, this is not declaring a new fault.Rather, it is referencing a fault (invalidDataFault)that was previously defined in the opCheckAvailabilityinterface, in order to specify binding details for it.
wsoap:code="soap:Sender"/>: This attribute is also specific to WSDL 2.0's SOAP binding. Thisspecifies the SOAP 1.2 fault code that will cause this faultmessage to be sent.
Editorialnote Need to verify that thisexplanation is correct. Seehttp://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.htmlIf desired, an list of subcodes can also be specified using theoptional wsoap:subcodes attribute.

2.6 Defining aService

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

A WSDL 2.0 service specifies a single interface thatthe service will support, and a list of endpoint locationswhere that service can be accessed. Each endpoint must alsoreference a previously defined binding in order to indicate thebinding details that are to be used at that endpoint. A service isonly permitted to have one interface. (However, WSDL 2.0 does notprohibit one from declaring multiple services that use differentinterfaces but happen to use the same endpoint address. See7.4Multiple Logical WSDL Documents Describing the SameService.)

Here is a definition for our GreatH service.

Example 2-6. GreatHService Definition

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

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

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

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

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

2.6.1 Explanation ofExample

<servicename="reservationService": This defines a name for this service, which must be unique amongservice names in the WSDL target namespace. The name attribute isrequired in order to facilitate the use of URIs to indentifycomponents in WSDL 2.0 documents. (See WSDL 2.0 CoreLanguage [WSDL 2.0 CoreLanguage] appendix C URI References for WSDL constructs.)
interface="tns:reservationInterface">: This specifies the name of the previously defined interface thatthese service endpoints will support.
<endpointname="reservationEndpoint": This defines an endpoint for the service, and a name for thisendpoint, which must be unique within this service.
binding="tns:reservationSOAPBinding": This specifies the name of the previously defined binding to beused by this endpoint.
address="http://greath.example.com/2004/reservation"/>: This specifies the physical address at which this service can beaccessed using the binding specified by the bindingattribute.

That's it! Well, almost.

2.7 Documenting the Service

As we have seen, a WSDL 2.0 document is inherently only apartial description of a service. Although it captures thebasic mechanics of interacting with the service -- the messagetypes, transmission protocols, service location, etc. -- ingeneral, additional documention will need to explain otherapplication-level requirements for its use. For example, suchdocumentation should explain the purpose and use of the service,the meanings of all messages, constraints on their use, and thesequence in which operations should be invoked.

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

Example 2-7.Documenting the GreatH Service

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

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

  <types>
    . . .
  </types>

  . . .  
</description>

2.7.1 Explanationof Example

<documentation>: This element is optional, but a good idea to include. It cancontain arbitrary mixed content.
athttp://greath.example.com/2004/reservation-documentation.html: The most important thing to include is a pointer to anyadditional documentation that a client developer would need inorder to use the service.

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

2.8 XML SyntaxSummary

In the core language specification, WSDL 2.0 constructs aredefined as a set of abstract components, along with a mapping to anXML infoset representation for these components. For easierconsumption, the primer uses the XML representation of WSDLcomponents. The following conventions are followed for thesyntax:

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

Editorial note:dbooth To do: check the aboveelipses (...), as they weren't rendering properly at onepoint.

2.8.1 Brief Syntax Summary

Editorialnote To do: Insert shortsummary here

2.8.2 Longer Syntax Summary

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

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

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

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

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

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

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

      <feature ... />*

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

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

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

        <feature ... />*

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

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

        <feature ... />*

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

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

        <feature ... />*

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

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

        <feature ... />*

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

      <feature ... />*

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

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

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

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

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

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

      <feature ... />*

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

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

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

        <feature ... />*

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

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

        <feature ... />*

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

      <feature ... />*

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

    <feature ... />*

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

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

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

      <feature ... />*

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

    <feature ... />*

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

In addition, feature and propertyelements are allowed inside most WSDL elements. Also, an optionaldocumentation element is allowed inside any WSDLelement as a container for human readable and/or machineprocessable documentation. The content ofdocumentation is arbitrary characters and elements("mixed" content in XML Schema).

3. More on MessageTypes

3.1Defining Messages Using XML Schema

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

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

A WSDL description MUST NOT refer to XML Schema components in agiven namespace unless an xs:import and/orxs:schema statement for that namespace is present. Inother words, using the xs:import and/orxs:schema constructs is a necessary condition formaking XML Schema components available to a WSDL description.

Please note the use of type system other than XML Schema isindicated by the extension elements in the above syntax. (SeeWSDL 2.0 Core Language [WSDL2.0 Core Language] appendix E Examplesof Specifications of Extension Elements for Alternative SchemaLanguage Support.)

3.1.1 Importing XML Schema

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

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

A types element can contain zero or moreimport s which may have one or two attributes asfollows:

A REQUIRED namespace attribute of typexs:anyURI.
The namespace attribute defines the namespace ofthe element declarations imported from the referenced schema. Asmandated in Section 3 of the Part 1 specification, the referencedschema MUST contain an XML Schema targetNamespaceattribute on its xs:schema element and the values ofthese two attributes MUST be identical. It is an error to import aschema that does not have an XML Schema target namespace. Suchschemas must first be included (using xs:include ) ina schema that contains a targetNamespace attribute; onits xs:schema element, which can then be eitherimported or inlined in the WSDL document.
An OPTIONAL schemaLocation attribute of typexs:anyURI.
The schemaLocation attribute, if present, providesa hint to the WSDL processor as to where the schema may be located.It's optional since the WSDL may have better ways to locate theschema files, for example, caching and cataloging technologies mayprovide better information than this hint.

3.1.2 Embedding XML Schema

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

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

Similarly, components defined in an embedded XML schema are NOTautomatically made available to a WSDL description that imported(using wsdl:import ) the description that embeds theschema (see section @@@@ for more details). For this reason, it isrecommended that XML schema documents intended to be shared acrossseveral WSDL descriptions be placed in separate documents andimported using xs:import , rather than embedded insidea WSDL document.

Inside an embedded XML schema, the xs:import andxs:include elements MAY be used to refer to other XMLschemas embedded in the same WSDL description, provided that anappropriate value is specified for theirschemaLocation attributes. The semantics of suchelements are governed solely by the XML Schema specification[XML Schema:Structures].

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

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

A REQUIRED targetNamespace attribute of typexs:anyURI.
It defines the XML Schema target namespace of the elementdeclarations embedded in its owner xs:schema . Notethat WSDL modifies the XML Schema definition of XML Schemaxs:schema to make the targetNamespaceattribute required.
Additional OPTIONAL attributes as specified for thexs:schema element by the XML Schema specification.
Zero or more child elements as specified forxs:schema by the XML Schema specification.

Here is an example of importing a schema.

Example 3-1. ImportingMessage Definitions into WSDL 2.0

Example3-2. Importing Message Definitions

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

  . . .
</description>

4. More onInterfaces

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

4.1 Interface Syntax

Editorial note:dbooth To do: Simplify thissyntax summary.

Below is the XML syntax summary of the interfaceelement:

<description targetNamespace="xs:anyURI" >

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

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

      <feature ... />*

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

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

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

        <feature ... />*

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

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

        <feature ... />*

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

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

        <feature ... />*

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

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

        <feature ... />*

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

      <feature ... />*

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

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

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

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


</description >

One WSDL description element may contain zero ormore interface elements as its direct children. Zerointerface elements are permitted since adescription element may only contain binding and/orendpoint definitions to be aggegrated into a master WSDLdescription via import/include mechanisms.

Let's have a look at the attributes of interfacefirst. It has one required name attribute. Within thesame WSDL target namespace (might be in different wsdl documents,see section @@@@), each interface must have a unique name. Theinterface element has two optionalattributes:extends and styleDefault .extends will be explained in the next section. We willexplain what a style later. For now, keep in mind thatthe optional styleDefault attribute ofinterface can be used to define a default value forthe style attribute of all operation sunder this interface , if any of the operations do notspecify a value for its style .

4.1.1 Interface Inheritance

The optional extends attribute allows an interfaceto extend one or more other interfaces. In such cases the interfacecontains the operations of the interfaces it extends, along withany operations it defines. Two things about extending interfacesdeserve some attention.

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

Second, there may be cases where, due to an interface extendingone or more other interfaces, operations from different interfacemay have a name collision. More precisely, within the samenamespace, two or more interface operations end up having the samename. In such cases, WSDL 2.0 requires that the component models ofthose Interface Operation components MUST be equivalent (ComponentEquivalence is defined in Part 1 section 2.15 Equivalence ofComponents. For operations, basically equivalence means the twooperations in question have same set of attributes anddescendents). If the collisional operations are equivalent thenthey are considered to collapse into a single operation. It is anerror if they have the same name in the same WSDL target namespacebut are not equivalent. In other words, if two interfaces have namecollisional operations, then those two interfaces cannot both formpart of the derivation chain of a derived interface unless thoseoperations are exactly the same. For the above reason, it isconsidered good practic to ensure that all operations within thesame namespace are named uniquely whenever possible. Furthermore,since faults, features and properties can also be defined aschildren of the interface element (as descrbed later),the same name-collision resolution rules apply to thoseconstructs.

Editorial note:KevinL20040910Add Example - illustrateuse extends attribute

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

4.1.2 Reusable Faults

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

The fault element has a required nameattribute. Within a same namespace, all faults must be nameduniquely. The optional element attribute can be usedto indicate the content or playload of the fault message. Its valueshould be the QName of the XML schema global element declarationwhich defines the fault message. Please note when other typesystems are used to define a fault message, additional attributesmay need to be defined via WSDL's attribute extension mechanism toallow associating such a message definition with the fault.

Here is an example of reusing faults.

Editorial note:dbooth To do: Update thisexample

Example4-1. Declaring interface faults

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

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

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

        </fault>   

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

        </fault>   

  </interface>


</description>

Editorial note:KevinL20040520Need clarification -fault must be named uniquely across interfaces?

4.1.3 Interface Operations

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

WSDL 2.0 defines two required and two optional attributes for anoperation :

A required name attribute
Operation names must be unique within an interface. Beware thatoperations are local to an interface ,sotwo interface elements sharing the same WSDL targetnamespace but with different name MAY containoperations which share the same name. Thus,operations cannot be referenced by QName since thename and WSDL target namespace are not sufficient touniquely identify an operation . In order to uniquelyidentify an operation , one must first identify theinterface by QName and then identify theoperation within that interface by afurther QName. As explained in section @@@, this fact has compoundimpact when an interface extends other interfaces. It is consideredgood practice to name operations uniquely within same namespacewhenever possible.
A required pattern attribute
it identifies the MEP a given operation uses. Itsvalue must be an absolute URI.
An optional style attribute
it's an absolute URI identifying the rules that were used toconstruct the message type definitions used by theoperation . Note that the attribute MAY not present,but if it is present, then the rules implied by that value MUST befollowed or it is an error. For example, WSDL 2.0 defines a set ofrules for constructing so called RPC style messages (Seesection@@@@). If this attribute is set to"http://www.w3.org/2004/03/wsdl/style/rpc", then all the rulesdefined for the RPC style must be followed. We will have a closerlook at RPC style in section@@@.
Editorial note:KevinL20040910Add Example and more text- illustrate use of RPC style
An optional safety attribute
A boolean indicating whether the operation is asserted to besafe (as defined in Section 3.5 of Web Architecture for users ofthe described service to invoke. An operation SHOULD be marked safeby setting the safty to true if it meets all thecriteria for a safe interaction defined in Section 3.5 of WebArchitecture. The default value of this attribute is false. If itis false or is not set, then no assertion is made about the safetyof the operation, thus the operation MAY or MAY NOT be safe.

An operation references a set of ordinary and faultmessages it accepts or sends via zero or more input ,output ,infault , andoutfault element. Which of these constructs to use isgoverned by the MEP in use. As we have seen in section@@@@, an MEPdefines a set of placeholder messages that participate in thepattern and assigns them unique names within the pattern. Theinput and output element are used toassociate an actual mesage type with that message placeholder inthe MEP. Such association is done via twoattributes:messageLabel and element . ThemessageLabel attribute is used to identify the rolethis message plays in the MEP. Its value must match the name of theMEP place holder message. Note that the messageLabelis optional, since it's not necessary to explicitly set themessageLabel when the MEP in use has only one message with a givendirection. The element attribute can be used toidentify the messages content (aka payload) when the content modelis defined in XML Schema (see section @@@@ for using other typesystems). The content model is a token with one of the values#any, #none, or #element. A value of#any indicates that the message content is any singleelement. A value of #none indicates there is no messagecontent. It means that the payload will be empty. When the value isset to a Qname, it indicates that the message consists of a singleelement described by the referenced global element declarationreference by Qname. In addition, the direction implied by theinput, and output must also match the direction ofthe placeholder message identified by messageLabel.

We have already talked about how to associate a message typewith a reusable interface fault . We have also coveredthe fault generation rules a MEP may use. Here underoperation , the infault andoutfault elements can be used to associate aninterface fault with a specific message in the MEPused by an operation . Such association is done via afew attributes: the now familiar messageLabelattribute, the direction implied by the infault andoutfault, and a required ref attrbiute whichpoints to the Qname of an interface fault . Wheninfault and/or outfault occur multipletimes within an operation , they define alternativefault message.

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

Example4-2. Defining Interface Operations

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

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

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

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

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

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

        </operation>

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

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

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

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

        </operation>

  </interface>

</description>

Note that in the above example, the invalidDataFault isre-used by both operations. In the makeReservationoperation, two alternative outgoing faults are defined which meanseither a invalidDataFault or a invalidCreditCardFault may bereturned as a replacement of the outgoing message.

An operation can also contain zero or morefeature and property elements. We deferthe explanation for feature and propertyto section @@@@.

4.2 Understanding Message ExchangePatterns

WSDL 2.0 message exchange patterns (MEPs) are used to definesthe sequence and cardinality of the abstract messages in anoperation. By design, WSDL 2.0 MEPs are abstract. First of all,they abstract out specific message types. MEPs identifyplaceholders for messages, and placeholders are associated withspecific message types when an operation specifies which MEP touse. Secondly, unless explicitly stated otherwise, MEPs alsoabstract out binding-specific information like timing betweenmessages, whether the pattern is synchronous or asynchronous, andwhether the messages are sent over a single or multiplechannels.

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

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

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

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

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

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

In-Only ("http://www.w3.org/2004/03/wsdl/in-only")
This patten consists of exactly one message received by aservice from some other node. No fault maybe generated.
Robust In-Only("http://www.w3.org/2004/03/wsdl/robust-in-only")
This pattern can be considered as a variation of In-only. Italso consists of exactly one message received by a service, but inthis case faults can be triggered by the message as specified inthe "Message Triggers Fault" model.
In-Out ("http://www.w3.org/2004/03/wsdl/in-out")
This patten consists of exactly two message: a message receivedby a service from some other node, followed by a message sent tothe other node. The second message may be replaced by a fault asspecified in the "Fault Replace Message" model.
In-Optional-Out("http://www.w3.org/2004/03/wsdl/in-opt-out")
This patten consists of one or two messages: a message receivedby a service from some other node, optionally followed by a messagesent to the other node from the service. Each message may trigger afault in response as specified in the "Message Triggers Faults"model.

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

Out-Only ("http://www.w3.org/2004/03/wsdl/out-only")
This patten consists of exactly one message sent to some othernode from a service. No fault maybe generated.
Robust Out-Only("http://www.w3.org/2004/03/wsdl/robust-out-only")
This pattern can be considered as a variation of Out-only. Italso consists of exactly one message sent to some other node from aservice, but in this case faults can be triggered by the message asspecified in the "Message Triggers Fault" model.
Out-in ("http://www.w3.org/2004/03/wsdl/out-in")
This patten consists of exactly two message: a message sent tosome other node from a service, followed by a message received bythe service from the other node. The second message may be replacedby a fault as specified in the "Fault Replace Message" model.
Out-Optional-In("http://www.w3.org/2004/03/wsdl/out-opt-in")
This patten consists of one or two messages: a message sent tosome other node from a service, optionally followed by a messagereceived by the service from the other node. Each message maytrigger a fault in response as specified in the "Message TriggersFaults" model.

While the in-bound MEPs are easier to understand, there havebeen questions concerning the usefulness of out-bound MEPs,especially how a service can specify the endpoint information forthe target node of the initial out-bound message. In their typicaluse cases, such as in large scale intergration projects whereendpoint information is most likely specified at deployment orruntime by mapping and routing facilities, or/and in languages thatfacilitate services composition where only abstract interfaces areconcerned, Out-bound MEPs are useful in the abstract level forfully specifying the functionality of a service, including itsrequirements for its potential customers, so application integratorcan gain a better understanding of how multiple services may beused together, whereas binding and endpoint information may beprovided by integration infrastructure in application deploymentand runtime.

Editorial note:KevinL20040910Add more use cases andexample - illustrate use of outbound meps?

5. More onBindings

A binding can be defined for different levels ofreusability. It can be used to describe binding information in are-usable manner for any interface or specifically for a giveninterface. Furthermore, binding information MAY be specified on aper-operation basis if needed. If a binding specifiesany operation-specific binding details or any fault bindingdetails, then it MUST specify an interface the binding informationapplies to, so as to indicate which interface the operations comefrom.Conversely, a binding that omits anyoperation-specific binding details and any fault binding detailsMAY omit specifying an interface. bindings that do notspecify an interface MAY be used to specify operation-independentbinding details for Service components with different interfaces.That is, such bindings are reusable across one or moreinterfaces.

A binding tied to a particular interface MUSTdefine bindings for all the operations of that interface. Thebindings may occur via defaulting rules which allow one to specifydefault bindings for all operations (for example, see the SOAPbinding in WSDL 2.0 Bindings [WSDL 2.0 Bindings] section 2.3 Default Binding Rules) or by directly listing each operation ofthe interface and defining bindings for them. Thus, it is an errorfor a binding to not define bindings for all the operations of thecorresponding interface.

The binding constructs can be grouped into two categories: thosein the WSDL namespace of "http://www.w3.org/2004/08/wsdl" and thosenot in WSDL namespace. WSDL 2.0 part 1 defines a set of bindingconstructs within the WSDL namespace that can be used to hostbinding detail definitions. Constructs for defining binding detailsare defined within their own namespaces which must be differentfrom the WSDL namespace. ll these binding detail constructs aredefined outside WSDL namespace, and are typically used asextensions of the hosting WSDL binding constructs. In the followingsections, we will introduce the hosting WSDL binding constructsfirst, and then move on the the binding extensions.

5.1Binding Constructs in WSDL Namespace

Let's have a look at the constructs defined within the WSDLnamespace first. The XML syntax of these constructs is summarizedbelow:

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

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

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

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

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

      <feature ... />*

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

    <feature ... />*

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

</description>

Editorial note:KevinL20040527Need clarification -infault outfault are missing from the binding operation syntax. Isit an oversight?Editorial note:dbooth Trim some of this?Redundant?

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

The binding element has a requiredname attribute. Within the same WSDL target namespace, each binding must have a unique name. The optionalinterface attribute refers, by QName, to aninterface . See the previous section for how theinterface attribute can be used to achieve differentlevels of reusability of the binding .

Careful readers may have already noticed that thebinding syntax is to some extent symmetric with thesyntax of interface , in other words, each interfaceconstruct has a binding counterpart. Simliar tointerface ,a binding element can containzero or more fault , zero or moreoperation , zero or more feature , andzero or more property . Be aware that despite of thesyntax similarity, they are indeed different constructs since theyare in different symbol spaces and are designed for differentpurpose. The feature and property elementwill be examined in section @@@@. We will explain the bindingfault and operation constructs in thefollowing sections.

5.1.1 Binding Faults

A binding fault describes a concrete binding of anabstract fault within an interface to a particular concrete messageformat. More precisely, it describes how faults that occur within amessage exchange of an operation will be formatted since the faultdoes not occur by itself - it occurs as part of a message exchangeas defined by an interface operation and its bindingcounterpart the binding operation .

A binding fault has one required refattribute which is a reference, by Qname, to aninterface fault . It identifies theabstract interface fault for which binding informationis being specified. Be aware that the value of refattribute of all the faults under abinding MUST be unique. That is, one cannot definemultiple bindings for the same interface fault within a givenbinding .

5.1.2Binding Operations

A binding operation describes a concrete binding ofa particular operation of an interface to a particular concretemessage format.A particular operation of an interface is uniquelyidentified by the WSDL target namespace of the interface and thename of the operation within that interface, via the requiredref attribute of binding operation . Foreach operation within a binding , thevalue of ref attribute MUST be unique. That is, onecannot define multiple bindings for the same interface operationwithin a given binding .

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

Corresponding to its interface operationcounterpart, binding operation may also have zero ormore input ,output , infault, and/or outfault . The presence or absence of thesemessage and/or fault reference constructs within a particularbinding operation is governed by the interfaceoperation counterpart.

5.2Extensions for SOAP Binding

Example 5-1. SOAPbinding example placeholder - to be completed

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

</description>

5.3Extensions for HTTP Binding

Example 5-2. HTTPBinding example placeholder - to be completed

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

</description>

6. More on ServiceEndpoints

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

As described previously, the service constructspecifies a set of alternate endpoints at which a service isavailable. Zero or more services can be defined withina description element. However, each service islimited to a single interface. The XML syntax ofservice is summarized below:

<description targetNamespace="xs:anyURI" >

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

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

</description>

A service has a required nameattribute (also see section @@@@ for service reference). Eachservice within a same namespace must be nameduniquely. A service can only implement one singleinterface, and it must specify the single interface it implementsvia the interface attribute.

A service may contain one or more alternateendpoints . An endpoint defines theparticulars of a specific endpoint at which a given service isavailable.

An endpoint has two required attributes:name and binding . Allendpoints within a service must be nameduniquely via the name attribute. The requiredbinding attribute refers to, via Qname, abinding definition. Note that if the referedbinding specifies a particular interface, thatinterface MUST be the same as the one implmented by the parentservice .

Like the WSDL binding constructs explained in section @@@@, theWSDL endpoint construct is also like an anchor forhosting extension elements that are used to provide informationspecific to a particular endpoint in a server. The semantics ofsuch extensions are defined by the specification for thoseextensions. Such specifications are expected to annotate the WSDLendpoint construct with additional properties andspecify the mapping between those properties and the XMLrepresentation. For example, The SOAP and HTTP binding extensionsdefined in WSDL 2.0 part 3 also provides extensions to be usedunder a service endpoint .

7. Advanced Topics -TBD

Editorial note:KevinL20040526This section is veryincomplete, and topics are still TBD.

7.1Extensibility

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

In either case, the URI that identifies the semantics of anextension SHOULD be dereferenceable to a document that describesthe semantics of that extension. As of this writing, there is nogenerally accepted standard for what kind of document that shouldbe. However, the W3C TAGhas been discussing the issue (see TAG issue namespaceDocument-8) and is likely to provide guidance at somepoint.

7.1.1 Optional Versus RequiredExtensions

Extensions can either be required or optional: Anoptional extension is one that the requester agent mayeither engage or ignore, entirely at its discretion, and issignaled by attribute wsdl:required="false"; whereas arequired extension is one that MUST be supported andengaged by the requester agent in order for the interaction tosucceed properly, and is signaled by attributewsdl:required="true".

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

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

7.1.2 Scoping of the wsdl:requiredAttribute

Editorialnote To do: Need to check thescoping rules to see if this is correct.

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

Because portions of a Web service description can be written indifferent physical documents by different people, one should becautious about setting wsdl:required="false" when anouter scope, written by someone else, had setwsdl:required="true".

7.2 Features andProperties

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

7.3 Import mechanism and authoringstyle

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

7.4 MultipleLogical WSDL Documents Describing the Same Service

[Acknowledge that multiple logical WSDL documents might try todescribe the same service. Explain why some might do thisintentionally, why it might cause problems for some systems, andexplain that this is outside scope of the WSDL language. See threadstarting athttp://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html]

7.5 Versioningand Service Equivalency

[ See also http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html]

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

7.6 MTOM Support

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

7.7 SecurityConsiderations

7.8 OperationStyle and RPC

7.9 Enabling Easy Message Dispatch

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

One technique is to ensure that the top-level elements declaredin the message schema are different for different operations. Thisis probably the most general solution, since it is guaranteed toprovide a way to perform dispatch, without preventing toolkits frompotentially using other dispatch techniques.

Another technique is to define a required feature that enables aparticular dispatching convention. This approach makes thedispatching convention explicit, although it may not be supportedby every WSDL toolkit.

7.10 GETVersus POST: Which to Use?

[Add material fromhttp://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.htmlthat prescribes when to use GET versus POST as well as some usefulexample]

7.11 Service References

[Usehttp://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.htmlas a starting point. Also example(s) from Roberto per theresolution at the end ofhttp://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html]

7.12 XML Schema Examples

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

7.13 Multiple In-LineSchemas

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

7.14The schemaLocation Attribute

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

7.15 Mappingto RDF and Semantic Web

7.16Notes on URIs

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

7.16.1 XML Namespaces andSchema Locations

It is a common misperception to equate either the targetnamespace of an XML Schema or the value of the xmlnsattribute in XML instances with the location of the correspondingschema. 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 onlyschema that is associated with that namespace. There can bemultiple schemas associated with a particular namespace, and it isup to a processor of XML to determine which one to use in aparticular processing context. The WSDL specification provides theprocessing context here via the import mechanism,which is based on XML Schema's term for the similar concept.

7.16.2Relative URIs

Throughout this document there are fully qualified URIs used inWSDL and XSD examples. The use of a fully qualified URI is simplyto illustrate the referencing concepts. The use of relative URIs isallowed and warranted in many cases. For information on processingrelative URIs, see RFC2396.

7.16.3 Generating URIs

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

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

8. References

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

8.1 Normative References

[IETF RFC2119]: Key wordsfor use in RFCs to Indicate Requirement Levels, S.Bradner, Author. Internet Engineering Task Force, June 1999.Available at http://www.ietf.org/rfc/rfc2119.txt.
[IETF RFC2396]: UniformResource Identifiers (URI): Generic Syntax, T.Berners-Lee, R. Fielding, L. Masinter, Authors. InternetEngineering Task Force, August 1998. Available athttp://www.ietf.org/rfc/rfc2396.txt.
[XML 1.0]: Extensible MarkupLanguage (XML) 1.0 (Second Edition), T. Bray, J. Paoli,C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide WebConsortium, 10 February 1998, revised 6 October 2000. This versionof the XML 1.0 Recommendation ishttp://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 isavailable at http://www.w3.org/TR/REC-xml.
[XMLInformation Set]: XMLInformation Set, J. Cowan and R. Tobin, Editors. WorldWide Web Consortium, 24 October 2001. This version of the XMLInformation Set Recommendation ishttp://www.w3.org/TR/2001/REC-xml-infoset-20011024. The latest version of XMLInformation Set is available athttp://www.w3.org/TR/xml-infoset.
[XMLNamespaces]: Namespaces inXML, T. Bray, D. Hollander, and A. Layman, Editors.World Wide Web Consortium, 14 January 1999. This version of the XMLInformation Set Recommendation ishttp://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespacesin XML is available at http://www.w3.org/TR/REC-xml-names.
[XMLSchema: Structures]: XML SchemaPart 1: Structures, H. Thompson, D. Beech, M. Maloney,and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001.This version of the XML Schema Part 1 Recommendation ishttp://www.w3.org/TR/2001/REC-xmlschema-1-20010502. The latest version of XML SchemaPart 1 is available at http://www.w3.org/TR/xmlschema-1.
[XMLSchema: Datatypes]: XML SchemaPart 2: Datatypes, P. Byron and A. Malhotra, Editors.World Wide Web Consortium, 2 May 2001. This version of the XMLSchema Part 2 Recommendation ishttp://www.w3.org/TR/2001/REC-xmlschema-2-20010502. The latest version of XML SchemaPart 2 is available at http://www.w3.org/TR/xmlschema-2.
[RFC3023]: IETF "RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D.Kohn, July 1998. (See http://www.ietf.org/rfc/rfc3023.txt.)
[WSDL MediaType]: IETF Internet Draft "The 'application/wsdl+xml' media type",@@@. (Work to be done once we have consensus on the mediatype).
[WSDL2.0 Core Language]: Web ServicesDescription Language (WSDL) Version 2.0 Part 1: CoreLanguage, R. Chinnici, M. Gudgin, J-J. Moreau, A. Ryman,J. Schlimmer, S. Weerawarana, Editors. World Wide Web Consortium, 3August 2004. This version of the "Web Services Description Language(WSDL) Version 2.0 Part 1: Core Language" Specification isavailable at http://www.w3.org/TR/2004/WD-wsdl20-20040803. Thelatest version of "WebServices Description Language (WSDL) Version 2.0 Part 1: CoreLanguage" is available at http://www.w3.org/TR/wsdl20.
[WSDL2.0 Predefined Extensions]: WebServices Description Language (WSDL) Version 2.0 Part 2: PredefinedExtensions, M. Gudgin, A. Lewis, and J. Schlimmer,Editors. World Wide Web Consortium, 3 August 2004. This version ofthe "Web Services Description Language (WSDL) Version 2.0 Part 2:Predefined Extensions" Specification is available athttp://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803. Thelatest version of"Web Services Description Language (WSDL) Version 2.0 Part 2:Predefined Extensions" is available athttp://www.w3.org/TR/wsdl20-extensions.
[WSDL2.0 Bindings]: WebServices Description Language (WSDL) Version 2.0 Part 3:Bindings, H. Haas, P. Le Hégaret, J-J. Moreau, D.Orchard, J. Schlimmer, S. Weerawarana, Editors. World Wide WebConsortium, 3 August 2004. This version of the "Web ServicesDescription Version 2.0: Bindings" Specification is available athttp://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803. The latest version of "WebServices Description Language (WSDL) Version 2.0 Part 3:Bindings" is available athttp://www.w3.org/TR/wsdl20-bindings.
[WebArchitecture]: Architecture ofthe World Wide Web, Volume One, Ian Jacobs, NormanWalsh, Editors. W3C Technical Architecture Group, 15 December,2004. Available at http://www.w3.org/TR/2004/REC-webarch-20041215/.
[WSArchitecture]: Web ServicesArchitecture, David Booth, Hugo Haas, Francis McCabe,Eric Newcomer, Michael Champion, Chris Ferris, David Orchard,Editors. W3C Web Services Architecture Working Group, 11 February2004. Available at http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/.
[WSGlossary]: Web ServicesGlossary, Hugo Haas, Allen Brown, Editors. W3C WebServices Architecture Working Group, 11 February 2004. Available athttp://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/ .

8.2 Informative References

[IETF RFC2045]: Multipurpose Internet MailExtensions (MIME) Part One: Format of Internet MessageBodies, N. Freed, N. Borenstein, Authors. InternetEngineering Task Force, November 1996. Available athttp://www.ietf.org/rfc/rfc2045.txt.
[IETF RFC2616]: HypertextTransfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys,J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee,Authors. Internet Engineering Task Force, June 1999. Available athttp://www.ietf.org/rfc/rfc2616.txt.
[SOAP 1.1]: Simple ObjectAccess Protocol (SOAP) 1.1, D. Box, D. Ehnebuske, G.Kakivaya, A. Layman, N. Mendelsohn, H. Frystyk Nielsen, S. Thatte,D. Winer, Editors. World Wide Web Consortium, 8 May 2000. Thisversion of the Simple Object Access Protocol 1.1 Note ishttp://www.w3.org/TR/2000/NOTE-SOAP-20000508.
[SOAP 1.2 Part 1: Messaging Framework]: SOAP Version1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley,N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World WideWeb Consortium, 24 June 2003. This version of the "SOAP Version 1.2Part 1: Messaging Framework" Recommendation ishttp://www.w3.org/TR/2003/REC-soap12-part1-20030624/. The latest version of "SOAPVersion 1.2 Part 1: Messaging Framework" is available athttp://www.w3.org/TR/soap12-part1/.
[XML Linking]: XML LinkingLanguage (XLink) Version 1.0, S. DeRose, E. Maler, D.Orchard, Editors. World Wide Web Consortium, 27 June 2001. Thisversion of the XML Linking Language 1.0 Recommendation ishttp://www.w3.org/TR/2001/REC-xlink-20010627. The latest version of XML LinkingLanguage 1.0 is available at http://www.w3.org/TR/xlink.
[WSDL 1.1]: Web ServicesDescription Language (WSDL) 1.1, E. Christensen, F.Curbera, G. Meredith, and S. Weerawarana, Authors. World Wide WebConsortium, 15 March 2002. This version of the Web ServicesDescription Language 1.1 Note ishttp://www.w3.org/TR/2001/NOTE-wsdl-20010315. The latest version of Web ServicesDescription Language 1.1 is available athttp://www.w3.org/TR/wsdl.
[WSDRequirements]: Web ServicesDescription Requirements, J. Schlimmer, Editor. WorldWide Web Consortium, 28 October 2002. This version of the WebServices Description Requirements document ishttp://www.w3.org/TR/2002/WD-ws-desc-reqs-20021028. The latest version of Web ServicesDescription Requirements is available athttp://www.w3.org/TR/ws-desc-reqs.
[XPointerFramework]: XPointerFramework,Paul Grosso, Eve Maler, Jonathan Marsh, NormanWalsh, Editors. World Wide Web Consortium, 22 November 2002. Thisversion of the XPointer Framework Proposed Recommendation ishttp://www.w3.org/TR/2003/REC-xptr-framework-20030325/ The latest version of XPointerFramework is available athttp://www.w3.org/TR/xptr-framework/.