Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document defines a set of extension attributes for the Web Services Description Language [WSDL 2.0] that allow to describe additional semantics of WSDL components. The specification defines how such semantic annotation is accomplished using references to semantic models, e.g. ontologies. SAWSDL does not specify a language for representing the semantic models. Instead it provides mechanisms by which concepts from the semantic models, typically defined outside the WSDL document, can be referenced from within WSDL components using annotations.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This September 2006 release of the Semantic Annotations for WSDL specification is a Last Call Working Draft by the SAWSDL Working Group (part of the W3C Web Services Activity) for review by W3C Members and other interested parties. The Working Group seeks confirmation that comments and issues have been addressed to the satisfaction of reviewers. Comments are due by 01 November 2006 to public-ws-semann-comments@w3.org, a mailing list with a public archive. Discussions on this specification should take place on the public-ws-semann@w3.org mailing list (public archive.)
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Semantic Annotations for WSDL (SAWSDL) defines how to add semantic annotations to various parts of a WSDL document such as input and output message structures, interfaces and operations. The extension attributes defined in this specification fit within the WSDL 2.0 extensibility framework. For example, it defines a way to annotate WSDL interfaces and operations with categorization information that can be used to publish a Web service in a registry. The annotations on schema types can be used during Web service discovery and composition. In addition, SAWSDL defines an annotation mechanism for specifying the structural mapping of XML Schema types to and from an ontology such mappings could be used during invocation, particularly when mediation is required. To accomplish semantic annotation, SAWSDL defines extension attributes that can be applied both to WSDL elements and to XML Schema elements.
Semantic annotations are references from an element within a WSDL or XML Schema document to a concept in an ontology or to a mapping. This specification defines annotation mechanisms for relating the constituent structures of WSDL input and output messages to concepts defined in an outside ontology. Similarly, it defines how to annotate WSDL operations and interfaces. Further, it defines an annotation mechanism for specifying the structural mapping of XML Schema types to and from an ontology by means of a reference to a mapping definition. The annotation mechanism is independent of the ontology expression language and this specification requires no particular ontology language. It is also independent of mapping languages and does not restrict the possible choices of such languages.
The rest of the document describes the SAWSDL extension attributes and provide examples as appropriate to illustrate their usage. For background and further examples, read the Semantic Annotations for WSDL - Usage Guide [SAWSDL Usage Guide].
The following are the basic definitions for the terminology used in this document.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].
The XML namespace URIs [XML Namespaces] together with the prefixes as used by this specification are as follows:
Prefix | Namespace name |
---|---|
sawsdl | http://www.w3.org/2002/ws/sawsdl/spec/sawsdl# |
wsdl | http://www.w3.org/2006/01/wsdl |
wsdl11 | http://schemas.xmlsoap.org/wsdl/ |
xs | http://www.w3.org/2001/XMLSchema |
In order to illustrate the concepts of SAWSDL, later sections will use a purchase order Web service interface. This imaginary Web service expects as input a customer account number and a list of items to be ordered, each containing quantity information and a product identifier in form of a Universal Product Code (UPC). The service will return the status of the order, which can be either reject, accept or pending. The WSDL including semantic annotations for this service is given below.
<wsdl:description targetNamespace="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:wsdl="http://www.w3.org/2006/01/wsdl" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sawsdl="http://www.w3.org/2002/ws/sawsdl/spec/sawsdl#"> <wsdl:types> <xs:schema targetNamespace="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" elementFormDefault="qualified"> <xs:element name="OrderRequest" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderRequest" sawsdl:loweringSchemaMapping="http://www.w3.org/2002/ws/sawsdl/spec/mapping/RDFOnt2Request.xml"> <xs:complexType> <xs:sequence> <xs:element name="customerNo" type="xs:integer" /> <xs:element name="orderItem" type="item" minOccurs="1" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="item"> <xs:all> <xs:element name="UPC" type="xs:string" /> </xs:all> <xs:attribute name="quantity" type="xs:integer" /> </xs:complexType> <xs:element name="OrderResponse" type="confirmation" /> <xs:simpleType name="confirmation" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderConfirmation"> <xs:restriction base="xs:string"> <xs:enumeration value="Confirmed" /> <xs:enumeration value="Pending" /> <xs:enumeration value="Rejected" /> </xs:restriction> </xs:simpleType> </xs:schema> </wsdl:types> <wsdl:interface name="Order" sawsdl:modelReference="http://example.org/categorization/products/electronics"> <wsdl:operation name="order" pattern="http://www.w3.org/2006/01/wsdl/in-out" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#RequestPurchaseOrder"> <wsdl:input element="OrderRequest" /> <wsdl:output element="OrderResponse" /> </wsdl:operation> </wsdl:interface> </wsdl:description>
The annotations in this example appear as modelReference and loweringSchemaMapping attributes on schema and WSDL elements. Each modelReference shown above identifies the concept in a semantic model that describes the element to which it is attached. For instance, the OrderRequest element is described by the "OrderRequest" concept in the ontology whose URI is "http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder." A loweringSchemaMapping is also attached to the OrderRequest element to point to a mapping, in this case an XML document, that shows how the elements within the OrderRequest can be mapped to semantic data in the model.
Sections of this example annotated WSDL document will be used in subsequent parts of the specification where these SAWSDL attributes are fully defined.
This section describes the semantic annotations that SAWSDL adds to WSDL 2.0 components.
Conceptually, WSDL 2.0 has the following components to represent service descriptions: types, interface, operation, fault, binding, service and endpoint. Of these, the first four, namely types, interface and operation deal with the abstract definition of a service while the latter three deal with service implementation. This specification focuses on semantically annotating the abstract definition of a service to enable dynamic discovery, composition and invocation of services. This specification does not address the annotation of service implementations. It provides a reference mechanisms that can be applied to WSDL type, interface and operation components to point to concepts defined in semantic models.
A summary of the extension attributes defined by SAWSDL is given below:
The semantic annotation mechanism defined by this specification does not rely on any particular semantic modeling language. It only requires that the semantic concepts defined in it be identifiable via URI references. The URIs typically refer to concepts in a semantic model that is external to the WSDL document. However, the URIs can also refer to elements within the WSDL document if semantic information is included in the document via WSDL extension elements as shown below on lines 3 to 14.
01 <wsdl:description … > 02 03 <rdf:RDF 04 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 05 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" 06 xmlns:owl="http://www.w3.org/2002/07/owl#" 07 xml:base="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#"> 08 <owl:Class rdf:ID="OrderRequest"/> 09 <owl:ObjectProperty rdf:ID="has_items"> 10 <rdfs:domain rdf:resource="OrderRequest"/> 11 <rdfs:range rdf:resource="Item"/> 12 </owl:ObjectProperty> 13 <owl:Class rdf:ID="Item"/> 14 </rdf:RDF> 15 16 <wsdl:types> 17 <xs:element name="OrderRequest" 18 sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderRequest"> 19 … 20 </xs:element> 21 … 22 </wsdl:types> 23 24 <wsdl:interface name="Order"> 25 … 26 </wsdl:interface> 27 </wsdl:description>
SAWSDL allows multiple semantic annotations to be associated with WSDL elements. Both schema mappings and a model references can contain sets of pointers. Multiple schema mappings are interpreted as alternatives whereas multiple model references all apply. SAWSDL does not specify any other relationship between them. More details about this are presented in the sections that follow.
This section defines the extension attribute modelReference. A model reference may be used with every element within WSDL. However, SAWSDL defines its meaning only for wsdl:interface, wsdl:operation, wsdl:fault, xs:element, xs:complexType, xs:simpleType and xs:attribute.
The following XML schema excerpt defines the modelReference attribute.
… <xs:simpleType name="listOfAnyURI"> <xs:list itemType="xs:anyURI"/> </xs:simpleType> <xs:attribute name="modelReference" type="listOfAnyURI" /> …
The value of the a modelReference attribute is a set of zero or more URIs, separated by whitespaces, that identify concepts in a semantic model. Each URI is a pointer to a concept in a semantic model and is intended to provide semantic information about the WSDL component being annotated. Model references define additional semantics for the components of the WSDL instance document. Sections 2.1.1 through 2.1.7 describe the use of modelReference on interfaces, operations, faults, simple types, complex types, elements and attributes.
The modelReference attribute allows multiple annotations to be associated with a given WSDL component via a set of URIs. These URIs may identify concepts expressed in different semantic representation languages. When a WSDL component is annotated with a modelReference that includes multiple URIs, each of them applies to the component, but no logical relationship between them is defined by this specification.
In terms of the WSDL 2.0 component model, a model reference is a new property. In particular, when used on an element that represents a WSDL 2.0 Component (e.g. wsdl:interface, wsdl:operation, top-level xsd:element, etc.), the modelReference extension attribute introduces an OPTIONAL property {model reference} whose value is a set of URIs taken from the value of the attribute. The absence of the {model reference} property is equal to its presence with an empty value.
SAWSDL does not define any particular way to dereference model references, i.e., it does not prescribe how a client processor can obtain the document in which the semantic model is defined. It is recommended that the URI used for pointing to a semantic concept resolves to a document containing its definition. If the semantic model is expressed using XML it could be placed directly within the WSDL document.
The modelReference annotations on xs:element, xs:complexType, xs:simpleType and xs:attribute define the semantics of the input or output data of WSDL operations. A modelReference on a WSDL operation or fault gives semantic information about that operation, while a modelReference on a WSDL interface provides a classification or other semantic descriptions of the interface.
This section defines how a modelReference can be used to annotate interfaces, including how to categorize them according to some model, specify behavioral aspects or other semantic definitions. A modelReference on a WSDL interface component provides a reference to a concept or concepts in a semantic model that describe the interface. The example below illustrates a categorization annotation on an interface.
… <wsdl:interface name="Order" sawsdl:modelReference="http://example.org/categorization/products/electronics"> … </wsdl:interface> …
The modelReference in this example points to a category some concept "electronics" in some semantic model. For taxonomies that are not expressed as part of a semantic model, the modelReference can point to a simple semantic model that contains the taxonomy reference information. This specification does not define such a categorization semantic model, but includes a non-normative example in Appendix C. SAWSDL does not constrain the form of the semantic model for categorization or that of any other semantic model specified in a modelReference on an interface.
When an interface extends one or more interfaces, the model references of the extended interfaces all apply to the new interface as well. In this way, an interface can be categorized via the modelReferences of the interfaces it extends. Categorizations applied to other WSDL components, such as operations, are separate. SAWSDL defines no relationship between categorizations applied to other WSDL components.
Appendix C further describes the use of categorization annotations including examples that show how to use the taxonomies supported by Universal Description, Discovery and Integration (UDDI) to categorize an interface.
The example below shows the annotated WSDL with a modelReference attribute to annotate the operation element. The annotation of the operation element carries a reference to a concept in a semantic model that provides a high level description of the operation, specifies its behavioral aspects or includes other semantic definitions. In the purchase order example, the order operation can be annotated using a class that represents a purchase order request operation. The annotation of the operation using the modelReference attribute is shown below.
… <wsdl:operation name="order" pattern="http://www.w3.org/2006/01/wsdl/in-out" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#RequestPurchaseOrder"> <wsdl:input element="OrderRequest"/> <wsdl:output element="OrderResponse"/> </wsdl:operation> …
Although inputs and outputs provide one way of capturing the semantics of an operation, a simple semantic annotation indicating the intended behavior of a given operation as a verb concept may be useful at certain times. During service discovery, this verb provides a coarse indication of whether this service is a match for a given request. This can act as way to reduce the number of services whose input and output must be checked.
Operations can also be annotated with category references. These are separate from any categorizations applied to other WSDL components (e.g. the interface holding the operation) and SAWSDL defines no relationships between categorizations applied to them.
The annotation of the fault element carries a reference to a concept in a semantic model that provides a high level description of the fault, includes other semantic definitions. The example below illustrates how to use the modelReference attribute to annotate the fault element. A fault that could be associated with order operation can be annotated using a class that represents the failure of a purchase order request operation due to the unavailability of the item. The annotation of the annotated using the modelReference attribute is shown below.
… <wsdl:interface name="Order"> <wsdl:fault name="ItemUnavailable" type="xs:string" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#ItemUnavailable"/> … </wsdl:interface>
This example identifies the "ItemUnavailable" concept in the referenced semantic model as a description of the fault "itemUnavailableFault."
Simple types can be annotated by including a modelReference attribute on the xs:simpleType element. An example is shown below for the output of the order operation in the example WSDL document presented in section 1.4.
… <xs:simpleType name="Confirmation" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderConfirmation"> … </xs:simpleType> …
In this example, any element or attribute whose type is Confirmation is described by the OrderConfirmation concept in the referenced semantic model.
Two of the principal techniques for annotating complex types can be summarized as follows:
In bottom level annotation, all the member elements and attributes in a complex type can be annotated. In some cases, the members of a complex type will correspond with the concepts in a semantic model. To accommodate this case, the member elements and attributes can be annotated by adding a modelReference attribute to the relevant schema element or attribute. Bottom level annotation uses the mechanism described under Annotating Elements With Model Reference and Annotating Attributes With Model Reference.
In top level annotation, complex types themselves are annotated with the model reference. If multiple concepts describe the complex type, all of their URIs can be included in the value of the modelReference attribute. This sawsdl:modelReference attribute on a complex type annotates the type as a whole, but does not necessarily make any specific statements about the elements or attributes within the complex type.
A complex type can be annotated at both the top and member level. These annotations are independent of each other.
An element declaration can be annotated by including a modelReference on the xs:element element. An example of annotating the member elements of a complex type with the modelReference attribute is shown below.
… <xs:complexType> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="quantity" type="xs:integer" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#Quantity"/> <xs:element name="UPC" type="xs:string" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#ItemCode"/> </xs:sequence> </xs:complexType> …
In this sequence, each bottom level element has an annotation since the semantic model contains concepts, namely "Quantity" and "ItemCode" that describe each of the components of the complex type.
An attribute can be annotated by including a modelReference on the xs:attribute element. If the quantity element in the example above where defined as an attribute, a modelReference could be applied to it as follows.
… <xs:attribute name="quantity" type="xs:integer" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#Quantity"/> …
This annotation indicates that the attribute "quantity" is described by the concept "Quantity" in the referenced semantic model.
SAWSDL introduces schema mapping annotations to address post-discovery issues in using a Web service. Model references can be used to help determine if a service meets the requirements of a client, but there may still be mismatches in the structure of the inputs and outputs. For example, a client may have a given name and last name among its data, and these values need to be concatenated in the message to the Web service. The schema mapping would take the client's semantic data and turn it into XML, and in the process it would perform the necessary concatenation to produce the full name.
In a more complex scenario, a client may use WSDL with semantic annotations to describe the service it expects. Again, if the XML structures expected by the client and by the service differ, schema mappings can translate the XML structures into the semantic model where any mismatches can be understood and resolved.
Schema mapping relates the instance data defined by an XML schema document with some semantic data defined by a semantic model. Such mappings are useful in general when the structure of the instance data does not correspond trivially to the organization of the semantic data. The mappings are used when mediation code is generated to support invocation of a Web service.
This section defines the extension attributes liftingSchemaMapping and loweringSchemaMapping. They are used to associate a schema type or element with a mapping to an ontology, as just described. Schema mappings may be added to global type definitions (complex or simple) as well as to global element declarations. It is possible to specify either lowering or lifting information as well both together on the same schema element. The following schema excerpt defines the liftingSchemaMapping as well as loweringSchemaMapping attributes.
… <xs:simpleType name="listOfAnyURI"> <xs:list itemType="xs:anyURI"/> </xs:simpleType> <xs:attribute name="liftingSchemaMapping" type="listOfAnyURI" /> <xs:attribute name="loweringSchemaMapping" type="listOfAnyURI" /> …
The value of the liftingSchemaMapping attribute is a set of zero or more URIs that reference mapping definitions. A mapping referenced by this attribute defines how an XML instance document conforming to the element or type defined in a schema is transformed to data that conforms to some semantic model, i.e. the output of the transformation process will be semantic data. The input to the transformation is the XML element on whose declaration the mapping is located; or an element valid according to the type on whose definition the mapping is located. Multiple values are interpreted as alternatives.
The value of the loweringSchemaMapping attribute is a set of zero or more URIs that reference mapping definitions. A mapping referenced by this attribute defines how data in a semantic model is transformed to XML instance data. The input will be some semantic data. The output of the process will be the XML element on whose declaration the mapping is located; or an element valid according to the type on whose definition the mapping is located.
When multiple URIs are specified on liftingSchemaMapping or loweringSchemaMapping, the schema mappings they reference are to be treated as alternatives, i.e. the client processor should choose one of them to apply, and the choice is fully at the client processor's discretion. For example, a mapping can be selected based on what mapping language the processor supports (different alternatives can use different languages), based on the availability of the mapping document, or by other preferences.
This specification provides a mechanism for associating optional schema mapping functions with a global type definition or global element declaration without any restriction on the choice of the schema mapping language. Just as SAWSDL does not prescribe any particular ontology representation language for specifying modelReferences, it does not prescribe any particular schema mapping representation language.
The following excerpt from the purchase order example shows how XSLT can be used as a schema mapping language to specify mapping from XSD elements to concepts in a semantic model. Detailed examples showing schema mapping using XSLT [XSLT] and SPARQL [SPARQL] are shown in Appendix A. Other languages, such as XQuery [XQuery] can also be used.
… <xs:element name="OrderRequest" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderRequest" sawsdl:liftingSchemaMapping="http://www.w3.org/2002/ws/sawsdl/spec/mapping/Response2Ont.xslt"> <xs:complexType> <xs:sequence> <xs:element name="customerNo" type="xs:integer" /> <xs:element name="orderItem" type="item" minOccurs="1" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> …
In order to perform the lifting of the data contained in an XML message, a client processor applies the transformation that can be retrieved from the URI given in the value of sawsdl:liftingSchemaMapping and applies the transformation to those elements where the schema mapping was specified. In the example above http://www.w3.org/2002/ws/sawsdl/spec/mapping/Response2Ont.xslt will be applied to OrderRequest elements. If a mapping is specified on a global type definition the mapping definition must only be applied to the elements that are of that type.
A mapping specified on an element, including an empty value (""), overrides any mappings specified on its type. If no mapping is specified on the element, the mapping on its type applies to the element.
The following example illustrates this rule. The type orderItem is represented as an element and a liftingSchemaMapping is specified on it. The complex type of orderItem is defined later in the schema and the complex type itself has a schema mapping. In such a case, the liftingSchemaMapping specified on the element overwrites the one specified on the complex type. This means that only the schema mapping that is given with the URI http://example.org/mapping/OrderItem2Ont.xslt applies to the element orderItem. The http://example.org/mapping/OrderType2Ont.xslt does not apply. The reason for specifying such an override rule to allow an element to indicate the type mapping does not apply.
… <xs:element name="orderItem" type="itemType" sawsdl:liftingSchemaMapping="http://example.org/mapping/OrderItem2Ont.xslt"/> <xs:complexType name="itemType" sawsdl:liftingSchemaMapping="http://example.org/mapping/OrderType2Ont.xslt"> <xs:sequence> <xs:element ref="partDesc" /> </xs:sequence> <xs:attribute name="ItemID" type="xs:string"/> </xs:complexType> …
When used on an element that represents a WSDL 2.0 Component (top-level xsd:element, xsd:complexType or xsd:simpleType), the loweringSchemaMapping and liftingSchemaMapping extension attributes introduce OPTIONAL properties {lowering schema mapping} and {lifting schema mapping}. The value of either of these properties is a set of URIs taken from the value of the respective attribute. In contrast to the {model reference} property, the absence of the {lifting schema mapping} and {lowering schema mapping} properties is different from its presence with an empty value, as mappings on an element must be able to override the mappings specified on the type of the element.
The mechanism for semantic annotation described in this specification can also be applied to WSDL 1.1 [WSDL 1.1] Web service descriptions. All the XML attributes defined in this specification apply without modification to the WSDL 1.1 descriptions. However, in some cases they are applied to different elements in the WSDL document structure and a new element is introduced to facilitate operation annotations.
WSDL 1.1 does not allow extension attributes on the operation element, so this specification introduces a new extension element, attrExtensions, to support semantic annotation of WSDL 1.1 operations. The following XML Schema excerpt defines the attrExtensions element.
… <xs:element name="attrExtensions"> <xs:complexType> <xs:anyAttribute namespace="##any" processContents="lax" /> </xs:comlexType> </xs:element> …
The attrExtensions element is designed for use directly with WSDL 1.1 documents. It provides a general mechanism for adding extension attributes where attribute extensibility is not allowed, but element extensibility is allowed. It SHOULD NOT be used where attribute extensibility is allowed. For SAWSDL it is used to add the sawsdl:modelReference attribute in WSDL 1.1. It MUST NOT be used for SAWSDL annotations in WSDL 2.0.
portTypes
A portType corresponds to a WSDL 2.0 interface and is annotated in the same way.
Input and Output
Annotation of XML Schema types with modelReference, liftingSchemaMapping or loweringSchemaMapping can be accomplished using the approach described for annotating these elements in WSDL 2.0. In addition, a liftingSchemaMapping, loweringSchemaMapping or modelReference attribute may be added to a part element (under a message element) to specify an input or output annotation that applies to the entire message part. Message parts are referenced from the portType structure in WSDL 1.1 which generally corresponds to the WSDL 2.0 interface structure.
Faults
In WSDL 1.1, faults are specified as messages that are generated when a particular condition arises. In contrast to WSDL 2 a WSDL 1.1 fault is defined identically to a input or output, i.e. as reference to a message as subelement of the operation element. Annotations for fault messages are done just as annotations are done for any other output message.
Operations
Because operation in WSDL 1.1 does not do attribute extensibility, an operation is annotated by adding an attrExtensions element as a child of the operation element. The modelReference attribute of attrExtensions specifies the operation annotation. An example of such an annotation is shown below.
… <wsdl11:operation name="order"> <wsdl11:input message="OrderRequestMessage"/> <wsdl11:output message="OrderResponseMessage"/> <sawsdl:attrExtensions sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#RequestPurchaseOrder"/> </wsdl11:operation> …
The same example as shown in Section 1.4 is shown here in its WSDL 1.1 form. An important difference is the way messages are defined:
The other difference is the inclusion of attrExtensions to annotate the operation.
<wsdl11:definitions targetNamespace="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sawsdl="http://www.w3.org/2002/ws/sawsdl/spec/sawsdl#" name="OrderService"> <wsdl11:types> <xs:schema targetNamespace="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" elementFormDefault="qualified"> <xs:element name="OrderRequest" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderRequest" sawsdl:liftingSchemaMapping="http://www.w3.org/2002/ws/sawsdl/spec/mapping/Response2Ont.xslt"> <xs:complexType> <xs:sequence> <xs:element name="customerNo" type="xs:integer" /> <xs:element name="orderItem" type="item" minOccurs="1" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="item" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#Item"> <xs:all> <xs:element name="UPC" type="xs:string" /> </xs:all> <xs:attribute name="quantity" type="xs:integer" /> </xs:complexType> <xs:simpleType name="Confirmation"> <xs:restriction base="xs:string"> <xs:enumeration value="Confirmed"/> <xs:enumeration value="Pending"/> <xs:enumeration value="Rejected"/> </xs:restriction> </xs:simpleType> </xs:schema> </wsdl11:types> <wsdl11:message name="OrderRequestMessage"> <wsdl11:part name="OrderRequest" element="OrderRequest" /> </wsdl11:message> <wsdl11:message name="OrderResponseMessage"> <wsdl11:part name="OrderResponse" type="Confirmation" sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderConfirmation"/> </wsdl11:message> <wsdl11:portType name="Order"> <wsdl11:operation name="order"> <wsdl11:input message="OrderRequestMessage" /> <wsdl11:output message="OrderResponseMessage" /> <sawsdl:attrExtensions sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#RequestPurchaseOrder"/> </wsdl11:operation> </wsdl11:portType> </wsdl11:definitions>
This example is available as a separate file at http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order11.
This section describes how the WSDL extensions introduced in this document are mapped into an RDF form compatible with the WSDL 2.0 RDF Mapping [WSDL 2.0 RDF]. This specification introduces the properties {model reference}, {lifting schema mapping} and {lowering schema mapping}. Since the WSDL 2.0 RDF mapping does not provide an RDF form for the element declaration and type definition components, the schema mapping properties (i.e. {lifting schema mapping} and {lowering schema mapping}) are also not mapped. Therefore only {model reference} properties are mapped.
To represent the {model reference} property on any WSDL component (esp. Interface, Interface Operation, and Interface Fault components, as described earlier in this document) the name of the sawsdl:modelReference extension attribute is reused as an RDF property identifier (the full IRI of the property is then "http://www.w3.org/2002/ws/sawsdl/spec/sawsdl#modelReference"), as shown in table 4-1. As the value of {model reference} is a set of IRIs, an RDF triple is introduced for each of the IRIs.
Property | RDF Form |
---|---|
(componentId of the parent component generated per IRI-References for WSDL 2.0 Components) | |
{model reference} | (for each IRI <iri> in the value of {model reference}) <componentId> sawsdl:modelReference <iri> |
Note that WSDL 2.0 RDF Mapping section 2.2.2 Generic extensions provides a generic mapping for WSDL extensions into RDF. Component {model references} may thus be expressed in the graph as a structure with the modelReference attribute in a canonicalized XMLLiteral element. For a given component in the graph with the wsdl:ExtensionAttribute structure, each URI in the sawsdl:modelReference attribute implies that the component has a sawsdl:modelReference property of that URI. For example, the a graph:
<componentId> wsdl:extensionAttribute <genId> . <genId> rdf:type wsdl:ExtensionAttribute . <genId> quote:attributeHolder "<quote:attrContainer xml:base='http://example.com/rdf/products' xmlns:wsdl='...' xmlns:sawsdl='...' xmlns:quote='http://www.w3.org/2006/07/quotedXML#'; sawsdl:modelReference='../terms#BookSearch http://uddi.example/prodMatch'/>"^^rdf:XMLLiteral.
implies the two triples
<parentComponentId> sawsdl:modelReference <http://example.com/rdf/terms#BookSearch> . <parentComponentId> sawsdl:modelReference <http://uddi.example/prodMatch> .
In this appendix we present the accompanying semantic descriptions and mappings to the example WSDL document presented in Section 1.4.
The files used in this example are:
The specification does not prescribe a specific mapping language, however for the purpose of illustration a set of concrete technologies is chosen in this appendix. To illustrate the loweringSchemaMapping we assume that an agent has semantic data available as an RDF graph. For extracting data from this graph we use SPARQL. Other technologies such as XSLT alone are not well suited for this task, since an RDF graph does not have canonical XML representation. SPARQL defines a XML representation for its query answers, which is amendable for an XSLT transformation that in turn can produce the XML data required by the purchase order Web service.
In the following we present an XML file that captures the information necessary to perform the mapping from an RDF graph to XML data required by the Web service. The lowering node in this file contains two child nodes. The first node sparqlQuery includes SPARQL query to extract the data in form of a variable binding; the second node is the root node of a XSLT transformation.
<lowering> <sparqlQuery> PREFIX po: <http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#> SELECT ?qty ?UPC ?CustomerNo WHERE { ?order po:hasCustomer ?customer . ?customer po:hasCustomerID ?id . ?id po:hasLexicalRespresentation ?CustomerNo . ?order po:hasLineItems ?item . ?item po:hasQuantity ?qty . ?item po:hasProduct ?product . ?product po:hasProductCode ?code . ?code po:hasLexicalRespresentation ?UPC } </sparqlQuery> <xsl:transform version="2.0" xmlns:po="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:sp="http://www.w3.org/2005/sparql-results#"> <xsl:output method="xml" version="1.0" encoding="iso-8859-1" indent="yes" /> <xsl:template match="/sp:sparql"> <po:OrderRequest> <po:customerNo> <xsl:value-of select="sp:results/sp:result[position()=1]/sp:binding[@name='CustomerNo']/sp:literal" /> </po:customerNo> <xsl:apply-templates select="sp:results/sp:result" /> </po:OrderRequest> </xsl:template> <xsl:template match="sp:result"> <po:orderItem> <xsl:attribute name="quantity"> <xsl:value-of select="sp:binding[@name='qty']/sp:literal" /> </xsl:attribute> <po:UPC> <xsl:value-of select="sp:binding[@name='UPC']/sp:literal" /> </po:UPC> </po:orderItem> </xsl:template> </xsl:transform> </lowering>
We assume that some agent has semantic data as an RDF graph that is intended to be used for a Web service invocation. Such data could look like in the listing below, which shows an instance of the OrderRequest concept according to the purchase order ontology introduced earlier.
<!DOCTYPE rdf:RDF[ <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#" > ]> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#" xml:base="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#"> <owl:Ontology /> <OrderRequest> <hasLineItems> <LineItem> <hasProduct> <Product> <hasProductCode> <UPCCode> <hasLexicalRespresentation>348290187318</hasLexicalRespresentation> </UPCCode> </hasProductCode> </Product> </hasProduct> <hasQuantity rdf:datatype="&xsd;float">12</hasQuantity> </LineItem> </hasLineItems> <hasLineItems> <LineItem> <hasProduct> <Product> <hasProductCode> <UPCCode> <hasLexicalRespresentation>998212387318</hasLexicalRespresentation> </UPCCode> </hasProductCode> </Product> </hasProduct> <hasQuantity rdf:datatype="&xsd;float">4</hasQuantity> </LineItem> </hasLineItems> <hasCustomer> <Customer> <hasCustomerID> <CustomerID> <hasLexicalRespresentation>007</hasLexicalRespresentation> </CustomerID> </hasCustomerID> </Customer> </hasCustomer> </OrderRequest> </rdf:RDF>
When the SPARQL is applied to the RDF graph above, the following XML will be generated as query answer.
<sparql xmlns="http://www.w3.org/2005/sparql-results#"> <head> <variable name="qty" /> <variable name="UPC" /> <variable name="CustomerNo" /> </head> <results> <result> <binding name="qty"> <literal>12</literal> </binding> <binding name="UPC"> <literal>348290187318</literal> </binding> <binding name="CustomerNo"> <literal>007</literal> </binding> </result> <result> <binding name="qty"> <literal>4</literal> </binding> <binding name="UPC"> <literal>998212387318</literal> </binding> <binding name="CustomerNo"> <literal>007</literal> </binding> </result> </results> </sparql>
When the XSLT is applied to the output of the SPARQL query, the following XML data is generated. This data corresponds to the element which has been annotated with the loweringSchemaMapping and can be used by some agent to invoke the purchase order Web service.
<ex:OrderRequest xmlns:POOntology="http://example.org/ontologies/purchaseorder#" xmlns:sp="http://www.w3.org/2005/sparql-results#" xmlns:po="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:ex="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order# ../wsdl/SchemaOnly.xsd "> <ex:customerNo>007</ex:customerNo> <ex:orderItem quantity="12"> <ex:UPC>348290187318</ex:UPC> </ex:orderItem> <ex:orderItem quantity="4"> <ex:UPC>998212387318</ex:UPC> </ex:orderItem> </ex:OrderRequest>
The mapping specification that is referenced using a liftingSchemaMapping takes as input XML data and produces semantic data as output. Within the purchase order example we have annotated the response type, i.e. OrderResponse. The XML data corresponding to the type can be transformed using XSLT or XQuery in order to obtain data processable by a semantic agent.
A possible response of the purchase order Web service is the following XML data.
<OrderResponse xmlns="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" >Confirmed</OrderResponse>
The XSLT specification below defines how to convert the XML data to an RDF graph corresponding to the purchase ontology.
<xsl:transform version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:po="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" xmlns:POOntology="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#"> <xsl:output method="xml" version="1.0" encoding="iso-8859-1" indent="yes" /> <xsl:template match="/"> <POOntology:OrderConfirmation> <hasStatus rdf:datatype="http://www.w3.org/2001/XMLSchema#string"> <xsl:value-of select="po:OrderResponse" /> </hasStatus> </POOntology:OrderConfirmation> </xsl:template> </xsl:transform>
When above XSLT is applied to the example response the following RDF instance will be produced as output.
<!DOCTYPE rdf:RDF[ <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#" > ]> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#" xml:base="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#"> <owl:Ontology /> <OrderConfirmation> <hasStatus rdf:datatype="&xsd;string">Confirmed</hasStatus> </OrderConfirmation> </rdf:RDF>
Equally well one can specify the mapping using XQuery. If both mapping are present a processor can choose the one it is able to interpret.
xquery version "1.0"; declare namespace po="http://www.w3.org/2002/ws/sawsdl/spec/wsdl/order#" ; declare namespace rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"; declare namespace owl="http://www.w3.org/2002/07/owl#" ; <rdf:RDF> <owl:Ontology /> <po:OrderConfirmation> <po:hasStatus rdf:datatype="http://www.w3.org/2001/XMLSchema#string">{ fn:string(/) }</po:hasStatus> </po:OrderConfirmation> </rdf:RDF>
The SAWSDL schema is also available as a separate file at document.
<xs:schema targetNamespace="http://www.w3.org/2002/ws/sawsdl/spec/sawsdl#" xmlns="http://www.w3.org/2002/ws/sawsdl/spec/sawsdl#" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://www.w3.org/2006/01/wsdl"> <xs:simpleType name="listOfAnyURI"> <xs:list itemType="xs:anyURI"/> </xs:simpleType> <xs:attribute name="modelReference" type="listOfAnyURI" /> <xs:attribute name="liftingSchemaMapping" type="listOfAnyURI" /> <xs:attribute name="loweringSchemaMapping" type="listOfAnyURI" /> </xs:schema>
One purpose for annotating services at the interface level is to help enable dynamic discovery. This is possible when services are published, catalogued and annotated with semantics. The modelReference mechanism adds categorization information to interfaces which could be used while publishing services in registries such as UDDI [UDDI]. Users can choose any categorization of their choice such as NAICS [NAICS], UNSPSC [UNSPSC] and GICS [GICS]. This aids in service discovery by narrowing the range of candidate services. The categorization can be used as input when the service is published in a UDDI registry since taxonomies supported by UDDI can be specified via a semantic model. Service categorization is also aimed at supporting specialized taxonomies of middleware or utility services such as mediators. The categorization modelReference is used to ensure that there is basic and high-level categorization information about a service.
In this example, a modelReference points to an RDF instance that gives three pieces of information, the name of the category, the taxonomy value (category code) of the category and the URI of the taxonomy. An example of instance data that would be referenced by an interface annotation is shown here.
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:if="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#"> <if:Category rdf:about="urn:Electronics" if:hasValue="443112" if:usesTaxonomy="http://naics.com/"/> </rdf:RDF>
This instance data derives from the following simple example model.
<rdf:RDF> <rdfs:Class rdf:about="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#Category"/> <rdf:Property rdf:about="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#hasValue"> <rdfs:domain rdf:resource="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#Category"/> <rdfs:range rdf:resource="http://www.w3.org/2000/01/rdf-schema#Literal"/> </rdf:Property> <rdf:Property rdf:about="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#usesTaxonomy"> <rdfs:domain rdf:resource="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#Category"/> <rdfs:range rdf:resource="http://www.w3.org/2001/XMLSchema#anyUri"/> </rdf:Property> </rdf:RDF>
Using this simple model, it is possible to create categorizations using the registered taxonomies in UDDI. This information can then be reused when the service is published in the UDDI registry. In the following example we use the NAICS taxonomy registered in UDDI.
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:if="http://www.w3.org/2002/ws/sawsdl/spec/ontology/interface#"> <if:Category rdf:about="urn:Electronics" if:hasValue="443112" if:usesTaxonomy="uddi:uddi.org:ubr:categorization:naics:2002"/> </rdf:RDF>
When publishing in UDDI V3, the category bag created to classify the service would be built from this information. This is the UDDI categoryBag structure that would derive from this categorization.
<categoryBag> <keyedReference tModelKey="uddi:uddi.org:ubr:categorization:naics:2002" keyName="Electronics" keyValue="443112"/> </categoryBag>
The other UDDI taxonomies would also be referenced via their registered URIs.
This document is the work of the W3C Semantic Annotations for Web Service Description Language Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Rama Akkiraju (IBM Corporation), Carine Bournez (W3C), J.B. Domingue (The Open University), Joel Farrell (IBM Corporation), Laura Ferrari (Telecom Italia SpA), Laurent Henocque (ILOG, S.A.), Mathias Kleiner (ILOG, S.A.), Jacek Kopecký (DERI Innsbruck at the Leopold-Franzens-Universität Innsbruck, Austria), Holger Lausen (DERI Innsbruck at the Leopold-Franzens-Universität Innsbruck, Austria), John Miller (University of Georgia Research Foundation, Inc (UGARF)) Carlos Pedrinaci (The Open University), Eric Prud'hommeaux (W3C), Brahmananda Sapkota (DERI Galway at the National University of Ireland, Galway, Ireland), Amit Sheth (Fortent), Claudio Venezia (Telecom Italia SpA), Tomas Vitvar (DERI Galway at the National University of Ireland, Galway, Ireland).
Date | Author | Description |
---|---|---|
20062009 | HL | Corrected links, sorted references, removed redundant namesapaces from example. |
20061909 | JAF | Resolutions from 18 Sept. WG call - Section 2 text, Terminology, UDDI example, and references. |
20060709 | JAF | Clean up for Last Call publication. |
20060609 | JAF | Included all major editorial decisions from f2f Aug 30, 31. |
20063108 | HL | Included RDF Mapping |
20062308 | HL | Implemented editorial comments of Jack, added example for inline reference of semantic model. |
20062108 | JAF | Documented resolutions to issues 26 and 27. |
20061508 | JAF | Documented remainder of the resolution to issue 22 on WSDL 1.1 (operation annotation). |
20062107 | JAF | Documented resolution to issue 22 on WSDL 1.1 (but operation annotation question still open) and issue 23 on interface extensions. Also updated semantics definition based on 18 July 2006 WG call. |
20061007 | HL | Replaced XSLT example with "more correct" version. |
20061007 | HL | Removed relativ looking URIs from modelReference examples and replaced with full URIs. |
20060628 | JAF | Made all textual changes required for publication as 1st Public Draft, as indentified in 27 June 2006 WG call. |
20060626 | JAF | Completed documentation of decisions from f2f in Galway, including resolutions to issues 6, 7, 8, 9 and 14 on schema mapping, and 10 on categorization as a modelReference. (Some done in HL's previous update) |
20060620 | HL | Reordered Appendixes according to f2f. Referenced copy of RNet ontology. changed text on semantic models |
20060614 | JAF | Documented resolution to Issue 18: Relationship between modelReferences. Documented initial part of Issue 6 on lifting and lowering mappings. Continued with section 2 restructuring. |
20060607 | JAF | Documented resolution to Issue 5: Multiplicity of modeReferences. Documented initial part of Issue 6: Clarification of SchemaMapping concept. |
20060530 | JAF | Documented resolution to Issue 2: embedding semantic descriptions. Removed some WSDL 1.1 terminology. |
20060523 | HL | changed categoryname from xs:NcName to xs:string. |
20060523 | HL | Introduced simple example in Section 1, modified structure 2 to reflect the elements defined. (Addressed Issue 1 and 9). |
20060519 | JAF | Split References into Normative and Informative and brought them up to TR quality. |
20061505 | HL | made sawsdl scheme independent of wsdl xsd by resolution in http://www.w3.org/2002/ws/sawsdl/minutes/20060509 |
20060508 | HL | Created sawsdl xsd, removed example.org imports for sawsdl schema. |
20060509 | HL | Created separate files for documents in purchase order example (grouped xsds to one file). Corrected several errors (mainly namespace), adopted xslt and XQuery examples respectively. |
20060504 | JAF | Based on 02 May 06 call - added requirements on semantic models, example.org for examples namespace, added todo list. More editorial clean up. |
20060418 | JAF | Changed name of spec based on decision in 18 April 06 call. Also editorial clean up. |
20060414 | JAF | Removed non-spec material from Mapping Choices Appendix. |