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


Help: OASIS Mailing Lists Help | MarkMail Help

ebxml-msg message

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

Subject: [ebxml-msg] Comments on 1.09 first half

After a more complete read of the specification, here are my detailed comments on the first half.  The document looks better than I had expected (no offence intended) and is a vast improvement over our 1.0 publication.
Here goes, with line numbers from a print-out of the document with changebars off.  My added comments are in square brackets.  A few comments are "minor technical".  Some of the comments are slightly redundant in light of my recent comments about error handling.
My apologies for any overlaps with (and, likely, different solutions from) Arvola's list.
Section 1
  • 217 s/format type/format or type/

Section 1.1.1

  • 234 s/ebXML SOAP/Basic ebXML SOAP/
  • 236 s/section 2/sections 2 through 6/
  • 239 s/section 4/section 4.1/
  • 246 s/section 8/sections 8 and 9/
  • 247 s/,/(section 10),/
  • 248 s/,/(section 11),/
  • 249 d
  • 251 s/contains [XMLSchema]/contains an XML schema [XMLSchema]/

Section 1.1.2

  • 263-4 d [These lines appear in RFC2119 to generalise beyond a single specification's use of the terms, we're defining only one protocol and don't need this generality.  In fact, it's confusing.  Note: I'm recommending removing only the first two lines stolen from 2119.  This leaves the definitions of the terms alone.]
Section 1.1.4
  • 293 s/its implications on implementation/understand its implications prior to implementation/
  • [Section needs words covering inconsistencies between specification text and our schema.  I believe we decided the schema "wins" but that isn't reflected here.]
Section 1.2
  • 306 s/for Message Servicing//
Section 1.2.1
  • 313 s/security and reliability//
  • 318 s/the ebMS/this document/
Section 1.2.2
  • 339 s/the ebMS/this document/
  • 342, 348 and 349 [For these many references to the old ebXML Requirements document, add that document (back) to the list of references and use "ebREQ" and not "ebRS" as the key to that reference in these lines.  The "ebRS" reference links to the Repository document.]
  • 344 s/the ebMS/this document/
  • 355 s/requirements defined for the MSH/MSH scope/
  • 359 s/intact/securely and intact/
  • 362 s/allows for the destination/allows the next destination/
  • 370 s/needs to/needs of/
  • s/a set of//
Section 1.2.3
  • 393 s/the ebMS MAY/this document may/
  • 398 s/communications configuration/configuration/
  • 400 s/[/(/g
  • s/]/)/g [These aren't references, they're definitions for the acronyms CPP and CPA.]
  • 405 s/discrete instance of a CPA. The/discrete CPA instance.  In [ebCPP], the/
  • 409 s/operations/operation/
Section 1.2.4
  • 417 s/requirements/features/
  • 443 a
Delivery Module -- an abstract service interface an MSH uses to interact with the communication protocol layers when sending and receiving messages.
  • 444 s/Authentication, Authorization and Non-Repudiation services/Security Services (authentication, authorization and non-repudiation)/ [This and other changes attempt to align the document with the preceding list.]
  • s/Header Processing/Header Processing and Parsing/
  • s|Encryption and / or Digital Signatures|Security Services (encryption and / or digital signatures)|
  • [Add Reliable Messaging box between "Message Packaging" and "Delivery Module".  Should also put everything after "Delivery Module" in parentheses.]
Section 1.3
  • 450 s/logical MIME parts/types of MIME parts/
Section 1.3.2
  • 488,499 d [These lines aren't accurate and imply requirements for the 0-payload case we can't enforce.]
  • a
Implementations MUST support receipt of a SOAP message that is not packaged within a MIME multipart/related container as defined in the SOAP 1.1 [SOAP] specification.
Section 1.3.4
  • 556 s/that//g
Section 2.1.1
  • 587 s/: version='1.0'// [Very confusing as it stands.  We don't need to tell people what the XML Recommendation actually requires.]
Section 2.2
  • 602 s/are namespace/is namespace/
  • 603 s/are namespace/is namespace/
  • 605 s/attribute/attributes/
Section 2.2.1
  • 611 [change background to match other URI values called out in the specification]
Section 2.2.2
  • 623 [change background and indentation to match other URI values called out in the specification]
  • 622,623 [move after line 643 because they talk about our schema location, not that of the SOAP extension namespace]
  • 630-631 s/will possibly preclude Receiving MSH implementations from being able to validate messages received./could prevent XML Schema validation of received messages./
  • 631 a
This schema is available at
and SHOULD be referenced in a schemaLocation attribute in the SOAP Envelope element.
  • 644 s/It is RECOMMENDED that use of a separate schemaLocation attribute be used so that/Separate schemaLocation attributes are RECOMMENDED so/
Section 2.2.6
  • 694 s/to provide for/for/
  • 697 a

This extension mechanism is an exclusive choice.  None of the elements defined in this specification support foreign namespace-qualified attributes.  The wildcard elements are provided wherever extensions might be required for private extensions or future expansions to the protocol. [This goes against the current xsi wildcard in the schema for MessageHeader and Manifest which is inconsistent across our extensions and doesn't seem necessary.  At most, we could have an optional xsi:schemaLocation attribute in every ebXML SOAP extension.  I'm also strongly recommending we add wildcard element support to the rest of our SOAP extensions and the Error element.]

Note: Extension elements should be included in ebXML SOAP extensions only when they expand the semantics of that particular element.  This mechanism might be used, for example, to extend the eb:Error element by providing additional structured information about a problem.  Wholly new features should be implemented using separate SOAP extensions.
Section 2.2.8
  • 705-707 d [Duplicates later text.]
  • 712-716 [move prior to line 708]
  • 714 s/MUST be "1.1"/MUST be "1.1" for the syntax and semantics described in this document/ [Otherwise versioning will become impossible.]
Section 2.2.9
  • 718-723 d [Defines SOAP, which shouldn't be necessary in our specification.]
  • OR [much prefer previous option but at least following change would define SOAP properly.]
  • 718 s/REQUIRED SOAP mustUnderstand attribute on SOAP Header extensions/SOAP mustUnderstand attribute/
  • 723 a
For all ebXML SOAP Header extensions defined in this specification, the SOAP mustUnderstand attribute is REQUIRED and MUST have the value '1'.  A compliant MSH MUST parse (but not necessarily support features associated with) all elements and attributes defined in this document.
Section 2.2.10
  • [Defining a new section introducing the soap:actor attribute with the existing 2.2.10 and 2.2.11 becoming and (subsections).  This section does not redefine the SOAP actor attribute (unlike lines 718-723 I'd recommend we delete).]
  • 724 a
2.2.10 SOAP actor attribute
All ebXML SOAP Header extensions defined in this specification that may be handled by an MSH node other than the ultimate recipient of a message allow inclusion of the SOAP actor attribute.  If present, this attribute MUST have one of the values defined in the following two subsections.
  • 725 s/service:nextMSH when used in the context of the/actor:nextMSH/ ["service:" versus "actor:" is consistently incorrect in this document and doesn't reflect our decisions from the face to face.  The motion actually said "actors:" but I could go either way.]
  • 730 a Such an actor MAY ignore SOAP Header extensions targeted to "urn:oasis:names:tc:ebxml-msg:actor:nextMSH" but not the "http://schemas.xmlsoap.org/soap/actor/next" actor (which all SOAP nodes, including an ebXML MSH, MUST adopt).
Section 2.2.11
  • 733 s/service:toPartyMSH when used in the context of the/actor:toPartyMSH/
  • [Technical issue: What is the semantic difference between toPartyMSH and the default SOAP actor?  When would a sending MSH specify toPartyMSH rather than leaving the soap:actor attribute out?  This is not clear in this document and if I need to check the archives for the reasoning we're leaving something important out.
  • I've been told this will support an intermediate node acting on behalf of the To Party in returning an Acknowledgment (prior to the ultimate recipient seeing the message).  That's a great use case, handling (for example) trusted store and forward MSH implementations in the destination's DMZ.  If that's the case, we need to be clear this actor value is specifically for use in the AckRequested and Acknowledgment elements.  I don't think it's useful elsewhere.]
Section 3.1
  • 747 [move left to align bullets]
Section 3.1.1
  • 771 s/section 7, ebXML Reliable Messaging Protocol/section 11.1, Multi-hop Reliable Messaging/
  • 787 s/authorizedRole/authorizedRole/ [This isn't an element in our specification.  Not sure the reference makes sense in any case.]
Section 3.1.2
  • 813 s/then the reliable messaging/the messaging/
  • 815-821 [split into 2 paragraphs one sentence later]
  • 819-821 s/If it chooses to generate an error because of the CPAId/If the CPAId/ [This error shouldn't be optional.]
  • [move these two paragraphs before line 810 since it seems to be specific to case where there's a real CPA instance.]
  • [This discussion does not reflect the decision to REQUIRE an error when a message / CPA consistency problem is detected.]
Section 3.1.3
  • 834 s/schema/scheme/
Section 3.1.4
  • 841-843 d [This discussion just confuses the issue because of its use of the word "role" without reference to the Role element.]
  • 854-855 [Remove second sentence.  It's not possible (or worthwhile) to determine whether or not a URI except by checking for a colon.]
  • [Technical issue: How are unrecognised services (those not mentioned in the BPSS referenced from the CPA for example) handled?  Need to define error handling for that case.]
  • 877 s/unique/globally unique/
  • 878 s/RFC2392/RFC2822/ or s/RFC2392/RFC822/
  • 878 d [As was commented earlier, RFC2392 does not even mention "local part" -- just the name of the local node when describing a common technique for creating globally unique values.  RFC2822 mentions the local part of email addresses but doesn't distinguish between the left and right sides of a message id except with respect to possible generation rules.]
  • 879 [This comment is sensible only with the background of our "where are angle brackets necessary / correct?" discussion.  Please add some context.  Maybe "Note: In the Message-Id and Content-Id MIME headers, values are always surrounded by angle brackets.  However references in mid: or cid: scheme URI's and the MessageId and RefToMessageId elements MUST NOT include these delimiters."]
  • 888 s/messages,/messages (see section 4.2),/
  • 889 s/section 4/section
  • [Technical issue: MUST TimeToLive (like Timestamp) be expressed in UTC?  I'd lean towards yes.]
  • [Technical issue: Should describe clock synchronization between MSH nodes.  Is it required?  Does it not matter because the durations expected are large values?  I would prefer explicit mention of synchronization or clock accuracy as a deployment issue rather than ignoring the issue entirely.]
Section 3.1.9
  • 930,935,938,940 [replace "someType" and similar labels with example values, this is an example]
  • 940 d [Ignore previous comment about this line if you can perform this deletion.  From the service and action values, this is a new order -- what message is referenced?]
Section 3.2
  • 953,954 s/, each of which is described below//
  • 965 s/any namespace-qualified element content belonging to a foreign namespace// [References to 2.2.6 should be consistent in these lists.]
  • 967 s/[XLINK] simple link/XLINK simple link (see [XLINK])/
  • 981,982 d [This disagrees with the schema and would be a unique case in the specification allowing foreign attributes.]
  • [Technical issue: For schema references, should allow a "namespace" attribute.  The location attribute in that case would be a preferred schemaLocation for the described schema.]
Section 3.2.2
  • 1000 d
  • 1001-1002 [move after line 982 because this clarifies use of the xlink:role attribute]
Section 3.2.3
  • 1008-1011 [Technical issue: Error requirements here are overly restrictive.  The problem might be a security failure accessing content elsewhere on the Internet, for example.]
Section 4.1
  • 1040 [move last sentence to end of line 1038 (the previous paragraph)]
  • 1066 s/payload./payload(s).  The MSH takes and active part in providing these security measures, as part of its generation of the SOAP message and through the parameters it passes to the underlying communication protocol./
Section 4.1.3
  • 1078 s/is [XMLC14N]/is described in [XMLC14N]/
  • 1088 s/element (the SOAP Header)// [It's actually the SOAP Envelope but "document" is already clear enough.]
  • 1097 s/ds:Signature element within which it is contained/parent ds:Signature element/
  • 1101 s/service:nextMSH/actor:nextMSH/
  • 1109 s|/>||
  • 1112 s/MAY/can/ [Just listing a few choices.  Neither MAY nor MUST make sense.]
  • 1114 s/an external payload object external/a payload object external/
  • 1121 a
  • 1136 s/service:nextMSH/actor:nextMSH/
  • 1146 s/xmldsigsha1/xmldsig#sha1/
  • 1156 s|blah"|blah/"|
  • 1169-1173 [move before line 1165, making this the first paragraph]
  • 1179 s/element consistent/element list consistent/
  • [Technical issue: This text disallows a receiving MSH returning a message saying "this party definitely received the message with id XYZ".  Since that party likely has the message stored with the sending MSH's signatures, having to say "this party definitely received the message with id XYZ and these contents" seems a burden only some relationships will require.]
  • [Technical issue: Unlike the Manifest element we're defining, the dsig:Signature element is not required to reference every payload in a message.  (Line 1111 says "that requires signing".)  The copying described here is likely insufficient for the and these contents claim you want.]
  • 1183 s/MAY be either in one direction, from the session initiator to the receiver,/may be in one direction/ [The deleted phrase would make the list include 2 of three possible "directions" and exclude the direction mentioned in the example at the end of the paragraph.]
  • 1185 s/[RFC2246]/those described in [RFC2246]/
  • 1188 s/Use of a/A/
  • s/[RFC2246]/those described in [RFC2246]/
  • 1189 s/integrity check CRCs of/digests and comparisons of/
  • 1192 s/document(s)/document/
  • 1198 s|[S/MIME]|those described in [S/MIME]|
  • 1199 s/SHALL/shall/ [This is a requirement for authors of future ebXML-MSH versions.]
  • 1201 s/payload encryption are required by/encryption are required of/
  • [Technical issue: It's not clear how XML Encryption will address this problem except for payloads expressed as XML documents.]
  • 1203 s/Use of a/A/
  • s/[RFC2246]/those described in [RFC2246]/
  • 1208 s/that is//g
  • 1209 s/MAY be used to/MAY/ ["may" might be more appropriate as well]
  • 1210 s/ebXML has a formal liaison to this TC.  There are also many ebXML/There are many ebXML MSH TC/ [The formal relationship between groups mentioned is no longer relevant.  We (ebXML MSH TC) and the SS TC are under the same OASIS umbrella.]
  • 1215 s/Use of a/A/
  • s/[RFC2246]/those described in [RFC2246]/
  • 1217 s/that can be used/and/
  • 1222,1223 s/to provide this capability/in later versions of this specification/
Section 4.2
  • 1230,1233 s/Faults/Fault messages/ [should not pluralize the name of an element]
  • 1240 a Also referred to as an "Error message" elsewhere in this document.
  • 1242 s/to another MSH errors in a message in error/errors to another/
  • 1246 s/section 4/section 4.1/
  • 1248 s/above/above or defined elsewhere/ [list above is not exhaustive]
Section 4.2.2
  • 1253 s/that//
  • 1254 s/that is//
  • 1258 a
a SOAP actor attribute identifying the message originator (see section 2.2.10 for details)
Note: The actor value "urn:oasis:names:tc:ebxml-msg:actor:toPartyMSH" (or the default actor) would most commonly be correct.  If the ebXML SOAP extension in question was qualified with actor="urn:oasis:names:tc:ebxml-msg:actor:nextMSH", that actor would be the appropriate destination for the ErrorList.
  • 1260 a
#wildcard (see section 2.2.6 for details)
[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.  From and To are exempted because they are (conveniently) already name / value pairs.]
  • 1261 s/reported then/reported,/
  • 1263 s/of any of the Error elements/of the grouped Error elements/
  • 1264,1265 s/Error then highestSeverity must be set to Error, otherwise set highestSeverity to/Error, highestSeverity MUST be set to Error; otherwise, highestSeverity MUST be set to/ ["it" would also be fine for the last highestSeverity]
  • 1267 s/the following attributes//
  • 1273 a
#wildcard (see section 2.2.6 for details)
[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]
  • 1274 s/contains an error message/MAY contain error message text/
  • [Technical issue for sections,, (OtherXML description) and (Unknown description): Adding the wildcard, requiring xml:lang when the Error element has content and avoiding mixed content would be greatly simplified if we pushed the textual content of the element and the xml:lang attribute down in to a Description element.  We could even go so far as to use a Description element list though that may be overkill.]
  • 1276 s/REQUIRED// [This attribute has a default and is not required in the schema.]
  • s/errorCodes/errorCode attribute values/
  • 1279 s/errorCodes/errorCode value(s)/
  • 1280 s/Use of non-ebXML values for errorCodes/A codeContext attribute value other than the default/ [We're defining this attribute not the errorCode attribute.]
  • 1281 s/errorCodes/errorCode value(s)/
  • 1280-1282 [Technical issue: Our list of codes is comprehensive due to its inclusion of OtherXML and Unknown.  How can "legal" additions to the list of error codes be created without violating these restrictions?]
  • 1288 s/that although there is an error,//
  • 1288,1289 s/will still/could/
  • 1289 s/way./way in spite of this problem.  (Other Error elements in the list may describe problems preventing further processing.)/
  • 1290 s/that there is/there was/
  • 1293 s/that is in/containing this/
  • a The value of this attribute MUST be a URL.  [Technical issue: Need some text requiring the value of this attribute be a URL.  Otherwise the later discussion doesn't make that much sense.]
  • 1294 s/the element is/the containing document is/
  • 1296-1298 d [Technical issue: This error type is generally not going to be caught by the ebXML handler.  In fact, the text of section 1.3.6 requires a SOAP Fault for this case.  That's why I'm recommending deleting these lines.  If preserved (though corrections to 1.3.6 allowing the ebXML handler to catch some MIME errors), s/in the format cid:23912480wsr, where the text after the ":" is the value of the MIME part's content-id/using URI scheme "cid"/]
  • 1299 s/Content/content/
  • 1302 s/that is//
  • s/that//
  • 1304 s/must/MUST/
  • a This attribute MUST be present unless the Error element is empty.
  • 1305 s/The content of the/The/
  • [move this sentence to the end of line 1303]
  • 1317 s/errorCode element/errorCode attribute/
  • 1321 [Why is this line a note?  Either it should use "must" or it shouldn't be a note.  I'd recommend this comment be normative.]
  • 1326 /NotSupported/ [Need to clarify difference between this ebXML code and SOAP mustUnderstand Fault.]
  • /Inconsistent/ [Need to mention conflicts between message instance and the CPA currently in force.]
  • /OtherXML/ [May need to change if my technical suggestions for result in updates.]
  • 1329 /Unknown/ [May need to change if my technical suggestions for result in updates.]
  • 1333 s/that//
  • 1334 s/that had an error if:/in error.  This is possible when:/
  • 1335 s/section 4/section
  • 1337 a With the possible exception of retries to the message in error, additional messages in the conversation MUST NOT be sent after receiving any message containing such an ErrorList.
  • 1344 s/header SHOULD/header and no ErrorList with highestSeverity set to Error SHOULD/
  • [Technical issue: What does "ignore" mean in the context of HTTP with SyncReply true?]
  • 1354-1356 [Technical issue: Unparsable messages will be caught by the SOAP processor underlying most "layered" MSH implementations.  It's not possible for us to specify the action of that SOAP processor.]
  • 1362 s/if the highestSeverity is set to Error,// [Following up on earlier comments on this section]
  • 1366 d
Section 5
  • [Need lines for the interaction of SyncReply with other elements.  Probably a new section saying "The SyncReply element MAY be present on any outbound message sent using a synchronous communication protocol."]
Section 5.1.4
  • 1379-1380 s/An ErrorList element MUST NOT be present with a StatusRequest element.// [Introduce in section 8.2.3]
  • 1384 d [Introduce in section 8.3.3]
Section 6
  • [Entire section would be better placed as section 4.3.]
  • 1386 s/There are use cases where it is/It may be/
  • 1391 s/In the case where/If/
  • 1393 s/that//
  • s/so that the/and so/
Section 6.1
  • 1398 s/has the following attributes/consists of/
  • 1401 s/SOAP/a SOAP/
  • 1402 [move to left to line up the bullets]
  • a
#wildcard (see section 2.2.6 for details)
[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]
  • 1406-1408 [Technical issue: This seems backwards.  SyncReply s/b allowed if SyncReplyMode is none; if SyncReplyMode is not none, SyncReply MUST be present.]
  • [Technical issue: During the discussion of this addition we agreed to add words about SOAP processors w/o full MSH understanding and their need to forward a like extension.  Those words are missing.  Note: Intermediate MSH nodes MAY forward using a different protocol than the incoming message and are therefore NOT REQUIRED to insert a copy of this element in all cases.]
  • [Technical issue: Should say the SyncReply element is not allowed in a synchronous response message.]

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

Powered by eList eXpress LLC