Re: [ws-rx] i093 cardinality replacements

[Doug Bunting <Doug.Bunting@Sun.COM>]

Marc,

On 24/05/06 13:21, Marc Goodner wrote:
> I don't like 4.
>   
Could you be a bit more specific?

> I'm not sure I understand 5, it seems to remove the 2119 language
> regarding cardinality but it doesn't seem to work for the content.
> So this example:
> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
> This REQUIRED element MUST contain an absolute URI conformant with
> RFC3986 [URI] that uniquely identifies the offered Sequence.
>
> Would become:
> /wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
> The cardinality of this element is 1. When present this element MUST
> contain an absolute URI conformant with RFC3986 [URI] that uniquely
> identifies the offered Sequence.
>   
Your replacement still has the element taking an action. It's the sender 
or receiver of that element which MUST do something. In this case, the 
RMS MUST give it a particular type of value when using this element. A 
better replacement using the (5) model would be:

    The cardinality of this element is 1. An RMS MUST set the value of
    this element to an absolute URI conformant with RFC3986 [URI] that
    uniquely identifies the offered Sequence.

> I really dislike 6.
>   
OK, I think I remember why but could you remind me?

thanx,
doug
> -----Original Message-----
> From: Doug.Bunting@Sun.COM [mailto:Doug.Bunting@Sun.COM] 
> Sent: Thursday, May 18, 2006 5:58 PM
> To: Gilbert Pilz
> Cc: ws-rx@lists.oasis-open.org
> Subject: Re: [ws-rx] i093 cardinality replacements
>
> Gil,
>
> A couple of other alternatives come to mind:
> 4) "The cardinality of this element {within its parent|within an XYZ
> {request|response}} is {0 or more|0 or 1|1 {or more}?}."
>
> 5) "The cardinality of this element is {0 or more|0 or 1|1 {or more}?}."
>
>     This option relies on an implication that "cardinality" is scoped to
>     presence within its parent &c.
>
> 6) nuking these sentences and relying on the exemplars
>
>     I believe this option was poorly received during our call / chat
> today.
>
> I kind of like (5).
>
> thanx,
> doug
>
> On 18/05/06 17:01, Gilbert Pilz wrote:
>   
>> 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
>>   
>>