[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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]