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

Jacek,

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.

Regards
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
>
http://example.org/categorization/PurchaseOrderServices/ItemAvailability
>       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

Done

>
> 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.

Done

>
> 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

Done

> 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.

Done.

>
> 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