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

Received on Friday, 19 July 2002 02:08:09 UTC