OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

ws-rx message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [ws-rx] i093 cardinality replacements


I'm working through this again and it is really number 3 below that I
dislike. 

I think we've let cardinality angle of this take us away from the point.
I think the meaning of the current text is clear despite what a very
strict reading may say. I don't find it confusing at all to understand
that any statements about what is required are predicated on the
optional element that contains the element or attribute being described.
It is the new sentence that is introduced here that attempts to restate
that the containing optional element is present that I find unnecessary.


In every case in this revision to the doc I'm fine with the changes for
this issue if the sentence introduced as describe in 3 below were
struck.

Here is one example, being the first instance of this.

Original text:
/wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
This REQUIRED element MUST contain an absolute URI conformant with
RFC3986 [URI] that uniquely identifies the offered Sequence.

Current proposed text:
/wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
An RM Source that includes a <wsrm:Offer> element within a
CreateSequence message MUST include this element as a child of the
<wsrm:Offer> element. This RM Source MUST set the value of this element
to an absolute URI (conformant with RFC3986 [URI]) that will uniquely
identify the offered Sequence.

Alternate proposed text:
/wsrm:CreateSequence/wsrm:Offer/wsrm:Identifier
This RM Source MUST set the value of this element to an absolute URI
(conformant with
RFC3986 [URI]) that will uniquely identify the offered Sequence.


I suggest that we accept the changes proposed in message 117 from this
month [1] with the following exceptions (line numbers from change bar
version): 
Strike sentence introduced on line 285 ending on line 286.
Strike sentence introduced on line 293 ending on line 294.
Strike sentence introduced on line 366 ending on line 367.
Strike sentence introduced on line 652 ending on line 654.
Strike sentence introduced on line 658 ending on line 660.


1 Message 117 " i093 edits - preview"
http://lists.oasis-open.org/archives/ws-rx/200605/msg00117.html

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


-----Original Message-----
From: Gilbert Pilz [mailto:Gilbert.Pilz@bea.com] 
Sent: Thursday, May 18, 2006 5:02 PM
To: ws-rx@lists.oasis-open.org
Subject: [ws-rx] i093 cardinality replacements

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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]