W3C home > Mailing lists > Public > public-ws-semann@w3.org > September 2006

Re: issues with the Usage Guide to be resolved before publication

From: Rama Akkiraju <akkiraju@us.ibm.com>
Date: Wed, 27 Sep 2006 20:13:11 -0400
To: Jacek Kopecky <jacek.kopecky@deri.org>
Cc: Brahmananda Sapkota <brahmananda.sapkota@deri.org>, SAWSDL public list <public-ws-semann@w3.org>, public-ws-semann-request@w3.org
Message-ID: <OF98E678F8.DED1BC27-ON852571F6.00833490-852571F7.0001353D@us.ibm.com>


Thank you for your detailed comments. I have incorporated most the changes
you suggested and checked the latest SAWSDL usage guide. I need a volunteer
to help verify this updated version before we can send it to W3C team leads
for First Working Draft Publication.

My responses are below in detail.

Rama Akkiraju

public-ws-semann-request@w3.org wrote on 09/26/2006 11:37:00 AM:

> Hi Rama and Brahmananda,
> here is a list of things that need to be fixed in the Usage Guide before
> I think it can be published. They will be discussed in our telcon
> shortly.
> 1) fix all the annotation URIs:
> there are the following types of problems:
>    a) using domain names like owl-ontologies.com, mynamespace.com -
>       we absolutely cannot use such domains, instead we have our w3.org
>       spec URIs and example.com and similar.
>    b) writing a URI like "www.w3.org/..." which misses "http://" -
>       e.g. in listing 3.2-2
>    c) writing a URI like "schemaMappingNS#OrderRequest.xslt" seems to
>       intend to identify a file OrderRequest.xslt but misplaces the name
>       in fragment ID
>    d) writing URIs like "SampleOntology#UPC" to point to something that
>       is elsewhere defined as
>       "http://www.mynamespace.com/SampleOntology.owl#UPC"
>    e) similarly, writing URIs like
>       to point to something that is elsewhere defined as
>       http://www.owl-ontologies.com/unnamed.owl#ItemAvailabilityCheck
>    f) unhelpful URIs like http://www.owl-ontologies.com/unnamed.owl#
>       should be avoided
>    g) using relative URIs without specifying the base - instead you can
>       use entity references or full URIs which won't be so long anyway
>       after we publish

Thanks for catching all these. I tried to addressed all of these. For item
e), all URI references in the document currently refer to
http://org1.example.com/... or http://org2.example.com/... etc. (Per Eric's
suggestion). For item g), I have included the full URI's in all WSDL
excerpts. I did not do this for Turtle excerpts.

> 2) put listing captions before the listings. Listings flow with the text
> so they are not viewed as a block and the user usually sees the caption
> only after reading the whole listing.

Throughout the document, I have added context and description so that
listings are introduced before they are included. This way the user has
better context of a listing while reading it. The conventional way of
adding captions for figures and listings is at the end. So, I still kept
the captions at the end of each listing. But I think the context upfront
helps address your point.

> 3) rename 2.a and 2.b to 2.1 and 2.2 (renumbering the current 2.1) - as
> it is, the two first subsections of 2 (a and b) are not well
> distinguished


> 4) complete listing 3.1-3 - the ontology also defines classes
> DeliveryDate, Quantity and AvailabilityConfirmation, according to the
> URIs that are used in listing 3.1-2.


> 5) add an editor's note or TODO in section 3.2 that the listings
> currently use URIs from a single ontology (SampleOntology) but should
> use URIs from two ontologies (as the text implies), and a mapping
> ontology is available that ties those two together (that's because the
> mapping ontology won't change the URIs of the things mapped).

I have revised section 3 so that the two different ontologies and the
mapping ontology are shown explicitly in the listings. I updated the text
to reflect this change. I need a volunteer to help verify it.

> 6) fix the formatting of listings 3.2-3 and 4-3, in the latter just drop
> the XML declaration (and the same elsewhere if other XML snippets have
> it)

Done (Thanks to Eric)

> 7) add an editor's note or TODO in section 3.3 that it shall be merged
> with section 3.4 - the bulk of what is in section 3.4 belongs in the now
> very short 3.3, and then 3.4 would only say that techniques from 3.2 and
> 3.3 can be used together (combining subClass reasoning with
> composition), which can be a note at the end of 3.3.

I have updated section 3.3 to include additional listings and more
explanation to address your point. I think section 3.4 is valuable as is
and I don't think it should be merged with 3.3. Just the way we provide a
full example to show matching via ontology mediation (instead of just
saying one can use a mapping ontology to map different annotations used by
different WSDLs and leave it at that), I think it is valuable to show a
full example for Web service composition via ontology inferencing. I
updated the listings and text in Section 3.4 to reflect the existance of
different ontologies and a mapping ontology.

> 8) in listing 3.4-2, add a modelReference on the WSDL operation that
> says the operation does translation, something like:
> modelReference="http://example.com/utilities#translation"
> and say in the text that this will let the composer know that this
> function does the translation and can be put in the correct place in the
> composition


> 9) drop paragraph after listing 3.5-1 and the listing 3.5-2 - the text
> and the listing seem to indicate that ontology terms can be inferred
> reliably from the names of XML elements, which is not what we want to
> imply, I'd say. Instead we can say something like this:
> "If a requesting WSDL is annotating with multiple concepts like shown in
> listing 3.5-1, this increases the number of matching service WSDLs, and
> similarly if a service WSDL is annotated with multiple concepts, more
> request WSDLs will match it."

Good Catch. Done. Thanks for the wording suggestion.

> 10) drop the last sentence from the paragraph after listing 3.6-1 -
> I don't think we talk about behavioral aspects of parameters - we only
> talk about behavioral aspects of operations or interfaces in SAWSDL.


> 11) add an editor's note or TODO in section 4 that the current leading
> text will be rewritten - it is all from a perspective of discovery, not
> invocation. The text should really talk about XML messages going to and
> from the service, and schemaMapping them from and to semantic data on
> the client, that can also be obtained by symetrically mapping the
> client's XML data using schemaMappings.

I have revised the ending text of section 3 and leading text in section 4
to introduce schema mapping concept more clearly.

> 12) add an editor's note or TODO around listing 4-3 that the XSLT, as it
> is, does not work, and that it will be completed.

Editor's TODO note added.

> As I said, we will discuss these points in the telcon when we discuss
> what needs to be done before we can publish the first public working
> draft of the usage guide, so there will be space for disagreement or
> clarifications.
> Hope this helps,
> Jacek
Received on Thursday, 28 September 2006 00:13:27 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 19:58:46 UTC