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 OWL-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 OWL-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 a version of 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 OWL-S, but rather assumes a basic familiarity with selected OWL-S constructs (particularly the atomic process), which may be acquired from the Technical Overview and related documents in the current release of OWL-S, available at http://www.daml.org/services/owl-s/1.1/. Note that the Technical Overview contains a Grounding section that gives the conceptual background for this approach.
OWL-S version 1.1 builds on WSDL
1.1. We anticipate that the next version of OWL-S will build on
WSDL 1.2
(depending
on its level of finalization when the time comes).
OWL-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 OWL-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 OWL-S have chosen to define conventions for using WSDL to ground OWL-S services. These conventions are based upon the observation that OWL-S' concept of grounding is generally consistent with WSDL's concept of binding. As a result, it is a relatively straightforward task to ground an OWL-S atomic process. In this document, we show how this may be done, relying on the WSDL 1.1 specification.
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:
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.
The essence of an OWL-S/WSDL grounding is captured by creating an instance of the OWL-S Grounding class, which includes all required information regarding the relationships between the relevant OWL-S constructs and the relevant WSDL constructs. (Although a Grounding instance is illustrated below, its details are not covered here. Please refer to the OWL-S Technical Overview for these details.) Because the Grounding instance has all required information, it is logically not necessary to modify the WSDL document(s) used with the grounding. However, it may nevertheless be useful to give some indications, in WSDL documents, of how the WSDL constructs are used to ground OWL-S.
Using OWL-S with WSDL involves OWL-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 OWL declarations In message, we allow (but do not require) the specification of message parts having OWL classes as their abstract types. (Actually, we indicate the correspondence of a message part with an OWL-S input or output property, and from that, the appropriate OWL 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 an OWL-S atomic process. In binding, we don't actually extend WSDL, but rather, merely provide a new encoding style for use with WSDL's SOAP binding.
With only one exception (the proposed new attribute for the WSDL operation declaration), everything here is done using WSDL extensibility elements. These extensions are described in greater detail in the following sections.
Part 1-A gives the OWL-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. Note that this Grounding is a simple illustration. In particular, it does not illustrate the use of OWL-S property xsltTransformation, which may be used to express more complex mappings between WSDL message parts and atomic process inputs/outputs.
Part 1-B gives the WSDL specification,
including
constructs that relate it back to the OWL-S code. The points of
reference between the two documents are shown in bold.
http://example.com/congo/CongoBuy.owl
<!DOCTYPE uridef[
<!ENTITY rdf "http://www.w3.org/1999/02/22-rdf-syntax-ns">
<!ENTITY rdfs "http://www.w3.org/2000/01/rdf-schema">
<!ENTITY owl "http://www.w3.org/2002/07/owl">
<!ENTITY xsd "http://www.w3.org/2001/XMLSchema">
<!ENTITY grounding "http://www.daml.org/services/owl-s/1.1/Grounding.owl">
<!ENTITY process "http://www.daml.org/services/owl-s/1.1/Process.owl">
<!ENTITY DEFAULT "http://example.com/congo/CongoBuy.owl">
]>
<rdf:RDF
xmlns:rdf= "&rdf;#"
xmlns:rdfs= "&rdfs;#"
xmlns:owl = "&owl;#"
xmlns:xsd= "&xsd;#"
xmlns:process= "&process;#"
xmlns:grounding= "&process;#"
xmlns= "&DEFAULT;#">
<owl:Class rdf:ID="SignInData">
<!-- details omitted -->
</owl:Class>
<!-- The CongoBuy atomic process -->
<process:AtomicProcess rdf:ID="CongoBuy">
<process:hasInput>
<process:Input ref:ID="In-BookName">
<process:parameterType rdf:about="&xsd;#string">
</process:Input>
</process:hasInput>
<process:hasInput>
<process:Input ref:ID="In-SignInData">
<process:parameterType rdf:resource="#SignInData">
</process:Input>
</process:hasInput>
<process:hasOutput>
<process:Output ref:ID="Out-Confirmation">
<process:parameterType rdf:resource="&xsd;#string">
</process:Output>
</process:hasOutput>
</process:AtomicProcess>
<!-- OWL-S Grounding Instance -->
<grounding:WsdlGrounding rdf:ID="FullCongoBuyGrounding">
<grounding:hasAtomicProcessGrounding rdf:resource="#CongoBuyGrounding"/>
</grounding:WsdlGrounding>
<grounding:WsdlAtomicProcessGrounding rdf:ID="CongoBuyGrounding">
<grounding:owlsProcess rdf:resource="#congoBuy">
<grounding:wsdlOperation>
<grounding:WsdlOperationRef>
<grounding:portType>
<xsd:uriReference rdf:value="http://example.com/congo/congobuy.wsdl#CongoBuyPortType"/>
</grounding:portType>
<grounding:operation>
<xsd:uriReference rdf:value="http://example.com/congo/congobuy.wsdl#BuyBook"/>
</grounding:operation>
</grounding:WsdlOperationRef>
</grounding:wsdlOperation>
<grounding:wsdlInputMessage rdf:resource="http://example.com/congo/congobuy.wsdl#CongoBuyInput"/>
<grounding:wsdlInput>
<grounding:wsdlInputMessageMap>
<grounding:owlsParameter rdf:resource="#In-BookName">
<grounding:wsdlMessagePart>
<xsd:uriReference rdf:value="http://example.com/congo/congobuy.wsdl#BookName">
</grounding:wsdlMessagePart>
</grounding:wsdlInputMessageMap>
</grounding:wsdlInput>
<grounding:wsdlInput>
<grounding:wsdlInputMessageMap>
<grounding:owlsParameter rdf:resource="#In-SignInInfo">
<grounding:wsdlMessagePart>
<xsd:uriReference rdf:value="http://example.com/congo/congobuy.wsdl#SignInInfo">
</grounding:wsdlMessagePart>
</grounding:wsdlInputMessageMap>
</grounding:wsdlInput>
<grounding:wsdlOutputMessage rdf:resource="http://example.com/congo/congobuy.wsdl#CongoBuyOutput"/>
<grounding:wsdlOutput>
<grounding:wsdlOutputMessageMap>
<grounding:owlsParameter rdf:resource="#Out-Confirmation">
<grounding:wsdlMessagePart>
<xsd:uriReference rdf:value="http://example.com/congo/congobuy.wsdl#Confirmation">
</grounding:wsdlMessagePart>
</grounding:wsdlOutputMessageMap>
</grounding:wsdlOutput>
<grounding:wsdlVersion rdf:resource="http://www.w3.org/TR/2001/NOTE-wsdl-20010315">
<grounding:wsdlDocument>
"http://example.com/congo/congobuy.wsdl"
</grounding:wsdlDocument>
</grounding:WsdlGrounding>
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:congoOwl="http://example.com/congo/CongoBuy.owl#"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:owl-s-wsdl="http://www.daml.org/services/owl-s/wsdl/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="CongoBuyInput">
<part name="BookName" owl-s-wsdl:owl-s-parameter="congoOwl:In-BookName"/>
<part name="SignInInfo" owl-s-wsdl:owl-s-parameter="congoOwl:In-SignInInfo"/>
</message>
<message name="CongoBuyOutput">
<part name="Confirmation" owl-s-wsdl:owl-s-parameter="congoOwl:Out-Confirmation"/>
</message>
<portType name="CongoBuyPortType">
<operation name="BuyBook" owl-s-wsdl:owl-s-process="congoOwl: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.owl#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 OWL-S/WSDL service</documentation>
<port name="CongoBuyPort" binding="tns:CongoBuySoapBinding">
<soap:address location="http://example.com/congo/"/>
</port>
</service>
</definitions>
<wsdl:definitions name="nmtoken"? targetNamespace="uri"?
xmlns:owl-s-wsdl="http://www.daml.org/services/owl-s/wsdl/">
<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 owl-s-parameter -->
<part name="nmtoken" element="qname"? type="qname"? owl-s-wsdl:owl-s-parameter="qname"?/> *
</wsdl:message>
<wsdl:portType name="nmtoken">*
<wsdl:documentation .... />?
<!-- This spec proposes attribute owl-s-process -->
<wsdl:operation name="nmtoken" owl-s-wsdl:owl-s-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:
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.
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.[WSDL 1.1, Section 2.2]<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.
<types>
<xsd:schema .... />*
</types>
</definitions><definitions .... >
<types>
<-- type-system extensibility element --> *
</types>
</definitions>
where the "..." within the extensibility element may be replaced by any number of OWL declarations.
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:
We create the message-typing attribute owl-s-parameter for use with OWL-S. This will normally be used to indicate a sub property of owl-s:input, or of owl-s:output. Given the input or output property, its type can easily be obtained from the OWL-S code.
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.[WSDL 1.1, Section 2.3]<definitions .... >The message name attribute provides a unique name among all messages defined within the enclosing WSDL document.
<message name="nmtoken"> *
<part name="nmtoken" element="qname"? type="qname"?/> *
</message>
</definitions>The part name attribute provides a unique name among all the parts of the enclosing message.
For example, to specify the input message to CongoBuy, we write this (from Example 1):
<definitions .... >
<message name="CongoBuyInput">
<part name="BookName" owl-s-parameter="congoOwl:In-BookName"/>
<part name="SignInInfo" owl-s-parameter="congoDaml:In-SignInInfo"/>
</message>
</definitions>
Note: http://www.daml.org/services/owl-s/wsdl/ may be used as the namespace for owl-s-parameter.
A port type is a named set of abstract operations and the abstract messages involved.[WSDL 1.1, Section 2.4]<wsdl:definitions .... >The port type name attribute provides a unique name among all port types defined within in the enclosing WSDL document.
<wsdl:portType name="nmtoken">
<wsdl:operation name="nmtoken" .... /> *
</wsdl:portType>
</wsdl:definitions>An operation is named via the name attribute.
WSDL has four transmission primitives that an endpoint can support:
WSDL refers to these primitives as operations. ....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.
<operation name="BuyBook" owl-s-process="congoOwl:CongoBuy">
Note: http://www.daml.org/services/owl-s/wsdl/ may be used as the namespace for owl-s-process.