Re: [ws-rx] i093 cardinality replacements

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

I actually like option 6. Much easier from editor's POV.
The sentences in question do not add anything wrt to conformance. The 
spec says that the schema is normative and the schema already has these 
cardinality constraints. For readers that do not want to look at the 
schema (or don't understand schema) there is the exemplar with '*' and 
'+' in them. Personally I find the exemplar succinct and easier to 
follow (as I don't have to go look for the cardinality constraints as 
they are spread out.

But I could also live with all the other options.

-Anish
--

Doug Bunting wrote:
> 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
>>>