SAWSDL External Annotation Proposal

This document proposes a possible use of SAWSDL to provide external annotations, in reply to issue 13 in AWSDL Last Call 20060928 . Obviously enough, since SAWSDL is XML, XPath/XQuery could be be useful for such external anotations. The SAWSDL charter however excludes the possibility for the group to work on a language for external annotations. Hopefully, SAWSDL as defined in the Last Call 2060928 (accessed on 2006 Dec the 12th) can be used for that purpose, maybe at the expense of slight WSDL schema changes required to make some elements optional.

In order to illustrate the proposal, I first recall the example in the SAWSDL last call presented at section 1.4. For clarity, the semantic annotations are highlighted in this style, which allows to easily figure out what the non annotated file could look like.

Then, Section "1.4.ext" illustrates a possible external specification for the same WSDL file, where all non annotated sections are treated as optional, provided that elisions do not generate ambiguities.

1.4 Example (original as from SAWSDL LC )

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.

1.4.ext Example (external annotation alone)

What follows is a file externally adding the same annotations to the above document. There, only the xml structure providing an unambiguous path to the annotated elements is preserved. For clarity again, the external annotation is presented as the original annotated document where all irrelevant information has been grayed.

<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 actual external annotation (without the grayed regions) follows. Note that the resulting file is not valid since there may exist references to undeclared elements (as e.g. types), that are to be searched for in the original WSDL. The semantics of this external annotation is obtained by superimposing the xml structure to that of the externally annotated WSDL (or SAWSDL)

<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#">
      <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:element>
      <xs:simpleType name="confirmation"
          sawsdl:modelReference="http://www.w3.org/2002/ws/sawsdl/spec/ontology/purchaseorder#OrderConfirmation">
      </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:operation>
  </wsdl:interface>
</wsdl:description>

Conclusion