Re: Message in Example 2 in Primer doesn't match prose exactly

Thank you for your comment, which has been listed as Issue 296 in the SOAP 1.2
Last Call Issues List. 

Your suggestion appears to be a good one, and I shall include it in the next revision
of the SOAP 1.2 Primer.

Thank you,
Nilo Mitra

Nilo Mitra
Ericsson Internet Applications, Inc.
phone: +1 516-677-1073
mobile: +1 516-476-7427
email: nilo.mitra@ericsson.com 



From: "Peter Drayton" <peter@razorsoft.com>
To: <xmlp-comments@w3.org>
Date: Thu, 18 Jul 2002 23:08:02 -0700
Message-ID: <001d01c22eea$a55d8630$56a6accf@razorsoft.com>
Subject: Message in Example 2 in Primer doesn't match prose exactly


SOAP Version 1.2 Part 0: Primer, Section 2.2.1, Example 2:

The prose describing the message says that the message is returned from
the travel service, requesting clarification on the choice of airports
in the departing city. However, the message itself doesn't (a) contain
any indication that it is a request for clarification; (b) indicate if
the request pertains to the outbound leg or the inbound leg; (c)
indicate if the request pertains to the departure or arrival airport of
a specific leg.

It is possible to claim that the target node provides the context for
processing the message, i.e the message might be sent to different
endpoints depending on which leg & choice of arrival/departure requires
clarification, and the endpoints might know that they are participating
in a conversational exchange and understand the flow, but I don't think
this is very clear. It also seems strange to me that the same
<itinerary> element is sent in both directions, with different child
elements and meaning. I don't think this is as clear as it could be for
a primer.

I'd suggest modifying example 2 to make the flow of messages back and
forth clearer. For example:

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
 
env:role="http://www.w3.org/2002/06/soap-envelope/role/next"
                 env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
 
env:role="http://www.w3.org/2002/06/soap-envelope/role/next"
               env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <q:itineraryClarification
xmlns:q="http://travelcompany.example.org/reservation/travel/">
   <q:departure>
    <q:departing>
     <q:airportChoices>
      JFK LGA EWR 
     </q:airportChoices>
    </q:departing>
   </q:departure>
   <q:return>
    <q:arriving>
     <q:airportChoices>
      JFK LGA EWR 
     </q:airportChoices>
    </q:arriving>
   </q:return>
  </q:itineraryClarification>
 </env:Body>
</env:Envelope>

This structure mirrors the prose, presuming the prose meant "...namely
the choice of airports in the departing city *on both the outbound and
the inbound legs*". If the prose meant to only request clarification on
one of the legs, the sample could obviously be simplified.

--Peter
http://www.razorsoft.net/weblog
http://staff.develop.com/peterd