[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [Fwd: comments on v0.92 12 Jan 2001]
-------- Original Message -------- Subject: comments on v0.92 12 Jan 2001 Date: Tue, 16 Jan 2001 11:44:32 -0500 From: Christopher Ferris <chris.ferris@east.sun.com> Organization: Sun Microsystems, Inc. To: Christopher Ferris <chris.ferris@east.sun.com> All, Here are some (lots of!) formal comments on v0.92 dated 12 Jan, 2001. I've numbered each comment, provided line numbers (based on Star Office, no guarantees that they are 100% accurate!) and identified each as editorial, minor or major technical. Cheers, Chris 1) line ?? - editorial - change Gordon Van Huizen's company affiliation from 'Process' to 'Progress' 2) line 2 - editorial - change 'The specification' to 'This specification' 3) line 6 - editorial - suggest we change: It will be included in a later version of this specification or as an additional specification. to: It SHALL either be incorporated into a future version of this specification or referenced as an external specification as deemed most suitable by the ebXML Transport, Routing and Packaging project team. 4) line 15 - minor technical - we may want to define a process for the development and registration of communication protocol bindings for ebXML. If we do, then we should do so before Vancouver. Of course, this will all be relative to what body assumes stewardship of the specification. 5) line 21 - editorial - internal reference to packaging section missing 6) line 41 & 2473 - minor technical - appendix C - communication protocol bindings should be made a normative part of the specification. This would be related to comment #4 above. Without normative protocol bindings, there can be no guarantee of interoperability between services that leverage the same protocol, but differently. 7) line 47 - editorial - suggest that character font treatment be given to each term's font (e.g. 'Bold Italics' be made Bold and Italicized) so that the reader is familiar with what will follow in the specification. 8) line 86 - editorial - insert a reference [EBXMLTASEC] even though the document has not yet been published 9) line 84, 89 and others - editorial - suggest that all references be made ALLCAPS for consistency. e.g. BRA97, EBXMLTP, EBXMLMSREQ. I believe that there are also others throughout the spec. Either that, or remove the 'ebXML' part of the reference and leave it [TP] and [MSREQ]. It just looks funny. 10) line 97 - editorial - suggest we change: The design objectives of this specification are to define a Message Service (MS) to support XML based electronic business between small, medium and large enterprises. to: The design objectives of this specification are to define a wire format and protocol for a Message Service (MS) to support XML based electronic business between small, medium and large enterprises. While the specification has been primarily designed to support XML-based electronic business, the authors of the specification have made every effort to ensure that non-XML business information is fully supported. 11) line 104 - editorial - suggest we change: clarity and accuracy of this specification. to: clarity, accuracy and efficacy of this specification. 12) line 128 - minor technical - proposed description of logical components of MSH are as follows: Header Processing - the creation of the ebXMLHeader document for the ebXML Message uses input from the application, passed through the Message Service Interface, information from the CPA that governs the message, and generated information such as digital signature, timestamps and unique identifiers. Header Parsing - extracting or transforming information from a received ebXMLHeader into a form that is suitable for processing by the MSH implementation. Security Services - digital signature creation and verification, authentication and authorization. These services MAY be used by other components of the MSH including the Header Processing and Header Parsing components. Reliable Messaging Services - handles the delivery and acknowledgment of ebXML Messages sent with deliverySemantics of OnceAndOnlyOnce. The service includes handling for persistence, retry, error notification and acknowledgment of messages requiring reliable delivery. Message Packaging - the final enveloping of an ebXML Message (ebXMLHeader and payload) into its MIME multipart/related container Error Handling - this component handles the reporting of errors encountered during MSH or Application processing of a message as well as processing of received messages that have an ErrorList element detailing an error reported by a foriegn MSH on a message previously sent by the MSH. Notification - I have no idea what this was supposed to be! Message Service Interface - an abstract service interface that applications use to interact with the MSH to send and receive messages and which the MSH uses to interface with applications that handle received messages. 13) line 132 - minor technical - the more I think about this, the more misleading I think this description is. An ebXML Message is, IMHO, JUST the MIME multipart/related object. It does NOT include a communication protocol envelope. That is NOT technically part of the ebXML Message. In addition, at least in my version, there is a Therefore, I would propose the following change: An ebXML Message consists of: - an outer Communication Protocol Envelope, such as HTTP or SMTP, - an inner communication ?protocol independent? ebXML Message Envelope, specified using MIME multipart/related, that contains the two main parts of the Message: - an ebXML Header Container that is used to envelope one ebXML Header Document, - an optional, single ebXML Payload Container that MUST be used to envelope the actual payload (transferred data) of the Message Communication Protocol Envelope (SMTP, HTTP, etc) to: An ebXML Message consists of: - an communication protocol independent ebXML Message Envelope, specified as MIME multipart/related, that contains the two main parts of the Message: - an ebXML Header Container that is used to envelope one ebXML Header Document, - zero or one ebXML Payload Container that MUST be used to envelope the actual payload (transferred data) of the Message NOTE that the last part of the second sub-bullet is an editorial typo... the heading from the graphic somehow got carried over into the bullet that preceded it! At the very least, that should be removed! 14) line 144 - editorial possibly minor technical - I thought that we agreed that 'ebXML Header Envelope' and 'ebXML Payload Envelope' were supposed to be constently labeled 'ebXML Heade Container' and 'ebXML Payload Container' respectively. Secondly, all uses of these labels should be italicized. In addition, I think it is overly confusing to use both terms when they REALLY describe the SAME thing. Proposed change: Identify all occurances of these strings and ensure that ALL are changed to the correct term (ebXML ... Container) and italicized throughout the document. Also NOTE that it makes little difference to me whether we call it envelope or container, just that we pick ONE and use it consistently and that we NOT use BOTH terms when they clearly describe the same thing. 15) line 158 - editorial - remove bullet as it is overly redundant and already mentioned in the supporting text preceding it. 16) line 193 - editorial or minor technical - Here's an example of what I mean by comment 14. Suggest we change: The ebXML Header Container is a MIME body part that MUST consist of: - one ebXML Header Envelope, that contains - one XML ebXML Header document (see section ebXML Header Document). to: The ebXML Header Container is a MIME body part that MUST consist of exactly one ebXML Header document (see section ebXML Header Document). The current version of the doc is WAY too confusing. 17) line 212 - minor technical - have we actually submitted a request for registration of this MIME type? I have never seen evidence that we have. 18) line 218 - editorial - suggest that all version numbers be made Word Fields with a value corresponding to the version of the document so that they don't need to be manually changed with each revision of the spec. 19) line 254 - editorial - change 'none' to 'neither' 20) line 267 - editorial - related to item 14 suggest we change: If an ebXML Payload Container is present, it MUST conform to MIME [RFC2045] and MUST consist of: a MIME header portion - the ebXML Payload Envelope, and a content portion - the payload itself that may be of any valid MIME type. to: If an ebXML Payload Container is present, it MUST conform to MIME [RFC2045] and MUST consist of a single payload MIME object that may be of any valid MIME type including any of the MIME multipart/* types. 21) line 276 - editorial - suggest change: Payloads MAY be a simple-plain-text-object or complex nested multipart objects. This is the implementer?s decision. to: Payloads MAY be a simple-plain-text-object or complex nested multipart objects. The specification of the structure and composition of payload objects is the prerogative of the organization that defines the business process or information exchange that uses the ebXML Message Service. 22) line 284 - editorial - suggest the following be changed: The MIME Content-Type for an ebXML payload is determined by the implementer and is used to identify the type of data contained in the content portion of the ebXML Payload Container. The MIME Content-Type MUST conform to [RFC2045]. For example: to: The MIME Content-Type for an ebXML Payload Container is used to specify the media type and subtype of data in the body of the ebXML Payload Container. The value of this MIME parameter is determined by the organization that defines the business process or information exchange. The value selected SHOULD be chosen from the list of registered MIME media types found at: ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/ The MIME Content-Type MUST conform to [RFC2045]. For example: 23) line 302 - editorial - [MIME] is not listed in the list of normative references. Instead, it is listed under [RFC2045]. Suggest we change this and any other references of [MIME] to [RFC2045] or vice-versa. 24) line 292 - editorial - extra linefeed in example Content-ID: ebxmlpayload-123@ebxmlhost.realm --| ebXML MIME | should be: Content-ID: ebxmlpayload-123@ebxmlhost.realm --| ebXML MIME | 25) line 291 - editorial - suggest that we use 'example.com' for all domainnames listed in our examples. ebxmlhost.realm might be misconstrued as meaningful or as a valid domainname. example.com is (as I understand) reserved for this manner of use, kind of like the '555' exchange is reserved for use in TV shows so that people don't get the urge to dial a number they hear on TV. 26) line 329 and 365 - minor technical - before we release 1.0, we need to research and verify the implications of carrying a DOCTYPE in the body of the ebXMLHeader document. This is especially true now that the XMLSchema for ebXMLHeader is the normative specification and the DTD is being produced for the express purpose of allowing non-schema-aware parsers to process the ebXMLHeader document. Note that because we have chosen our own MIME media type (application/vnd.eb+xml) an implementation can expect that the XML document contained conforms to the DTD or XSD we publish with the specification, and therefore can preload the DTD or XSD into its XML parser as an optimization. The presence of a DOCTYPE is therefore potentially unnecessary. 27) line 337 - editorial - remove <DB> note 28) line 337 - editorial - suggest we change: If both <DB>the encoding declaration and the MIME charset?</DB> are present, the XML prolog for the ebXML Header Document SHALL contain the encoding declaration that SHALL be equivalent to the charset attribute of the MIME Content-Type of the ebXML Message Header Container (see section ebXML Header Container). to: If both the encoding declaration and the MIME charset parameter are present, the XML prolog for the ebXML Header Document SHALL contain an encoding declaration that SHALL be equivalent to the charset attribute of the MIME Content-Type of the ebXML Message Header Container (see section ebXML Header Container). 29) line 353 - editorial - suggest that the example include the MIME Content-Type header with the charset parameter equivalent for the example (UTF-8). Content-Type: application/vnd.eb+xml; version="0.92"; charset="UTF-8"; <?xml version="1.0" encoding="UTF-8"?> This could be added as an alternative example for the explanation in the section. 30) line 358 - editorial - remove <DB> note 31) line 365 - editorial - remove <DB> note 32) line 397 - editorial - suggest we change: ApplicationHeaders - an element that can be used by a process or service to include additional information that needs to be associated with the data in the ebXML Payload but is not contained within it to: ApplicationHeaders - an element that can be used by a process or service to include additional information that needs to be associated with the data in the ebXML Payload that the MSH MUST make available to the application processing the ebXML Payload Container 33) line 402 - editorial - suggest we change: an element that contains a list of the errors that have been found in a message to: an element that contains a list of the errors that are being reported against a previous message 34) line 404 - editorial - suggest we change: Acknowledgment - an element that is used by a MSH to indicate that a message has been received to: Acknowledgment - an element that is used by a receiving MSH to acknowledge to the sending MSH that a previous message has been received 35) line 423 - minor technical - I fail to see why ApplicationHeaders is NOT allowed when there is an ErrorList that has a highestSeverity of Error. I would suggest that the only case where ApplicationHeaders is NOT allowed is when there is a StatusData element because the StatusData is a MSH to MSH message and there is no "application" involvement. 36) line 431 - minor technical - I fail to see why a StatusData element could not be accompanied by an ErrorList element, regardless of severity. Suppose the message being queried had errors but the message reporting the errors was never received? 37) line 473 - editorial - missing period 38) line 530 - editorial - suggested change: The designer of the protocol or application that is using ebXML Messaging decides what payload data is referenced by the Manifest and the values to be used for xlink:role. to: The designer of the business proces or information exchange that is using ebXML Messaging decides what payload data is referenced by the Manifest and the values to be used for xlink:role. 39) line 567 - minor technical - suggest we remove the ID attribute from Header element. An ID is not much use when there is only a single element matching that type in a document because there is no need to distinguish between like elements. 40) line 584 - editorial - fix whitespace in example: <From> <PartyId type="urn:duns.com">1234567890123</PartyId> <From> <To> <PartyId>smtp:joe@example.com</PartyId> </To> 41) line 593 - editorial - suggest we change: CPAId element The REQUIRED CPAId element is a string that identifies the Collaboration Protocol Agreement (CPA) that governs the processing of the message. It MUST be an identifier that is unique within the combination of the From and To Parties. CPAId element The REQUIRED CPAId element is a string that identifies the Collaboration Protocol Agreement (CPA) that governs the processing of the message. It MUST be an identifier that is unique within the domain of the names chosen by the Parties. 42) line 600 - editorial - remove <DB> note 43) line 615 - editorial - remove <DB> note 44) line 623 - editorial - need to double check against the BP specification to ensure that this is indeed the term that should be used in this context. 45) line 626 - minor technical - the Service/@type attribute is missing from the XSD schema. This begs the question, is the type attribute an uriReference or is is a string? 46) line 654 - editorial - remove <DB> note. This issue should be taken up based on Andrew's comments regarding the various uses of xsd:timeInstant in the schema. 47) line 655 - minor technical - Status messages use the RefToMessageId don't they? 48) line 671 - editorial - change 'is' to 'MAY be' 49) line 673 - minor technical - there are a number of problems with this section. Some of the errors are editorial in nature (e.g. use of term 'element' instead of 'attribute'. There are also some technical issues at play including the confusion of the use of the term default. The description also erroneously describes BestEffort as "unspecified", which is wrong. Finally, I take great exception with the notion that the CPA may be overridden. The CPA constitutes an AGREEMENT between the two parties. In the case of deliverySemantics and reliable messaging, you cannot willy-nilly change the agreed upon behavior. The receiving party may NOT be capable of adapting to the different deliverySemantics that were agreed upon. Let us not make this specification any more comlicated than it needs to be. Suggest we change: deliverySemantics attribute The deliverySemantics element, if present, over-rides the value of the same parameter in the CPA. If it is not present, the value in the CPA MUST be used. The deliverySemantics parameter/element MUST used by the From Party MSH to indicate whether the Message must be sent reliably. Valid Values are: OnceAndOnlyOnce. The message must be sent using a reliableMessagingMethod that will result in the application or other process at the To Party receiving the message once and only once BestEffort The reliable delivery semantics are not specified. In this case the value of reliableMessagingMethod is ignored. The default value for deliverySemantics is specified in the CPA. If no value is specified in the CPA then the default value is BestEffort. If deliverySemantics is set to OnceAndOnlyOnce then the From Party MSH and the To Party MSH must adopt the Reliable Messaging behavior (see section Reliable Messaging) that describes how messages are resent in the case of failure and duplicates are ignored. If deliverySemantics is set to BestEffort then a MSH that received a message that it is unable to deliver MUST NOT take any action to recover or otherwise notify anyone of the problem, and the MSH that sent the message must not attempt to recover from any failure. This means that duplicate messages might be delivered to an application and persistent storage of messages is not required. If the To Party is unable to support the type of Delivery Semantics requested, then the To Party SHOULD report the error to the From Party using an ErrorCode of NotSupported and a Severity of Error. to: deliverySemantics attribute The deliverySemantics attribute is an enumeration of the following possible values: OnceAndOnlyOnce BestEffort (default value) The deliverySemantics parameter/element MUST used by the From Party MSH to indicate whether the Message be processed using Reliable Messaging as defined in this specification. The value for deliverySemantics is specified in the CPA that governs the processing of the message. If no value is specified in the CPA then the default value of BestEffort MUST be used. Refer to the section on Reliable Messaging for a detailed discussion on the REQUIRED and suggested handling of messages with this attribute. 50) line 697 - editorial - remove example and defer until end of section 51) line 698 - editorial and minor technical - as with the previous attribute, the deliveryReceiptRequested attribute has both editorial and minor technical issues. Propose we change: DeliveryReceiptRequested attribute The deliveryReceiptRequested element, if present, over-rides the value of the same parameter in the CPA. If not present then the value in the CPA MUST be used. The deliveryReceiptRequested parameter/element MUST be used by a From Party MSH to indicate whether a message received by the To Party MSH should result in the To Party MSH returning an acknowledgment message containing an Acknowledgment element with a type of deliveryReceipt. The deliveryReceiptRequested parameter/element is frequently used to help implement Reliable Messaging (see section Reliable Messaging) although it can be used independently. Before setting the value of deliveryReceiptRequested, the From Party SHOULD check the deliveryReceiptSupported parameter for the To Party in the CPA to make sure that its value is compatible. Valid values for deliveryReceiptRequested are: Unsigned - requests that an unsigned Delivery Receipt is requested Signed - requests that a signed Delivery Receipt is requested, or None - indicates that no Delivery Receipt is requested. When a To Party MSH receives a message with deliveryReceiptRequested not set to None then it should check if it is able to support the type of Delivery Receipt requested. If the To Party MSH can produce the Delivery Receipt of the type requested, then it MUST return to the From Party on the message just received, a message containing an Acknowledgment element with the value of the type attribute set to DeliveryReceipt. If the To Party cannot return a Delivery Receipt of the type requested then it MUST report the error to the From Party using an ErrorCode of NotSupported and a Severity of Error. to: deliveryReceiptRequested attribute The deliveryReceiptRequested attribute is an enumeration of the following possible values: Signed UnSigned None (default) The value of the deliveryReceiptRequested attribute is determined by the CPA that governs the processing of the message. If no value is specified in the CPA, then the default value of 'None' MUST be used. Refer to the section on Reliable Messaging for a detailed discussion on the REQUIRED and suggested handling of messages with this attribute. 52) line 721 - minor technical - this attribute troubles me. How is an intermediary expected to handle it? The whole issue of synchronous replies and reliable messaging is troubling to be perfectly honest. 53) line 730 - minor technical - It isn't at all clear to me why this attribute is present in the QualityOfServiceInfo element. It would seem to me that if anything, this should be an element and it should be included in MessageData. IMHO, TTL has nothing to do with reliable messaging or quality of service. I could easily see TTL applying to a message that is delivered with BestEffort deliverySemantics. I would propose that we adopt the following changed description and insert it in the MessageData section following 5.4.6.2: TimeToLive element The TimeToLive element indicates the time by which a message should be delivered to and processed by the To Party. In this context the TimeToLive has expired if the time of the internal clock of the MSH that receives a message is greater than the value of TimeToLive for the Message. If TimeToLive is not present then it MUST be assumed that TimeToLive is infinite and therefore checks for message expiry are unnecessary. When setting a value for TimeToLive it is RECOMMENDED that the From Party takes into account the accuracy of its own internal clocks as well as the mshTimeAccuracy parameter for the Receiver MSH (see section MSH Time Accuracy) that indicates the accuracy to which a MSH will keep its internal clocks. How a MSH ensures that its internal clocks are kept sufficiently accurate is an implementation decision. If the To Party's MSH receives a Message where TimeToLive has expired, it SHALL send a Message to the From Party MSH, reporting that the TimeToLive of the message has expired. This Message SHALL be comprised of: - a Payload that consists of the ebXML Message that expired - an ErrorList containing an Error that has the errorCode attribute set to TimeToLiveExpired, and the severity attribute set to Error. 54) line 751 - editorial - change 'is' to 'MAY be' 55) line 780 - editorial - suggest that the example not make use of default values. I propose substitution of the example with the following: <Header id="N01"> <From>?</From> <To type="userType">...</To> <CPAId>http://www.ebxml.org/cpa/123456</CPAId> <ConversationId>987654321</ConversationId> <Service type="myservicetypes">QuoteToCollect</Service> <Action>NewPurchaseOrder</Action> <MessageData> <MessageId>UUID-2</MessageId> <Timestamp>20000725T121905.000Z</Timestamp> <RefToMessageId>UUID-1</RefToMessageId> </MessageData> <QualityOfServiceInfo deliverySemantics="OnceAndOnlyOnce" deliveryReceiptRequested="Signed"/> </Header> 56) line 792 - editorial - suggest we change: The RoutingHeader element contains information about a single transmission of a message between two Parties. If a message traverses multiple hops by passing through some type of intermediate system between the From Party and the To Party, then each transmission over each hop results in the addition of a new Routing Header element. to: The RoutingHeader element contains information about a single transmission of a message between two MSH nodes. If a message traverses multiple hops by passing through one or more intermediate MSH nodes as it travels between the From Party MSH and the To Party MSH, then each transmission over each successive "hop" results in the addition of a new Routing Header element. 57) line 825 - editorial - change 'optional' to 'OPTIONAL'. 58) line 840 and 847 - editorial - relocate the attribute definitions so that they are immediately following their introduction on line 804. reliableMessagingMethod attribute intermediateAckRequested attribute 59) line 880 - editorial - remove the second part of the single hop example. It is overly redundant and possibly confusing. 60) line 949 - editorial - remove this line as it adds no value and might possibly be confusing. 61) line 959 - editorial - change 'recommended' to 'RECOMMENDED' 62) line 960 - minor technical - I am inclined to agree with sentiments that have been expressed by some that the mustUnderstand attribute on the ApplicationHeaders element should probably be removed. Instead, we should simply RECOMMEND that the global mustUnderstand attribute has been provided to enable the sender of ApplicationHeaders content to inform the receiving party's application or application services layer whether understanding of the namespace qualified content is REQUIRED. My initial thought regarding handling of mustUnderstand on the ApplicationHeaders element was to inform the MSH as to whether or not it had to support the ability to pass ApplicationHeaders content to the "application" that services the message received. I now believe that we simply should REQUIRE that this functionality be supported in an MSH and leave the mustUnderstand to the namespace qualified element content. If we do adopt my proposal to remove mustUnderstand from this element, then delete lines 960-967. In addition, the example would need to be adjusted accordingly. If not, then the following change is recommended: The ApplicationHeaders element has a single attribute called mustUnderstand. This attribute has two possible values true and false. The default value for the mustUnderstand attribute is false. An ApplicationHeaders element that has a mustUnderstand set to a value of true means that a receiving MSH MUST be capable of understanding the meaning of the namespace-qualified element content. If the content is not understood, the receiving MSH MUST respond with a message that includes an errorCode of NotSupported in an Error element as defined in section ErrorList Element. to: The ApplicationHeaders element has a single attribute called mustUnderstand. This attribute has two possible values; true and false. The default value for the mustUnderstand attribute is false. An ApplicationHeaders element that has a mustUnderstand set to a value of true means that the application that services the message MUST be capable of understanding the meaning of the namespace-qualified element content. If the content is not understood, the receiving application MUST respond with a message that includes an Error element that has an errorCode of NotSupported and an errorSeverity of Error as defined in section ErrorList Element. 63) line 1000 - editorial - need example of StatusData element 64) line 1152 - minor technical - OOPS! I didn't see this TBD;-) Here's the proposed text for the Signature element definition: An ebXML Message MAY be digitally signed to provide security countermeasures. Zero or more Signature elements, belonging to the [XMLDSIG] defined namespace MAY be present in an ebXMLHeader. The Signature element MUST be namespace qualified in accordance with [XMLDSIG]. The structure and content of the Signature element MUST conform to the [XMLDSIG] specification. If there are more than one Signature elements contained within the ebXMLHeader, the first MUST represent the digital signature of the ebXML Message as signed by the From Party MSH in conformance with the section Security. Additional Signature elements MAY be present, but their purpose is undefined by this specification. Refer to section Security for a detailed discussion on how to construct the Signature element when digitally signing an ebXML Message. 65) line 2167 - editorial - the version of the schema in v,0.92 is NOT accurate. It is the version 0.91 schema. It should be removed and a reference to an external link should be put in its place. I propose that the URL be: http://www.ebxml.org/project_teams/transport/ebxmlHeader,v<version>.xsd
begin:vcard n:Ferris;Christopher tel;work:781-442-3063 x-mozilla-html:FALSE org:Sun Microsystems, Inc;XML Technology Development adr:;;One Network Drive;Burlington;Ma;01824-0903;USA version:2.1 email;internet:chris.ferris@east.Sun.COM title:Sr. Staff Engineer x-mozilla-cpt:;0 fn:Christopher Ferris end:vcard
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC