|
One added point in the first half. The section 4.2.1 is
missing -- we skip from 4.2 Error Handling Module to 4.2.1.1 Definitions.
We should at least have an intermediate heading or (probably easier) make
4.2.1.1 and 4.2.1.2 be 4.2.1 and 4.2.2.
thanx,
doug
----- Original Message -----
Sent: Thursday, 29 November 2001 16:14
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
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 2.2.10.1 and
2.2.10.2 (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/
Section 3.1.1.2
- 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
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.]
Section 3.1.4.1
- 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.]
Section 3.1.6.1
- 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."]
Section 3.1.6.3
- 888 s/messages,/messages (see section 4.2),/
- 889 s/section 4/section 4.2.1.1/
Section 3.1.6.4
- [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.]
Section 3.2.1.1
- [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)]
Section 4.1.2.1
- 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
xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/
http://www.oasis-open.org/committees/ebxml-msg/schema/envelope.xsd"
- 1136 s/service:nextMSH/actor:nextMSH/
- 1146 s/xmldsigsha1/xmldsig#sha1/
- 1156 s|blah"|blah/"|
Section 4.1.4.1
- 1169-1173 [move before line 1165, making this the
first paragraph]
Section 4.1.4.2
- 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.]
Section 4.1.4.3
- 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]/
Section 4.1.4.4
- 1188 s/Use of a/A/
- s/[RFC2246]/those described in
[RFC2246]/
- 1189 s/integrity check CRCs of/digests and
comparisons of/
Section 4.1.4.5
- 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.]
Section 4.1.4.6
- 1203 s/Use of a/A/
- s/[RFC2246]/those described in
[RFC2246]/
Section 4.1.4.7
- 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.]
Section 4.1.4.8
- 1215 s/Use of a/A/
- s/[RFC2246]/those described in
[RFC2246]/
- 1217 s/that can be used/and/
Section 4.1.4.9
- 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]
Section 4.2.1.1
- 1240 a Also referred to as an "Error message"
elsewhere in this document.
Section 4.2.1.2
- 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.
#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,/
Section
4.2.2.1
- 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]
Section
4.2.2.1.1
#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 4.2.2.1.1, 4.2.2.1.6, 4.2.2.3.1 (OtherXML description) and 4.2.2.3.2
(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.]
Section 4.2.2.1.2
- 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?]
Section 4.2.2.1.4
- 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/
Section 4.2.2.1.5
- 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"/]
Section 4.2.2.1.6
- 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]
Section 4.2.2.3
- 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.]
Section 4.2.2.3.1
- 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 4.2.2.1.2 result in updates.]
Section 4.2.2.3.2
- 1329 /Unknown/ [May need to
change if my technical suggestions for 4.2.2.1.2 result in updates.]
Section 4.2.3.1
- 1333 s/that//
- 1334 s/that had an error if:/in error.
This is possible when:/
- 1335 s/section 4/section 4.2.3.2/
- 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.
Section 4.2.3.1.1
- 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?]
Section 4.2.3.2
- 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.]
Section 4.2.3.3
- 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.]
|