1. Prerequisites
This primer assumes that the reader has the following prerequisite knowledge:
familiarity with XML (@@reference@@);
familiarity with XML Namespaces (@@reference@@);
familiarity with basic Web concepts and architecture (@@reference@@).
No previous knowledge of Web services or Web service descriptions is required.
2. Introduction
This section provides a conceptual introduction to Web services and Web service descriptions. Its purpose is twofold:
to introduce concepts and define terms that are used elsewhere; and
to provide the "big picture" context for WSDL 1.2, so that the reader has a clearer understanding of what WSDL 1.2 is and isn't.
2.1 What Is a Web Service?
A traditional Web application is designed to take input from a human user and display output to a human user, as illustrated below. The user's browser and the Web server that hosts the Web application act as intermediaries. The output of the application is typically in HTML, for convenient display to the human user sitting at a browser, and the input is typically provided through HTML forms.
In contrast, a Web service is an application or application component that is accessible on the Web and is intended to be used by another application -- the client application, as illustrated below. The output of a Web service is intended to be in a format that is easy for the client application to use. In general, the input and output of a Web service will be in some kind of XML format.
2.2 Examples of Web Services
One example of a Web service might be a credit card transaction service. A Merchant application that wishes to accept credit card purchases could simplify its task by making use of a credit card transaction service. Another example might be taxation service. Given an item, a price and a location, a taxation service could computer the applicable federal, state and local taxes that should be collected on the item. A third example might be a printer service. A personal digital assistant (PDA) might wirelessly locate a printer service in its physical vicinity in order to print a document. A fourth example might be a travel service that sells travel packages. In fact, the travel service itself may make use of other Web services as means of imlementing its own Web services, such as a credit card transaction service, a taxation service, hotel services, airline services, etc., as illustrated below. (The small, darker colored boxes represent the communication interfaces or "stubs"/"skeletons" that are used by client and service.)
2.3 Clients and Services
It is important to bear in mind that the terms "client" and "service" are relative terms. An application that acts as a Web service in one instance may also act as a client to some other Web service. For example, the travel service illustrated above acts as a service to its client application, but it also acts as a client to the credit card, hotel and airline services that it uses to implement its own service.
The relative nature of the client and service roles can be confusing if we are not consistent in our use of terms, since a client's input is a Server's output, and vice versa. Therefore, to help avoid confusion, we will generally speak from the Web service's point of view unless otherwise indicated. So for example, if we talk about "input", then we mean "input to the Web service" (which would be output from the client).
2.4 Motivation for Web Service Descriptions
Clearly, if a Web service and a client are going to interact meaninfully with each other, they will need to agree on the purpose and mechanics of the interaction, so that they know what to expect of each other. Ideally, these expectations should be stated explicitly, in a machine-processable document that both parties can access.
In principle, there are several ways these expectations could be expressed in a document. For example, the document could describe only the expectations (think "inputs") of both the client and the service. By inference, the functionality (think "outputs") of the corresponding service or client would have to at least meet the other's expectations. Or, the document could describe only the functionality of both the client and the service. By inference, the expections of the corresponding service or client would have to be no greater than the other's functionality.
Another way to express these expectations in a document is to view the problem only from the point of view of one party, and describe both its expectations and its functionality (again, think "inputs" and "outputs"). For example, if the document is written entirely from the point of view of the Web service, the document would describe the expectations and the functionality of the Web service. By inference, the functionality of a potential client would have to at least meet the service's declared expectations, and the expectations of the client would have to be no greater than the service's declared functionality. This is the basic idea behind a Web service description.
2.5 Web Service Descriptions
A Web service description is an machine-processable document that describes the expectations and functionality of a particular Web service, so that a potential client can read the description and understand how to correctly interact with the service. Even though it is written solely from the point of view of the Web service -- that's why it's called a Web service description -- it is inherently intended for use by both the client and the service. It represents a take-it-or-leave-it "contract" that specifies how they should interact.
This is illustrated in the diagram below, in which one Web service description (the green one) defines the interaction between the travel service and its client application, another Web service description (blue) defines the communication between the travel service and the credit card service (with the travel service acting as the client of the credit card service), another Web service description (magenta) defines the travel service's interaction with the hotel services (one or more), and another Web service description (brown) defines the interaction with one or more airline services.
2.6 Machine Processable Languages Versus Human Languages
There are several benefits in using a machine-processable language for Web service descriptions, rather than a human language (such as English):
Precision. Formal, machine-processable languages are much more precise than natural languages.
Software tools can automatically generate "stub" and "skeleton" code that the client and service can use to more easily implement their applications.
Dynamic discovery and use. If a Web service is adequately described by its Web service description, then a potential client can dynamically read the description, decide whether the service meets that client's needs, and invoke that service automatically. For example, you may want your Personal Digital Assistant (PDA) to dynamically discover a nearby color printer service.
Arbitration. A third party can easily determine whether the client and/or service are interacting in a way that conforms to the Web service description.
2.7 The Need for Explicit Semantics
To fully understand WSDL 1.2 in context, it is helpful to know not only what it does do, but also what it doesn't do. This section takes a brief look at the need for explicit semantics and explains how that need relates to WSDL 1.2.
2.7.1 Why Should Semantics Be Described?
Clearly, if any client and Web service are going to interact sensibly, they must agree not only on the mechanics of the interaction -- the message formats, data types and protocols -- but they must also agree on the meaning and purpose of the interaction. In other words, they must agree on the semantics. For example, what are the consequences of sending a "PurchaseOrder" message? Money will be transfered from the buyer to the seller, and goods will be shipped! What happens if a printer service receives a "PrintDocument" message? The printer starts spewing out printed pages! Furthermore, your PDA must have a way of selecting a printer service with the appropriate semantics -- such as color printing -- not just any service that accepts "PrintDocument" message formats.
Another way to view semantics is to think about the context in which the client - service interaction occurs. For example, a "PurchaseOrder" message is intended to occur in the context of a business-level agreement to purchase goods. Or, a "ShippingReceipt" may be sent in the context of a pending PurchaseOrder. The context determines the semantics of the interaction.
In our day-to-day world of human activities, interactions often occur under implied agreements, semantics or contexts, instead of being explicit. For example, you might receive a shipping receipt that does not identify the purchase order to which it pertains. Although we humans are generally flexible enough to cope with the ambiguity this creates, it is always clearer if the semantics or context of an interaction are explicit. Furthermore, if we wish to automate our human processes using Web services, then it is even more important to be explicit, because machines are not nearly as good as humans at dealing with ambiguity.
2.7.2 How Can Semantics Be Described?
There are two ways semantics can be described: either in a human language, such as English; or in a machine-processable language, such as RDF. Of course, the benefit of a machine processable language is that it allows more automated service selection and processing. For example, a "marketplace" can be created, in which clients can select Web services dynamically, by analyzing their semantics.
What if semantics are not described in a machine-processable language? Could explicit semantics still be useful to Web services if they are expressed only in human languages? Yes. Making semantics explicit in any form still helps to facilitate machine processing. For example, if two parties can unambiguously identify the semantic agreement under which they will interact (either by its URL, or its checksum, or by some other means), then those parties can be sure they are "speaking the same language" -- both syntactically and semantically -- without relying on human intervention, even if the agreement itself is written in a human language that is not machine processable.
2.7.3 Where Should Semantics Be Described?
A Web service description is nearly useless if you don't know its semantics. So where should its semantics be described? How can a potential client know where to find the semantics? Here are some possibilities:
The semantics could be described using some ad-hoc, out-of-band mechanism that is not indicated in the Web service description. This option is clearly undesireable, because it means that an agent discovering a Web service description would have no deterministic way of locating that description's semantics.
The semantics could be described directly within a designated section of the Web service description document. This is somewhat reasonable, but it's a little impractical, because the software that processess the Web service description is unlikely to be the same software (or human) that will need to read the semantics.
The semantics could be described in a separate document that is referenced by the Web service description, such as by including the URL of the document that describes the semantics, as illustrated below. This is the approach taken by WSDL 1.2. (WSDL 1.2 uses the "targetNamespace" URL for this purpose.)
2.8 Web Service Discovery
Web service discovery refers to the ability to dynamically find a Web service that meets the application's needs. For example, I may wish to dynamically discover a nearby printer service, in order to print out a document from my PDA.
Actually, the term "discovery" is somewhat ambiguous, for two reasons. First, because there are two kinds of "discovery" that people often discuss: (a) the act of finding a previously unknown service that meets the application's needs; and (b) the act of selecting one from among several candidate services that are already known (and trusted). These two kinds have quite different needs and implications. Second, different assumptions are often made about who is expected to perform the "discovery" -- a human or an application. Again, the interface and trust implications are quite different.
Several means of Web service discovery have been proposed, some representing centralized solutions (such as UDDI), and some being decentralized (such as conventional Web searching). WSDL 1.2 does not address the problem of Web service discovery, but WSDL 1.2 is intended to be used by discovery mechanisms that provide additional value to a client seeking a particular kind of Web service. For example, a discovery mechanism might provide convenient ways to categorize Web services, or it might provide data on the reliability or trustworthiness of the vendors whose Web services are listed.
Clearly, semantics are important to discovery, because the client needs to find or select a Web service that has the desired semantics. However, if a Web service description is complete enough to describe the syntax for interacting with the service, and the semantics of the interaction (or at least to unambiguously identify the semantics), then a client will be able to use a potential service regardless of how the service is discovered.
2.9 Creating Markets of Clients and Services
One obvious potential use of Web services is to create Web-based markets, in which clients and services are matched and invoked dynamically by an automated broker. For example, buyers of a particular product might be matched with sellers, as illustrated below. 
Although this use is beyond the scope of what WSDL 1.2 attempts to address, WSDL could be one component of a larger solution for this problem. However, due to the asymmetric nature of WSDL (focusing on describing only the Web service -- not the client), it is currently unclear how clients would be described and what role WSDL play.
2.10 Creating Applications and Web Service Descriptions: Which Comes First?
There are two main approaches currently in use for creating Web service descriptions and their corresponding applications:
- Top Down
Write the Web service description first, and then use it to automatically generate "stub" and "skeleton" code that is then filled in to create the corresponding application.
- Bottom Up
Start with existing classes or other application code, and automatically generate a Web service description from them.
Both approaches are useful. For the purpose of this primer, we will take the top down approach, partly because it allows us to avoid dependency on a specific programming language.
3. Fundamental Concepts of WSDL 1.2
This section outlines the basic concepts that underly the design of WSDL 1.2.
4. Defining an Abstract Interface of a Web Service
This section introduces the WSDL 1.2 mechanisms for defining an abstract interface to a Web service, independeint of the specific Web address and transport protocols that are used to implement the Web service. Later (in Section @@@@), we will show how a "binding" is used to associate an abstract interface with a specific Web address and transport protocol. Material in this section roughly corresponds to @@part 1 of the WSDL 1.2 Specification@@.
[explain the key difference of interface for web services and for traditional distributed computing:
- for traditional distributed technology, API are tied to implementation signature, change of signature will break the linkage
- for web services, the wired message is the real interface. service implementation and service client are loosely coupled as long as both share a common understanding of the message exchanged. wsdl is the language used to describe the message exchanged.The application API can be changed as long as the messages remains the same]
[Explain the overall WSDL structure, ideally show a diagram showing different logic components of WSDL in different color: Data, Abstract Interface, Binding, Services]
[Abstract definition constructs provide a way to define and group related data as input /outputs of a web service. It should be independant of the underlying transportation protocol and any implementation language. ]
4.1 Example Application: Hotel Reservation Service
As a vehicle for discussing WSDL 1.2, we describe a hypothetical hotel reservation service. A client making use of our hotel service will be able to:
Request a room reservation;
Receive confirmation of a room reservation;
@@@@
@@@@
4.2 The Root of All WSDL Files
[WSDL files are XML instance document. ]
[WSDL 1.2 defines a set of XML schemas that guide the creation of WSDL instance files. ]
[All wsdl constructs are defined as children of <definitions>. ]
[Explain the typical usage of namespaces here]
[Kevin: I think this first example should omit anything that is binding-specific. Later, when we introduce bindings, we can add the binding-specific information. -- D.Booth]
<?xml version="1.0" encoding="utf-8"?> <definitions name="example0" targetNamespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://www.w3.org/webServicesDescription12/PrimerExamples/example0">
[more contents here, eg. @name vs. @targetNamespace, versioning etc]
4.3 Define the data and messages to be exchanged
[WSDL is all about describing the data a web service provides to and get from a client, and how this data will be exchanged based on the underlying transportation protocols]
[WSDL provides a modular constructs that allows a services to separate the description of message payload from description of the tranport protocol used to transmit the message]
[using the <types> construct, data types can be defined in any type system. By default, WSDL 1.2 use W3C XML Schema]
[<message> construct adds an additional abstraction layer which connects the data type defintions to WSDL operations. ]
[In its simpliest form, built-in xml schema data types can be directly used in <message>]
[when define the input message and output message of a service, try to keep yourself away from thinking about how the message willbe transported, and how the service will use the data. Keep it in the abstract level, just think about what the service will need, and what it will provide to its clients]
[Explain there are many different ways to define the same message, eg.: element vs. type, simple types vs. complex types]
<message name="inReserveRoom"> <part name="customreName" type="xs:string"/> <part name="checkInDate" type="xs:date"/> <part name="checkOutDate" type="xs:date"/> <part name="roomType" type="xs:string"/> <part name="comments" type="xs:string"/> <part name="agentID" type="xs:string"/> </message>
[explain the data needed to make a hotel reservation and how XSD can used here]
[explain what's a part and point out its role of linking a data type system to the WSDL message construct]
<message name="outReserveRoom"> <part name="roomRate" type="xs:double"/> <part name="reservationID" type="xs:string"/> </message>
[explain the data a hotel reservation service typically provide and how XSD can used here]
<types> <xs:schema elementFormDefault="qualified" targetNamespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"> <xs:element name="eRoomType" type="tRoomType"/> <xs:simpleType name="tRoomType"> <xs:restriction base="xs:string"> <xs:enumeration value="Single"/> <xs:enumeration value="Double"/> <xs:enumeration value="Queen"/> <xs:enumeration value="King"/> </xs:restriction> </xs:simpleType> </xs:schema> </types>
[room types only allow enumerated values]
[a part may refer to a XSD element using the element AII, or refer to a XSD complex or simple type using the type AII]
<message name="inReserveRoom"> <part name="customreName" type="xs:string"/> <part name="checkInDate" type="xs:date"/> <part name="checkOutDate" type="xs:date"/> <part name="roomType" element="tns:eRoomType"/> <part name="comments" type="xs:string"/> <part name="agentID" type="xs:string"/> </message>
[more contents here]
<message name="inReserveRoom"> <part name="customreName" type="xs:string"/> <part name="checkInDate" type="xs:date"/> <part name="checkOutDate" type="xs:date"/> <part name="roomType" type="tns:tRoomType"/> <part name="comments" type="xs:string"/> <part name="agentID" type="xs:string"/> </message>
[more contents here]
<types> <xs:schema elementFormDefault="qualified" targetNamespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"> <xs:element name="eReserveRoom" type="tReserveRoom"/> <xs:complexType name="tReserveRoom"> <xs:sequence> <xs:element name="customreName" type="xs:string"/> <xs:element name="checkInDate" type="xs:date"/> <xs:element name="checkOutDate" type="xs:date"/> <xs:element name="roomType" type="xs:string"/> <xs:element name="comments" element="xs:string"/> <xs:element name="agentID" type="xs:string"/> </xs:sequence> <xs:attribute name="mustUnderstand" type="xs:boolean" default="false"/> <xs:attribute name="actor" type="xs:anyURI"/> </xs:complexType> </xs:schema> </types> <message name="inReserveRoom"> <part name="ReserveRoom" type="tns:eReserveRoom"/> </message>
[more contents here]]
4.4 Operation and Different Transmission Primitives
[explain what differentiate a WSDL operation from the term used in traditional programming language. WSDL operation is not an API. It's nothing but a construct to group a input message and output message]
[major constructs include <input>, <output> and <fault>, different combinations of these constructs imply different patterns of message exchange: eg. request-response]
[Note that these combination is orthognal to syncronization and asyncronization which is more related to the bindings]
[Needs updates from the spec]
<operation name="ReserveRoom"> <input message="inReserveRoom"/> <output message="outMessage"/> </operation>
[explain the potential impact of name AII on the wired message. Refer to later sections for RPC vs Document]
[explain how message AII connects to the data set defintion - any real benefit of using message EII when XSD is the data type system in use?]
[more contents here]
4.5 portType and serviceType
[why do we need the portType and serviceType construct? how do they help provide a modular and flexible mechanism for describing a abstract service]
[how will these abstract constructs help define binding details and run time services, may refer to later sections]
<portType name="ptHotelReservation"> <operation name="oReserveRoom"> <input message="inReserveRoom"/> <output message="outMessage"/> </operation> </portType> <serviceType name= "stHotelReservation"> <portType name="ptHotelReservation"/> </serviceType>
[more contents]
5. Bind Abstract Interface to Concrete Protocols
[why it's important to separate a abstract interface definition from the binding details]
[brief introduction to the three normative bindings defined in WSDL1.2: SOAP, HTTP, and SMTP]
[demostrate how this constructs are related to the abstract definition]
- explain the reusability of binding details]
- explain the "inheritance" mechanism of the binding constructs]
[given the current status of part 2 spec, there is not too much the primer can do at the time being]
5.1 Bind the Reserve Room service to SOAP
[explain the import role of soap and the close connection between WSDL and SOAP]
[how does wsdl deal with different versions of SOAP: 1.1 vs. 1.2]
<binding name="bndHotelReservationSOAP" type="tns:ptHotelReservation"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> <operation name="oReserveRoom"> <soap:operation soapAction=" "/> <w:input> <soap:body use="literal" namespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"/> <soap:header message="tns:ShipGoodsRequest" parts="ContextHeader" use="literal" namespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"> <soap:headerfault message="tns:ContextFaultMessage" parts="ContextFault" use="literal" namespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"/> </soap:header> </w:input> <w:output> <soap:body use="literal" namespace="http://www.w3.org/webServicesDescription12/PrimerExamples/example0"/> </w:output> </operation> </binding>
[explain how "inheritance" works in this example]
5.1.1 Where do the parts go in the wire?
[soap body vs header - application decision]
place holder
[more contents here]
place holder
[more contents here]
5.1.2 SOAP operation styles: RPC vs Document
[brief intro to SOAP RPC convention and how WSDL describe the RPC convention]
[explain how the styles impact the message payload eg. RPC wrapper element]
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Body> <reserveRoom> <customerName>Kevin Liu</customerName> <checkInDate>2002-09-01</checkInDate> <checkOutDate>2002-09-10</checkOutDate> <roomType>double</roomType> <comments>the customer will be arriving late in the evening</comments> </reserveRoom> </env:Body> </env:Envelope>
[need update to reflect changes in part 2]
[explain that same soap message can also be described usign document style and message for example 7, and why document style makes more sense in the web services world
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Body> <customerName>Kevin Liu</customerName> <checkInDate>2002-09-01</checkInDate> <checkOutDate>2002-09-10</checkOutDate> <roomType>double</roomType> <comments>the customer will be arriving late in the evening</comments> </env:Body> </env:Envelope>
[need update to reflect changes in part 2]
[this is just a example for the sake of explaining concepts - not really make sense in really world]
6. Advanced Topics - TBD
Import mechanism and authoring style - Extensibility - Security Considerations - Versioning and services equivalency - Mapping to RDF and semantic web - Differences b/t WSDL1.2 and WSDL1.1?