RE: [ws-rx] i093 cardinality replacements

["Marc Goodner" <mgoodner@microsoft.com>]

Yes, I thought about the two instances you cite here as well. I'm fine
with either alternative you propose here. I share your concern over the
second MUST, a SHOULD would probably be safer there.

Marc Goodner
Technical Diplomat
Microsoft Corporation
Tel: (425) 703-1903
Blog: http://spaces.msn.com/mrgoodner/ 


-----Original Message-----
From: Doug.Bunting@Sun.COM [mailto:Doug.Bunting@Sun.COM] 
Sent: Thursday, May 25, 2006 12:04 PM
To: Doug Bunting
Cc: Marc Goodner; Gilbert Pilz; ws-rx@lists.oasis-open.org
Subject: Re: [ws-rx] i093 cardinality replacements

Marc,

I have looked at the PDF files and think all of the suggestions you make
are positive. The document has MUST requirements (on the RMS) for most
of the affected elements and attributes in any case.

The only exception's are /wsrm:CreateSequence/wsrm:Offer/wsrm:Endpoint
(lines 251-254 without change bars, lines 293-296 with) and
/wsrm:CreateSequenceResponse/wsrm:Accept/wsrm:AcksTo (lines 324-328 w/o
change bars, lines 366-370 w/). I somewhat prefer being prescriptive but
can live with your proposed

    This element, of type wsa:EndpointReferenceType (as specified by
    WS-Addressing [WS-Addressing]), specifies the endpoint reference to
    which <wsrm:SequenceAcknowledgement> messages related to the
    accepted Sequence are to be sent.

as all we say (taking the second example). One alternative would be

    An RM Source MUST include this element, of type
    wsa:EndpointReferenceType (as specified by WS-Addressing
    [WS-Addressing]). The RM Destination MUST send
    <wsrm:SequenceAcknowledgement> messages related to the accepted
    Sequence to the specified endpoint reference.

I'm not sure about the second MUST (might be SHOULD or even MAY since I
seem to remember a per-acknowledgement override somewhere). That's
secondary since my main reason for making the change was to avoid the
round-about passive voice of the original.

thanx,
doug

On 25/05/06 11:34, Doug Bunting wrote:
> Marc,
>
> This seems reasonable to me though I haven't opened up the document 
> again and looked at all of the sentences you reference (will soon).
> Thanks for proposing a compromise you can live with.
>
> One question: Should the predication you describe be mentioned early 
> in the document to avoid making assumptions about our readers?
>
> thanx,
> doug
>
> On 25/05/06 11:20, Marc Goodner wrote:
>> I'm working through this again and it is really number 3 below that I

>> dislike.
>> I think we've let cardinality angle of this take us away from the
point.
>> I think the meaning of the current text is clear despite what a very 
>> strict reading may say. I don't find it confusing at all to 
>> understand that any statements about what is required are predicated 
>> on the optional element that contains the element or attribute being
described.
>> It is the new sentence that is introduced here that attempts to 
>> restate that the containing optional element is present that I find
unnecessary.
>>
>>
>> In every case in this revision to the doc I'm fine with the changes 
>> for this issue if the sentence introduced as describe in 3 below were

>> struck.
>>
>> Here is one example, being the first instance of this.
>>
>> Original text:
>> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
>> This REQUIRED element MUST contain an absolute URI conformant with
>> RFC3986 [URI] that uniquely identifies the offered Sequence.
>>
>> Current proposed text:
>> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
>> An RM Source that includes a <wsrm:Offer> element within a 
>> CreateSequence message MUST include this element as a child of the 
>> <wsrm:Offer> element. This RM Source MUST set the value of this 
>> element to an absolute URI (conformant with RFC3986 [URI]) that will 
>> uniquely identify the offered Sequence.
>>
>> Alternate proposed text:
>> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
>> This RM Source MUST set the value of this element to an absolute URI 
>> (conformant with
>> RFC3986 [URI]) that will uniquely identify the offered Sequence.
>>
>>
>> I suggest that we accept the changes proposed in message 117 from 
>> this month [1] with the following exceptions (line numbers from 
>> change bar
>> version): Strike sentence introduced on line 285 ending on line 286.
>> Strike sentence introduced on line 293 ending on line 294.
>> Strike sentence introduced on line 366 ending on line 367.
>> Strike sentence introduced on line 652 ending on line 654.
>> Strike sentence introduced on line 658 ending on line 660.
>>
>>
>> 1 Message 117 " i093 edits - preview"
>> http://lists.oasis-open.org/archives/ws-rx/200605/msg00117.html
>>
>> Marc Goodner
>> Technical Diplomat
>> Microsoft Corporation
>> Tel: (425) 703-1903
>> Blog: http://spaces.msn.com/mrgoodner/
>>
>> -----Original Message-----
>> From: Gilbert Pilz [mailto:Gilbert.Pilz@bea.com] Sent: Thursday, May 
>> 18, 2006 5:02 PM
>> To: ws-rx@lists.oasis-open.org
>> Subject: [ws-rx] i093 cardinality replacements
>>
>> As of WD-12 our spec has a number of explanations of sub-elements 
>> with the following pattern:
>>
>> /wsrm:Foo/wsrm:Baz
>> This [REQUIRED | OPTIONAL] element . .
>> There are actually a number of different cases under which this 
>> pattern is used.
>>
>> 1) Describing a singly-nested sub-element within a message element.
>> Example: /wsrm:CreateSequence/wsrm:AcksTo
>>
>> 2) Describing a singly-nested sub-element within a header element.
>> Example: /wsrm:AckRequested/wsrm:Identifier
>>
>> 3) Describing a doubly-nested sub-element within a top-level message 
>> element when the parent element is optional. Example:
>> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
>>
>> There are other cases like doubly-nested attributes within top-level 
>> header elements who's parent elements are optional, etc. but you get 
>> the point.
>>
>>
>> I have used the following patterns to address these cases:
>>
>> 1) The RM [Source | Destination] [MUST | MAY] include this element in

>> any Foo message it sends.
>>
>> (Note the use of the informal "Foo message" as shorthand for "SOAP 
>> envelope that includes the <wsrm:Foo> element in the body of that
>> envelope")
>>
>> 2) An RM [Source | Destination] that includes a <wsrm:Foo> header 
>> block in a SOAP envelope [MUST | MAY] include this element in that 
>> header block.
>>
>> 3) An RM [Source | Destination] that includes a <wsrm:Baz> element 
>> within a Foo message [MUST | MAY] include this element as a child of 
>> the <wsrm:Baz> element.
>>
>> If anyone in the group has any suggestions on some better phrasing 
>> for these patterns I would be more than happy to hear them.
>>
>> Also, with respect to the idea that the current cardinality 
>> statements are somehow clear to the reader, take a second look at the

>> example for case (3):
>>
>> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
>> This REQUIRED element MUST contain an absolute URI conformant with
>> RFC3986 [URI] that uniquely identifies the offered Sequence.
>>
>> What it *means* is that if you include an Offer in your 
>> CreateSequence then you MUST include the Identifier in that Offer but

>> all it *says* is "This REQUIRED element . . ." This doesn't seem very
clear to me at all.
>>
>> - gp