Comments on WS-Reliability CD 0.992

[Pete Wenzel <pete@seebeyond.com>]

Here is my laundry list of things to fix in CD-0.992; most are
editorial in nature.


Line 98: Says "This specification addresses end-to-end reliability,
and is not concerned with intermediaries."  However, there is nothing to
prevent someone targeting Reliability headers to "next" role/actor.
This case should be explicitly forbidden, rather than left undefined.

Lines 129, 1620: Reuse of "wsrm" prefix for different namespaces
is confusing.  Choose a different one for the feature namespace in
the appendix.

Line 134: Change
  "This specification defines reliable messaging protocol embedded in
  the SOAP Header."
to
  "This specification defines reliable messaging protocol features,
  expressed as extension header blocks embedded in the SOAP Header."

140 Use official name of the standard.  Its title must be "WS-Security
2004", not just "WS-Security", to avoid confusion with prior incarnations.
Remove the last sentence of this paragraph, which is already obsolete.

Also Line 1581, reference should be:
[WSS] "OASIS Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)".
Available at
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

Section 1.5: Examples are placed in an awkward location.  Should appear
after the protocol & features are described.  Suggest moving them to a
non-normative appendix.

Line 279: Change
  "A module capable of processing and enforcing Reliable Messaging as
  described in this specification."
to
  "A SOAP Processor capable of processing Reliable Messaging SOAP
  header blocks."

Line 281, 317 (and throughout document): Prefer the more grammatical forms
"Sending RMP"/"Receiving RMP" rather than "Sender RMP" and "Receiver RMP".
Also replace instances where just "sender"/"receiver" are used, to be
more specific that we are referring to a sending or receiving RMP.

569: Sequence Number is not a Feature; it is simply a mechanism used to
implement Guaranteed Message Ordering.  Should not be given equal status
to the other 3 features.

1025-1030: Example in which SOAP Fault may also convey an RM
Acknowledgment requires a confusing or impossible processing order.
(Process RM headers, remember that an Ack needs to be sent, continue
with header processing and SOAP Body validation and finally "application
processing space outside the realm of the receiving RMP".)  How does
the RMP know when all processing has been completed, then intercept a
possible SOAP Fault in order to attach its Ack?

1990: Remove appendix if there is nothing to say here; the sole item
listed is already done (Appendix A).

The specification contains no reference to the schemas.  They should
be listed in the normative appendix, and introduced at an appropriate
location in the text, perhaps at the beginning of Section 4.


269: Remove line break in the middle of "response".
501: "the Sender RMP notifies a delivery failure"
  should be
  "the Sending RMP is notified of a delivery failure".
522: "an" should be "a".
526: "nor to notify failure on the sender side" should be "nor to notify
  the RMP Sender of the failure".
527: "it's" should be "its".
Schemas: "it's" (in comment blocks) should be "its".
1036: Grammar.
(The above list is not comprehensive; we could use a thorough proofreading
pass to catch errors in grammar and punctuation.)


--Pete
Pete Wenzel <pete@seebeyond.com>
Senior Architect, SeeBeyond
Standards & Product Strategy
+1-626-471-6311 (US-Pacific)