editorial comments for this thursday's call

[christopher ferris <chris.ferris@east.sun.com>]

All,

I've collated all of the editorial comments against v0.92
submitted to date. Please review this carefully and
identify any that:
	- you don't agree to
	- you feel are more correctly classified as
	minor or major technical

During Thursday's call, we'll have 15 minutes of
discussion on these, identify those that are NOT
to be incorporated due to the above and then vote
on them as a "block" change for the next revision
of the MS spec (v0.93).

If you cannot make the call, but still want to
contribute to the discussion, please send to the list
those items that you feel should be excluded from the
"block" edit with a brief rationale.

Thanks!

Chris

Rik Drummond
http://lists.ebxml.org/archives/ebxml-transport/200101/msg00200.html

line 1416: routingheader should be header

Rich Salz
http://lists.ebxml.org/archives/ebxml-transport/200101/msg00182.html

Delete lines 2-7, since it's a duplicate of 91-93 (and internally
contradictory unless "separate document" on line 6 becomes "separately").
As a consequence of this, remove line 8 and renumber accordingly.

Line 20, replace "placed into the body of" with "sent over a"

Line 34, strike "complete".
Line 34, should "requirements" be "semantics"?

Line 39, replace "contains" with "contains a non-normative"

Lines 40-41, need the word "normative" or "non-normative" somewhere.

Lines 46-48.  Use typographic onomotopoeia, putting "Italics" in italics,
etc.

Lines 52-74.  Should be reformatted to more clearly indicate that they
are an excerpt from RFC2119.

Lines 82-92. How do these compare with the documents mentioned in lines
110-116?

Line 84. Change "of the" to "on these"?

Lines 115-116. Change "that includes: ..." to "; the other two are ..."
and strike the last five words.

Lines 121-123. Reword to indicate this is one possible architecture, not
a required architecture.  Consider separating the "applications" and
"interface" boxes, as is done with the transport box -- that would help
emphasize what this particular document is defining.

Line 130ff.  Change "of:" to "of two parts:". Consider capitalizing the
first words of lines 130 and 131 and putting "and" at the end of 131
and 134.

Line 135. replace "an optional, single" with "at most one".

Lines 136-137. Isn't it the actual payload of the "ebXML application"?

Figure at line 138. What is the difference between "ebXML Header Container"
and "ebXML Header Envelope".  Should the latter be in a yellow box
analogous to the "ebXML HEader Document (XML)"?  And the same question
for "Payload" except I assume the color would be baby blue. And, now that
I look at it further, the should the "ebXML Message Envelope" also be
in a box?

Line 141. Remove comma after "standard."  Or remove "standard," altogether.

Line 144 is confusing.  Pragmatically, MIME can carry anything. Is the
intent better expressed by "contents of the payload are up to the user
of the ebXML service"?

Lines 145-146 are confusing. It implies Appendix C only talks about the
Message envelope, when it's already been made clear it addresses ALL
the transport issues.  Consider deleting them.

Lines 147-149. RFC2045 discusses the quoting rules and these lines here
are a little misleading (cf lines 170 and 177 where quotes are mandatory).
Consider deleting them and renumbering accordingly.

Line 158. The trailing semicolon is in error since there are no parameters.

Line 159. Replace "contains" with "MUST contain"

Line 170 appears to use "-" not "=", but it could just be my printer.

Line 177. The colon should be removed.  As at least one other person has
pointed out, the "8760" should be replaced with someone neutral, like
"hashxxxxxxx@ebxml.org"

Line 180. Shouldn't the "SHOULD" be a "MUST"?

Line 186. The trailing semicolon is in error.

Chris Ferris: 
http://lists.ebxml.org/archives/ebxml-transport/200101/msg00175.html

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.

6) 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.

7) line 86 - editorial - insert a reference [EBXMLTASEC] even though the
document has not yet
been published
 
8) 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.

9) 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.

10) line 102 - editorial - suggest we change:
clarity and accuracy of this specification.

to:

clarity, accuracy and efficacy of this specification.

16) line 213 - 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.

17) line 248 - editorial - change 'none' to 'neither'

18) line 261 - 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.

19) line 269 - 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.

20) line 278 - 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:

21) line 296 - 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.

22) line 286 - editorial - extra linefeed in example

Content-ID: ebxmlpayload-123@ebxmlhost.realm --|
ebXML MIME      |

should be:

Content-ID: ebxmlpayload-123@ebxmlhost.realm --|  ebXML MIME      |

23) line 285 - 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.

25) line 330 - editorial - remove <DB> note

28) line 333 - 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).

27) line 346 - 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.

28) line 351 - editorial - remove <DB> note

29) line 358 - editorial - remove <DB> note

30) line 389 - 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

31) line 394 - 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

32) line 396 - 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 508 - 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.

37) line 570 - 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. 

38) line 576 - editorial - remove <DB> note

39) line 590 - editorial - remove <DB> note

40) line 598 - editorial - remove <DB> note. However, we do need to 
double check against the BP specification to ensure
that this is indeed the term that should be used in this context.

42) line 627 - 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.

44) line 645 - editorial - change 'is' to 'MAY be'

46) line 671 - editorial - remove example and defer until end of section

50) line 802 - 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>

51) line 824 - 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.

52) line 858 - editorial - change 'optional' to 'OPTIONAL'.

53) line 873 and 880 - editorial - relocate the attribute definitions
so that they are immediately following their introduction on line 804.

reliableMessagingMethod attribute
intermediateAckRequested attribute

54) line 912 - editorial - remove the second part of the single hop
example. It is overly redundant and possibly confusing.

55) line 981 - editorial - remove this line as it adds no value and
might possibly be confusing.

56) line 991 - editorial - change 'recommended' to 'RECOMMENDED'

58) line 1030 - editorial - need example of StatusData element 

60) line 2172 - 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