RE: [ws-rx] i093 cardinality replacements

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

I think readers unfamiliar with schema would have similar problems with
the exemplar. I agree the exemplar is succinct. However I still prefer
the existing text in the description of the elements as I find it
helpful and clear as well. 

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


-----Original Message-----
From: Anish Karmarkar [mailto:Anish.Karmarkar@oracle.com] 
Sent: Wednesday, May 24, 2006 5:22 PM
To: Doug Bunting
Cc: Marc Goodner; Gilbert Pilz; ws-rx@lists.oasis-open.org
Subject: Re: [ws-rx] i093 cardinality replacements

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
>>>