Describing Web Services using DAML-S and WSDL

DAML-S Coalition working document; August 2002

This version:: http://www.daml.org/services/daml-s/0.7/daml-s-wsdl.html
Latest version:: http://www.daml.org/services/daml-s/0.7/daml-s-wsdl.html
Authors:
David Martin
Mark Burstein: Ora Lassila; Massimo Paolucci; Terry Payne; Sheila McIlraith

Abstract

The DAML Services arm of the DARPA Agent Markup Language program is developing a DAML-based Web Service Ontology, named DAML-S, as well as supporting tools and agent technology to enable automation of services on the Semantic Web. DAML-S supplies Web service providers with a core set of markup language constructs for describing the properties and capabilities of their Web services in unambiguous, computer-intepretable form. DAML-S markup of Web services will facilitate the automation of Web service tasks including automated Web service discovery, execution, interoperation, composition and execution monitoring.

WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate, however, the only bindings described in this document describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

[WSDL 1.1, Abstract]

The extensibility elements of WSDL allow for a straightforward means of using DAML-S and WSDL together. This, in turn, allows service developers to take advantage of the complementary strengths of these two specification languages. This document, which is written in an informal, tutorial style, describes how this combined use of DAML-S and WSDL is accomplished, and in particular focuses on the way WSDL is used in this combination.

For ease of reference, and to be helpful to readers not already familiar with WSDL, this document includes selected quotations from the WSDL 1.1 specification, which are helpful in explaining the relevant aspects of WSDL. Each such quotation is indented, displayed in a distinct font (Arial), and immediately followed by a bracketed citation. In addition, when viewed online or in a color printout, these quotations will appear in green. Also for ease of reference, a number of the section headings of this document (for example, 2.3 Messages) correspond to section headings in the WSDL 1.1 specification.

This document does not explain the concepts or details of DAML-S, but rather assumes a basic familiarity with selected DAML-S constructs (particularly the atomic process), which may be acquired from the Technical Overview and related documents in the current release of DAML-S, available at http://www.daml.org/services/daml-s/0.7/. Note that the Technical Overview contains a Grounding section that gives the conceptual background for this approach.

1 Introduction.

1.1 DAML-S / WSDL Document Example
2 Service Grounding With WSDL
2.1 WSDL Document Structure and Extensions for DAML-S
2.2 Types
2.3 Messages
2.4 Port Types
2.4.1 One-way Operation
2.4.2 Request-response Operation.
2.4.3 Solicit-response Operation
2.4.4 Notification Operation
2.4.5 Mapping DAML-S Processes to WSDL Operations
2.5 Bindings

1. Introduction

Web Services Description Language (WSDL) specifies a protocol- and encoding-independent mechanism for Web Service providers to describe the means of interacting with offered services. WSDL is an XML vocabulary which describes network-reachable services and maps these to a messaging-capable collection of communication endpoints. WSDL separates the abstract definition of service and messages from their concrete binding to a network port and message format. The current WSDL specification describes concrete bindings for SOAP, HTTP GET/POST, and MIME. WSDL 1.1 is a submission to the World Wide Web Consortium.

DAML-S allows for the description of a Web service in terms of a Profile, which tells "what the service does", a Process Model, which tells "how the service works", and a Grounding, which tells "how to access the service". The Profile and Process Model are considered to be abstract specifications, in the sense that they do not specify the details of particular message formats, protocols, and network addresses by which a Web service is instantiated. The role of the Grounding is to provide these more concrete details. The Web Services Description Language (WSDL), developed independently of DAML-S, provides a well developed means of specifying these kinds of details, and has already acquired considerable visibility within the commercial Web services community. Therefore, the authors of DAML-S have chosen to define conventions for using WSDL to ground DAML-S services. This document provides an informal explanation of these conventions.

It may readily be observed that DAML-S' concept of grounding is generally consistent with WSDL's concept of binding. Indeed, by using the extensibility elements already provided by WSDL, along with one new extensibility element proposed here, it is an easy matter to ground a DAML-S atomic process. In this document, we show how this may be done, relying on the WSDL 1.1 specification. With only one exception, everything here is done using WSDL extensibility elements. The one exception is a proposed new attribute for the WSDL operation declaration, which is used to show the correspondence between the given WSDL operation and a DAML-S atomic process (see Section 2.4.7).

Whereas a default WSDL specification refers to XSD primitive data types, and composite data types defined using XSD, a DAML-S/WSDL specification can refer to DAML classes (in addition to the XSD primitive and defined types). The DAML classes can either be defined within the WSDL spec, or defined in a separate document and referred to from within the WSDL spec.

We emphasize that a DAML-S/WSDL grounding involves a complementary use of the two languages, in a way that is in accord with the intentions of the authors of WSDL. Both languages are required for the full specification of a grounding. This is because the two languages do not cover the same conceptual space. As discussed in http://www.daml.org/services/daml-s/0.7/GroundingIntro.pdf, the two languages do overlap in the area of providing for the specification of what WSDL calls ``abstract types'', which in turn are used to characterize the inputs and outputs of services. WSDL, by default, specifies abstract types using XML Schema, whereas DAML-S allows for the definition of abstract types as (description logic-based) DAML+OIL classes. However, WSDL/XSD is unable to express the semantics of a DAML+OIL class. Similarly, DAML-S has no means, as currently defined, to express the binding information that WSDL captures. Thus, it is natural that a DAML-S/WSDL grounding uses DAML+OIL classes as the abstract types of message parts declared in WSDL, and then relies on WSDL binding constructs to specify the formatting of the messages.

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definition of endpoints and messages is separated from their concrete network deployment or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types which are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitutes a reusable binding. A port is defined by associating a network address with a reusable binding, and a collection of ports define a service. Hence, a WSDL document uses the following elements in the definition of network services:

Types– a container for data type definitions using some type system (such as XSD).
Message– an abstract, typed definition of the data being communicated.
Operation– an abstract description of an action supported by the service.
Port Type–an abstract set of operations supported by one or more endpoints.
Binding– a concrete protocol and data format specification for a particular port type.
Port– a single endpoint defined as a combination of a binding and a network address.
Service– a collection of related endpoints.

These elements are described in detail in Section 2. It is important to observe that WSDL does not introduce a new type definition language. WSDL recognizes the need for rich type systems for describing message formats, and supports the XML Schemas specification (XSD) as its canonical type system. However, since it is unreasonable to expect a single type system grammar to be used to describe all message formats present and future, WSDL allows using other type definition languages via extensibility.

In addition, WSDL defines a common binding mechanism. This is used to attach a specific protocol or data format or structure to an abstract message, operation, or endpoint. It allows the reuse of abstract definitions.

[WSDL 1.1, Introduction]

Using DAML-S with WSDL involves DAML-S extensions to the following WSDL elements: types, message, operation and binding. In brief, in types we allow (but do not require) the inclusion of arbitrary DAML declarations In message, we allow the specification of message parts having DAML classes as their abstract types. (Actually, we indicate the correspondence of a message part with a DAML-S input or output property, and from that, the appropriate DAML range class can easily be obtained.) In operation, we propose a new attribute for the purpose of indicating a correspondence between the given operation and a DAML-S atomic process. In binding, we don't actually extended WSDL, but rather, merely provide a new encoding style for use with WSDL's SOAP binding.

These extensions are described in greater detail in the following sections.

1.1 DAML-S/WSDL Document Example

The following example shows, in two parts, the DAML-S/WSDL definition of a simple online book-buying (or sellling, depending on your point of view) service. The service supports a single operation called CongoBuy, which is deployed using the SOAP 1.1 protocol over HTTP. The request takes inputs ....of type ..., and returns .... A detailed description of the elements used in this definition can be found in Section 2 (core language) and Section 3 (SOAP binding).

Part 1-A gives the DAML-S code for a simple atomic process, and the accompanying Grounding instance that relates this code to a WSDL specification by which the service can be contacted. Part 1-B gives this WSDL specification, including constructs that relate it back to the DAML-S code. The points of reference between the two documents are shown in bold.

Example 1-A: CongoBuy, a DAML-S Atomic Process

[TBD: name space declarations and some auxiliary classes are missing.]

http://example.com/congo/CongoBuy.daml

!DOCTYPE uridef[
  <!ENTITY process "http://www.daml.org/services/daml-s/0.7/Process.daml">
]>

<daml:Class rdf:ID="SignInData">
  <!-- details omitted -->
</daml:Class>

<daml:Class rdf:ID="CongoBuy">
  <rdfs:subClassOf rdf:resource="&process;#AtomicProcess"/>
</daml:Class>

<!-- Inputs -->

<rdf:Property rdf:ID="congoBuyBookName">
  <rdfs:subPropertyOf rdf:resource="&process;#input"/>
  <rdfs:domain rdf:resource="#CongoBuy"/>
  <rdfs:range rdf:resource="&xsd;#string"/>
</rdf:Property>

<rdf:Property rdf:ID="congoBuySignInInfo">
  <rdfs:subPropertyOf rdf:resource="&process;#input"/>
  <rdfs:domain rdf:resource="#CongoBuy"/>
  <rdfs:range rdf:resource="#SignInData"/>
</rdf:Property>

<!-- Output: Confirmation No. -->

<rdf:Property rdf:ID="congoBuyConfirmation">
  <rdfs:subPropertyOf rdf:resource="&process;#output"/>
  <rdfs:domain rdf:resource="#CongoBuy"/>
  <rdfs:range rdf:resource="http://www.daml.org/2001/03/daml+oil.daml#Literal"/>
</rdf:Property>

<!-- Here, we relate CongoBuy to its grounding, CongoBuyGrounding.  Since CongoBuy
     is a class, we need to say: "Every instance (i.e., invocation, or use) of this
     class has an instance of the hasGrounding property, with value CongoBuyGrounding".
     The hasGrounding property is defined in Process.daml. -->

<daml:Class rdf:about="CongoBuy">
  <daml:sameClassAs>
    <daml:Restriction daml:cardinality="1">
      <daml:onProperty rdf:resource="#hasGrounding"/>
      <daml:hasValue rdf:resource="#congoBuyGrounding"/>
    </daml:Restriction>
  </daml:sameClassAs>
</daml:Class>

<!-- DAML-S Grounding Instance -->

<grounding:WsdlGrounding rdf:ID="CongoBuyGrounding">
  <grounding:damlsProcess rdf:resource="#congoBuy">
  <grounding:wsdlOperation rdf:resource="http://example.com/congo/congobuy.wsdl#BuyBook"/>

  <grounding:wsdlInputMessage rdf:resource="http://example.com/congo/congobuy.wsdl#CongoBuyInput"/>
  <grounding:wsdlInputMessageParts rdf:parseType="daml:collection">
    <grounding:wsdlMessageMap>
      <grounding:damlsParameter rdf:resource=#congoBuyBookName>
      <grounding:wsdlMessagePart
        rdf:resource="http://example.com/congo/congobuy.wsdl#BookName">
    </grounding:wsdlMessageMap>
    <grounding:wsdlMessageMap>
      <grounding:damlsParameter rdf:resource=#congoBuySignInInfo>
      <grounding:wsdlMessagePart
        rdf:resource="http://example.com/congo/congobuy.wsdl#SignInInfo">
    </grounding:wsdlMessageMap>
  </grounding:wsdlInputMessageParts>

  <grounding:wsdlOutputMessage rdf:resource="http://example.com/congo/congobuy.wsdl#CongoBuyOutput"/>
  <grounding:wsdlOutputMessageParts rdf:parseType="daml:collection">
    <grounding:wsdlMessageMap>
      <grounding:damlsParameter rdf:resource=#congoBuyConfirmation>
      <grounding:wsdlMessagePart
        rdf:resource="http://example.com/congo/congobuy.wsdl#Confirmation">
    </grounding:wsdlMessageMap>
  </grounding:wsdlOutputMessageParts>

  <grounding:wsdlReference rdf:resource="http://www.w3.org/TR/2001/NOTE-wsdl-20010315">
  <grounding:otherReference>
    "http://www.w3.org/TR/2001/NOTE-wsdl-20010315"
    "http://schemas.xmlsoap.org/wsdl/soap/"
    "http://schemas.xmlsoap.org/soap/http/"
  </grounding:otherReference>
  <grounding:wsdlDocument>
    "http://example.com/congo/congobuy.wsdl"
  </grounding:wsdlDocument>
</grounding:WsdlGrounding>

Example 1-B: WSDL Specification providing a SOAP binding for CongoBuy

http://example.com/congo/congobuy.wsdl

<?xml version="1.0"?>
<definitions name="CongoBuy">

targetNamespace="http://example.com/congo/congobuy.wsdl"
          xmlns:tns="http://example.com/congo/congobuy.wsdl"
          xmlns:congoDaml="http://example.com/congo/CongoBuy.daml#"
          xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
          xmlns="http://schemas.xmlsoap.org/wsdl/">

    <message name="CongoBuyInput">
        <part name="BookName" daml-s-parameter="congoDaml:congoBuyBookName"/>
        <part name="SignInInfo" daml-s-parameter="congoDaml:congoBuySignInInfo"/>
    </message>

    <message name="CongoBuyOutput">
        <part name="Confirmation" daml-s-parameter="congoDaml:congoBuyConfirmation"/>
    </message>

    <portType name="CongoBuyPortType">
        <operation name="BuyBook" daml-s-process="congoDaml:CongoBuy">
           <input message="tns:CongoBuyInput"/>
           <output message="tns:CongoBuyOutput"/>
        </operation>
    </portType>

    <binding name="CongoBuySoapBinding" type="tns:CongoBuyPortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="BuyBook">
           <soap:operation soapAction="http://example.com/congo/CongoBuy.daml#BuyBook"/>
           <input>
               <soap:body parts="BookName SignInInfo" use="encoded"
                          namespace="http://example.com/congo/"
                          encodingStyle="http://www.daml.org/2001/03/"/>
           </input>
           <output>
               <soap:body parts="Confirmation" use="encoded"
                          namespace="http://example.com/congo/"
                          encodingStyle="http://www.daml.org/2001/03/"/>
           </output>
        </operation>
    </binding>

    <service name="CongoBuyService">
        <documentation>My first DAML-S/WSDL service</documentation>
        <port name="CongoBuyPort" binding="tns:CongoBuySoapBinding">
           <soap:address location="http://example.com/congo/"/>
        </port>
    </service>


</definitions>

In the remainder of this document, we explain the WSDL extensions proposed for use in DAML-S/WSDL service declarations; that is, the means by which WSDL specs, such as that illustrated in example 1-B, can be declared to correspond with DAML-S specs, such as that illustrated in example 1-A. Thus, this document is primarily concerned with explaining example 1-B. For additional background regarding example 1-A, please see the DAML-S references mentioned in the Abstract.

2. Service Grounding With WSDL

2.1 WSDL Document Structure and Extensions for DAML-S

We reproduce here the WSDL grammar given in section 2.1 of WSDL 1.1, but with the addition of one new element and two attributes for use with DAML-S. These additions are shown in bold.

<wsdl:definitions name="nmtoken"? targetNamespace="uri"?>

    <import namespace="uri" location="uri"/>*

    <wsdl:documentation .... /> ?

    <wsdl:types> ?
        <wsdl:documentation .... />?
        <xsd:schema .... />*
        <-- extensibility element --> *
        <rdf:RDF namespace-declarations ...> .... </rdf:RDF/>*
    </wsdl:types>

    <wsdl:message name="nmtoken"> *
        <wsdl:documentation .... />?
        <!-- This spec adds attribute daml-s-parameter -->
        <part name="nmtoken" element="qname"? type="qname"? daml-s-parameter="qname"?/> *
    </wsdl:message>

    <wsdl:portType name="nmtoken">*
        <wsdl:documentation .... />?
        <!-- This spec proposes attribute daml-process -->
        <wsdl:operation name="nmtoken" daml-process="qname"?>*
           <wsdl:documentation .... /> ?
           <wsdl:input name="nmtoken"? message="qname">?
               <wsdl:documentation .... /> ?
           </wsdl:input>
           <wsdl:output name="nmtoken"? message="qname">?
               <wsdl:documentation .... /> ?
           </wsdl:output>
           <wsdl:fault name="nmtoken" message="qname"> *
               <wsdl:documentation .... /> ?
           </wsdl:fault>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="nmtoken" type="qname">*
        <wsdl:documentation .... />?
        <-- extensibility element --> *
        <wsdl:operation name="nmtoken">*
           <wsdl:documentation .... /> ?
           <-- extensibility element --> *
           <wsdl:input> ?
               <wsdl:documentation .... /> ?
               <-- extensibility element -->
           </wsdl:input>
           <wsdl:output> ?
               <wsdl:documentation .... /> ?
               <-- extensibility element --> *
           </wsdl:output>
           <wsdl:fault name="nmtoken"> *
               <wsdl:documentation .... /> ?
               <-- extensibility element --> *
           </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="nmtoken"> *
        <wsdl:documentation .... />?
        <wsdl:port name="nmtoken" binding="qname"> *
           <wsdl:documentation .... /> ?
           <-- extensibility element -->
        </wsdl:port>
        <-- extensibility element -->
    </wsdl:service>

    <-- extensibility element --> *

</wsdl:definitions>

Services are defined using six major elements:

types, which provides data type definitions used to describe the messages exchanged.
message, which represents an abstract definition of the data being transmitted. A message consists of logical parts, each of which is associated with a definition within some type system.
portType, which is a set of abstract operations. Each operation refers to an input message and output messages.
binding, which specifies concrete protocol and data format specifications for the operations and messages defined by a particular portType.
port, which specifies an address for a binding, thus defining a single communication endpoint.
service, which is used to aggregate a set of related ports.

In WSDL the term binding refers to the process associating protocol or data format information with an abstract entity like a message, operation, or portType. WSDL allows elements representing a specific technology (referred to here as extensibility elements) under various elements defined by WSDL. These points of extensibility are typically used to specify binding information for a particular protocol or message format, but are not limited to such use. Extensibility elements MUST use an XML namespace different from that of WSDL. ...

Extensibility elements are commonly used to specify some technology specific binding. To distinguish whether the semantic of the technology specific binding is required for communication or optional, extensibility elements MAY place a wsdl:required attribute of type boolean on the element. The default value for required is false. The required attribute is defined in the namespace "http://schemas.xmlsoap.org/wsdl/".

Extensibility elements allow innovation in the area of network and message protocols without having to revise the base WSDL specification. WSDL recommends that specifications defining such protocols also define any necessary WSDL extensions used to describe those protocols or formats.

[WSDL 1.1, Section 2.1]

2.2 Types

The types element encloses data type definitions that are relevant for the exchanged messages. For maximum interoperability and platform neutrality, WSDL prefers the use of XSD as the canonical type system, and treats it as the intrinsic type system.
<definitions .... >
    <types>
        <xsd:schema .... />*
    </types>
</definitions>
However, since it is unreasonable to expect a single type system grammar can be used to describe all abstract types present and future, WSDL allows type systems to be added via extensibility elements. An extensibility element may appear under the types element to identify the type definition system being used and to provide an XML container element for the type definitions. The role of this element can be compared to that of the schema element of the XML Schema language.
<definitions .... >
    <types>
        <-- type-system extensibility element --> *
    </types>
</definitions>

[WSDL 1.1, Section 2.2]

When using DAML-S with WSDL, it is possible to declare DAML classes and properties within the types section. When a types section is used in this way, the extensibility element looks like this:

where the "..." within the extensibility element may be replaced by any number of DAML+OIL declarations.

Probably the more usual case will be to declare all relevant DAML classes in a separate ".daml" file, as shown in Example 1. If that is done, the WSDL types section may be completely omitted.

2.3 Messages

Messages consist of one or more logical parts. Each part is associated with a type from some type system using a message-typing attribute. The set of message-typing attributes is extensible. WSDL defines several such message-typing attributes for use with XSD:

element. Refers to an XSD element using a QName.
type. Refers to an XSD simpleType or complexType using a QName.

Other message-typing attributes may be defined as long as they use a namespace different from that of WSDL. Binding extensibility elements may also use message-typing attributes.

[WSDL 1.1, Section 2.3]

We create the message-typing attribute daml-s-parameter for use with DAML-S. This will normally be used to indicate a sub property of daml-s:input, or of daml-s:output.

The syntax for defining a message is as follows. The message-typing attributes (which may vary depending on the type system used) are shown in bold.
<definitions .... >
    <message name="nmtoken"> *
        <part name="nmtoken" element="qname"? type="qname"?/> *
    </message>
</definitions>
The message name attribute provides a unique name among all messages defined within the enclosing WSDL document.
The part name attribute provides a unique name among all the parts of the enclosing message.

[WSDL 1.1, Section 2.3]

For example, to specify the input message to CongoBuy, we write this (from Example 1):

<definitions .... >
     <message name="CongoBuyInput">
        <part name="BookName" daml-s-parameter="congoDaml:congoBuyBookName"/>
        <part name="SignInInfo" daml-s-parameter="congoDaml:congoBuySignInInfo"/>
    </message>
</definitions>

2.4 Port Types

A port type is a named set of abstract operations and the abstract messages involved.
<wsdl:definitions .... >
    <wsdl:portType name="nmtoken">
        <wsdl:operation name="nmtoken" .... /> *
    </wsdl:portType>
</wsdl:definitions>
The port type name attribute provides a unique name among all port types defined within in the enclosing WSDL document.
An operation is named via the name attribute.
WSDL has four transmission primitives that an endpoint can support:

One-way. The endpoint receives a message.

Request-response. The endpoint receives a message, and sends a correlated message.

Solicit-response. The endpoint sends a message, and receives a correlated message.

Notification. The endpoint sends a message.

WSDL refers to these primitives as operations. ....

[WSDL 1.1, Section 2.4]

2.4.1 One-way Operation

An atomic process with inputs, but no outputs, corresponds to a WSDL one-way operation.

2.4.2 Request-response Operation

An DAML-S atomic process with both inputs and outputs corresponds to a WSDL request-response operation.

2.4.3 Solicit-response Operation

A composite process with both outputs and inputs, and with the sending of outputs specified as coming before the reception of inputs, corresponds to WSDL's solicit-response operation.

2.4.4 Notification Operation

An atomic process with outputs, but no inputs, corresponds to a WSDL notification operation.

2.4.5 Mapping DAML-S Processes to WSDL Operations

A way is needed to indicate the correspondence between a particular WSDL operation, and a DAML-S AtomicProcess. WSDL offers no extensibility elements for operations. While there are ways within WSDL bindings to indicate this correspondence (using, for example, the soapAction attribute), it will also be useful to indicate this correspondence in conjunction with the operation definition; that is, in a place that is not specific to any binding. For this purpose, we propose that WSDL sanction an optional daml-s-process attribute for the WSDL operation element, as illustrated in Example 1:

2.5 Bindings

As with any use of WSDL, a variety of options are possible for the binding of a DAML-S/WSDL-specified service. For present purposes, we utilize SOAP bindings, just as they are used in existing WSDL examples, except that we use "http://www.daml.org/2001/03/" to indicate the encoding style of each of the message parts. That is, we use "http://www.daml.org/2001/03/" to indicate that the set of valid body part strings is simply the set of valid DAML+OIL constructs, which is certainly true because every DAML-S construct is, by definition, a DAML+OIL construct.