Comments on the v0-1 of the Messaging Service Spec

[David Burdett <david.burdett@commerceone.com>]

Folks

The attached text file contains my comments on v 0-1 of the spec. Comments
that are clearly (IMO) typos I have placed in a separate section other are
losely described as "substantive".

David
 <<Message Svc Spec 01 David B comments.txt>> 

Product Management, CommerceOne
4400 Rosewood Drive 3rd Fl, Bldg 4, Pleasanton, CA 94588, USA
Tel: +1 (925) 520 4422 (also voicemail); Pager: +1 (888) 936 9599 
mailto:david.burdett@commerceone.com; Web: http://www.commerceone.com

David Burdett's comments on version 0-1 of the ebXML Transport Routing & Packaging Message Service Specification.

August 21, 2000

SUBSTANTIVE
===========
General comments
----------------
1. We should use "communication protocol" rather than "transport" or "transport protocol" when we are referring to the likes of HTTP or SMTP. Lines where this applies are: 101, 102, 121, 152, 153, 180, 181, 182, 184, 186, 187 (twice), 189 (twice), 521, 1317, 1327, 1338 (transport level requirement)

2. Envelope vs Container. These are used ambiguously. For example, the diagram on page 7 suggests that the ebXML (header or payload) container and the envelope are the same. However the examples on lines 273-280 (header) and lines 325-332, indicate that the "header" is the MIME header for the mime part. Suggest we add the following definitions after the diagrams on page 7:
   "* An ebXML Header (or Payload) Envelope are the MIME headers that are associated with a MIME part
    * An ebXML Header (or Payload) document is the content of the MIME part and is:
       - an XML document for the ebXML Header, and
       - an XML or some other document for the ebXML Payload
    * An ebXML Header (or Payload) container, is the combination of the ebXML Header (or Payload) envelop and the document it contains"

3. Appendices C & D Why are these included within the spec. I think that they should be removed as it makes the spec shorter and they are non-normative. However I don't think the information should be lost. It should be included in a non-normative "rationale" document that explains how decisions were made for those people who are new to ebXML TRP.

Specific comments
-----------------
L29 Add a footnote to the page after "addressed" that states "The current specification is a working draft. Some of the requirements are note yet supported". If we don't then some people might think that we are addressing everything in this version.

L99 change "encapsulate ebXML" to "encapsulate (package) ebXML" as otherwise need to define what is meant by package on lines 136/7

L111 Remove Service Interface or at least make it optional as Service Interface may be in a separate spec

L143/4 & L147/8. L143 suggests that XML can be case-insensitive which it can't. Also L147, suggests that this applies to the whole spec when it only applies to packaging. Suggest moving these two comments to the start of section 2 after l 149

L145/6 This is isn't a convention, it's more of an explanation. It can't be understood unless you know what is meant by "message structure" which is not explained until section 2 or more particularly "message type" which is not explained until section 3.1

L153 Change "for example" to "specifically" as we only allow MIME

L189 We need to specify exactly how to specify the data communication (aka transport) envelopes for specific protocols

L190/1 Change "Message Envelope" to "ebXML Message Envelope" to make consistent with diagram on page 7

L193 Change "headers" -> "headers that conform to [RFC 2045]" to mandate conformance to the standard

L197/8 Change first sentence to "ContentType SHALL be set to 'multipart/related' on all ebXML Message Envelopes."

L199-201 Only two attributes are defined. Not sure if this is a typo or an omission

L225-7 Following on from General Comment 2 above, change last sentence to read "The ebXMl Heder Envelope container consists of an ebXML Header Envelope and an ebXML Header Document"

L228 Change to "The ebXML Header Envelope conforms to [RFC2045] amd consists of three MIME headers:"

L238 Delete second sentence of this para as it is covered by change to L228 above

L248 It wasn't clear to me what was being referred to by the "encoded" attribute. It needs to be made specific

L249 I think "message structures" is ambiguous. Suggest changing sentence to "version - a value indicating the version of the ebXML Transport, Routing and Packaging Messaging Specification that the structure of the message conforms to"

L251-3 Guidance or rules need to be specified on when the version (or versionless) alternatives should beused

L259+ Optional Support for Signed Header. This whole section strikes me as very woolly and therefore likely to be interpreted differently by implementers. I suggest that we remove this and also the reference to digital signing on L233, pending development of the security spec.

L270 Change "envelope" -> "Container"

L283-289 It is not clear, how it is decided what entries go in the Manifest. I suggest that we replace the second sentence to the end of the paragraph with ... "The ebXML Header Document contains a Message Manifest that identifies the parts of the ebXML Header Document that are present as well as the payload information that is present. See section xxx Message Manifest, for rules on what should exist. If the Message Manifest indicates that a Payload Container is present, then it will consist of an ebXML Payload Envelope and a content portion.

L290 Change to "The ebXML Payload Envelope conforms to [RFC2045] and consists of three MIME headers:

L295 Change both "payloads" to "containers".

L300/1 Remove second sentence as covered by change to L290

L312-321 See comments on Optional Support for Signed Header above.

L323 Change "ebXML Payload envelope" to ebXML Payload Container"

L334+ Message Digest. I think that we should make this stricter to improve interoperability. How about ...
>>>Parties may create a "Message Digest" over a "Domain of Computation" to ensure the integrity of data exchanged using messages that conform to this specification.
The Domain of Computation begins with the first "-" octet of the first boundary following the ebXML Message Envelope. The Domain of Computation ends with the last "-" of the final boundary of an ebXML message.  All octets between and including these begin and end points are Domain of Calculation.
A Message Digest is calculated by applying a [SHA1] or [MD5] hash over the domain of computation and storing the result in xxx.<<<
What isn't clear to me is how the digest should be recorded in an interoperable way. It can't go in the header since this is likely within the domain of computation. Can we put it as an additional attribute in the MIME header?

L356 Change "Message Header" -> "ebXML Header Document" to conform to the diagram on page 7

L357 Change "ebXML Header" -> "ebXML Header Document"

L358 Change "each header" -> "each principal header"

L369-70 Delete last sentence as the reason for this statement (routing headers?) is not explained. If we include it we need to specify the circumstances or reasons why information might be added

L382 Change "transport-specific" -> "messaging service-specific"

L383 Reference to Section 4 is incorrect. Section 4 is now Security Considerations.

L385/6 We don't define what we mean by an application-generate message. Suggest changing definition to "Normal - the ebXML Payload Container contains data that has been provided to the ebXML Messaging Service by the software that called it. For example a business document such as a Purchase Order"

L390 Change definition to "Manifest - lists and identifies the content of the ebXML Header Document and the ebXML Payload Container" - for rationale see reference to line 407+ below.

L391 Header isn't just routing information. Suggest changing to conform to definition on L368-9.

L405 Change "Payload document(s)" -> "ebXML Header Document principal elements and ebXML Payload Container contents"

L406 Change "document" -> "data or information"

L407+ Add section on guidelines for use ...
>>>Document Reference elements MUST created for each principal header element that is not a Manifest or a Header element. It is RECOMMENDED that Document Reference elements are created for each top-level MIME part contained within the ebXML Payload Container. It is an implementation decision of the application or process that is using the ebXML Messaging Service to specify which parte of the ebXML Payload Container are referenced by the Message Manifest".<<<
The rational for this is that knowledge of the existence of, for example, digital signatures, routing headers, etc in the ebXML Header Document is something that the ebXML Messaging Service could usefully discover from the Manifest. Specifying guidelines on what should be referenced in the ebXML Payload Containers should help provide some consistency of use.

L411 Following on from a discussion on email ...
i) Change "DocumentLabel" to "DocumentDescription"
ii) Add new element "DocumentPurpose" that has a definition of ...
>>>"A code that enables the purpose of the referenced document to be determined without retreiving it. Some values for Document Purpose are reserved by the ebXML Messaging Service. These begin with "ebXMLHeader:" and are followed by the name of the principal header element that is present."

L432 TPAInfo - just a place holder that I think changes are required here, that will arise out of work in the TP group that we haven't yet done.

L449 Need to update definition of PartyId to reflect conclusion (?) of the discussion on the list on PartyId - suggest we add a comment that this is under review.

L494 Delete "uniquely". Message Data doesn't uniquely identify a message, Message Id does.

L502 Change 'Not Applicable'" to ' "NotApplicable" (case-sensitive) '

L512+ See recent email suggesting new value of "Delivery Semantics" of "CommunicationProtocol"

L521+ This section should be removed pending completion of the TRP Security spec.

L522 If this section is kept then "Realm Security" needs to be explained. It doesn't mean anything to me.

L527+ References - Need to expand references to include other documents (e.g. [RFC2045].

L527+ (and elsewhere). Need to make the referencing style consistent.

L776++ Appendix B. Suggest removing the detail of the XML documents to make the examples much shorter.

TYPOS
=====
General comments
----------------
1. Add titles to all figures.

2. Use capitals consistently, specifically:
  i) "ebXML header document" -> "ebXML Header Document"
  ii) "ebXML header envelope" -> "ebXML Header Envelope"

Specific comments
----------------
L14+ Arrange authors in alphabetic order

L12 & 16 Add angle brackets

L99-100 replace "ebXML message headers and payloads" by "ebXML payloads" as the message header is covered by this spec

L132-133 Fix indentation

L139 - text missing. Replace by copying text from lines 360-370

L148 Add another bullet point to explain use of italics, e.g. Message Manifest is in italics on Line 284

L156 "Container MUST" -> Container that MUST"

L201 Add an example of a Content-Type attribute

L206 Limit example to just the "type= ..."

L212/3 Limit example to just "boundary= ..."

L214 Move section 2.3.2 on Content-Length to before section 2.3.1 to make consistent with the list on lines 194/5
L284 "is/are" -> "are"

L299 Delete "MIME header  identifies this instance of an ebXML"

L364 Remove line

L366 "to he" -> "to the"

L387 "a" -> "an"