Re: [ws-rx] i093 cardinality replacements

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

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
>