Re: [ws-rx] i093 cardinality replacements

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

If that text is for making things easier to the readers, then I would 
say that it is best to avoid all 2119 keywords -- they are unnecessary.

I would also say that the notion that the exemplar is not clear to a lot 
of people isn't quite true. It uses a very simple notation which most 
folks who understand XML would have no problem comprehending. For those 
few who are not familiar with ?/*/+ can read section 1.2.

-Anish
--

Marc Goodner wrote:
> 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
>>>>