- From: Yin Leng Husband <Yin-Leng.Husband@hp.com>
- Date: Wed, 17 Jul 2002 04:41:25 +1000
- To: "'www-ws-arch@w3.org'" <www-ws-arch@w3.org>
As per my action item, these are my comments on all 3 parts of SOAP version 1.2. None of them are specific to WSA viewpoint. The first 8 are non-editorial type. The rest are purely editorial. Comments on SOAP Version 1.2 Part 0: Primer 1. Type: S o 5. Changes between SOAP 1.1 and SOAP 1.2, Additional or changed syntax o Another additional syntax: SOAP 1.2 uses XML Base whereas SOAP 1.1 is silent on it. o Suggest additional bullet: "SOAP 1.2 uses XML Base [15] for determining a base URI for relative URI references whereas SOAP 1.1 is silent about it." Comments on SOAP Version 1.2 Part 1: Messaging Framework 2. Type: S o 2.4 Understanding SOAP Headers, 3rd paragraph, 2nd sentences o "Therefore, for every mandatory SOAP header block targeted to a node, that node MUST either process the header block or not process the SOAP message at all, and instead generate a fault ..." o This sentence implies that there can be at most one detection of a fault caused by processing a header block as all further message processing ceases on fault detection. o However, in various parts of Part 1, there is assumption that multiple misunderstood header blocks may be possibly identified in a fault message, e.g. in 2.6 Processing SOAP Messages, Rule 3: "If one or more of the header blocks identified in the preceding step are not understood by the node ..." o e.g. in 5.4.8 SOAP mustUnderstand Faults, 2nd paragraph, 1st sentence: "A SOAP node MAY generate a SOAP fault for any one or more SOAP header blocks ..." 3. Type: S o 2.4 Understanding SOAP Headers, 3rd paragraph, last sentence o "Tagging SOAP header blocks as mandatory thus assures that such modifications will not be silently (and, presumably, erroneously) ignored by a SOAP node to which the header block is targeted." o This sentence implies that it will not be possible for modifications by mandatory header blocks to be silently and erroneously ignored. o However, in the last 2 sentences of the next paragraph, it is said that "it is not an error for an ultimate SOAP receiver to receive a message containing a mandatory header block that is targeted at a role other than the ones assumed by the ultimate SOAP receiver. This is the case, for example, when a header block has survived erroneously due to a routing or targeting error at a preceding intermediary." o That is, it is not an error for mandatory header block to survive erroneously and therefore be silently ignored, thus contradicting the first sentence quoted. Comments on SOAP Version 1.2 Part 2: Adjuncts 4. Type: Question o 6.2.3 State Machine Description, Table 6, Transition Condition, Init row o If the Transition Condition is "Unconditional", then the boundary between Init state and the Requesting state is indistinguishable. Shouldn't the two states be one state? 5. Type: Question o 6.2.3 State Machine Description, last bullet before 6.2.4 o "A requesting SOAP node MAY enter the Fail state, and thus abort transmission of the outbound SOAP request, based on information contained in an incoming streamed SOAP response". o In this case, should the responding SOAP node switch from generating a SOAP response to a SOAP fault ? Should the requesting SOAP node also generate a SOAP fault since it initated the transmission abortion? 6. Type: Question o 7.5.2.1 Init, Table 20, SOAP Fault, Malformed Request Message row o For Malformed Request Message ( HTTP Status Code 400, HTTP Reason: Bad request) the SOAP Fault is "None". o Why not let the SOAP Fault to be "env:Sender", which is consistent with Table 23? 7. Type: Question o 7.5.2.2 Receiving, Table 23, SOAP Fault to HTTP Status Mapping o What about mapping RPC Faults (see 4.4 RPC Faults) to HTTP Status? E.g. rule 2 in 4.4 defines a fault "env:DataEncodingUnknown" which is not mentioned in Table 23. 8. Type: S o A.1 Rules for mapping application defined names to XML Names, Rule 5, case 4 o "Let U1, U2, ... , U8 be the eight hex digits [PROD: 4] such that Ti is "U+" U1 U2 ... U8 in the UCS-4 encoding." o The "U+" notation denotes the Unicode code point rather than either UCS-2 or UCS-4 encoding. Moreover, "the full range of Unicode code points [are] from U+0000 to U+10FFFF inclusive; code points above U+10FFFF MUST NOT be used". (See Character Model for the World Wide Web 1.0, 3.5 Reference Processing Model.) o Suggest change to: "Let U1, U2, ... , U8 be the eight hex digits [PROD: 4] such that Mi is U1 U2 ... U8 in the UCS-4 encoding." o Suggest also changing "This case implies that Ti has a UCS-2 encoding, which is U+U5U6U7U8." o to: "This case implies that Ti has a UCS-2 encoding, which is U5U6U7U8." --------------------------------------------- Editorial-type comments on SOAP Version 1.2 Part 0: Primer 9. Type: E o 2.2.1 Document-style message exchange, last paragraph, 3rd sentence o "The header block reference with the same value of some of the sub-elements ..." o The header block is reservation, not reference. o Suggest change to: "The header block reservation with the same value of some of the sub-elements ..." 10. Type: E o 2.2.2 Remote procedure calls, 8th paragraphs, last sentence o "(In the typical SOAP/RPC usage with HTTP, the HTTP request URI is often not the resource itself but some intermediate entity which has to evaluate the SOAP message to fully identify the resource.)" o Nit: Should refer to an URI as an identifier (of entity) rather than the entity itself. o Suggest change to: "(In the typical SOAP/RPC usage with HTTP, the HTTP request URI is often not the identifier of the resource itself but that of some intermediate entity which has to evaluate the SOAP message to fully identify the resource.) " 11. Type: E o 2.2.2 Remote procedure calls, two paragraphs before Example 4, last sentence o " We ... draw the reader's attention to section 3.1.3 which provides detailed examples on how to carry RPCs in the HTTP binding where the purpose appear to be ..." o Missing "s" in "appear". o Suggest change to: " We ... draw the reader's attention to section 3.1.3 which provides detailed examples on how to carry RPCs in the HTTP binding where the purpose appears to be ..." 12. Type: E o 2.2.2 Remote procedure calls, paragraph just after Example 4, last sentence o "The latter is also a struct, which takes three elements, the card holder's name, the card number and an expiration date." o The card holder's name needs to be marked-up as <code>. o Suggest change to: "The latter is also a struct, which takes three elements, the card holder's name, the card number and an expiration date." 13. Type: E o 2.2.2 Remote procedure calls, paragraph just before Example 5a, 2nd sentence o "The RPC response is returned in the Body element of a SOAP message, with is modelled as a struct ..." o Typo in "with is modelled". o Suggest change to: "The RPC response is returned in the Body element of a SOAP message, with it modelled as a struct" 14. Type: E o 2.2.2 Remote procedure calls, 2nd paragraph after Example 5b, 3rd sentence o "... thereby making the RPC inependent ..." o Typo in "inependent". o Suggest change to: "... thereby making the RPC independent ..." 15. Type: E o 2.3 Fault scenarios, 2nd paragraph after Example 6, 5th sentence o "The only requirement for such defining application-specific subcode values is ..." o Typo in "such defining"? Meant to be either "defining such" or just "such"? o Suggest change to: "The only requirement for defining such application-specific subcode values is ..." 16. Type: E o 2.3 Fault scenarios, 2nd paragraph after Example 6, 5th sentence o "The only requirement for such defining application-specific subcode values is that they be namespace qualified using any namespace other than the SOAP env namespace which "contain" the "primary" SOAP faults." o It is unclear in what sense the terms "contain" and "primary" mean. Would help if further clarified. o Possible change? : "The only requirement for such defining application-specific subcode values is that they be namespace qualified using any namespace other than the SOAP env namespace which defines the main classifications of SOAP faults." 17. Type: E o 2.3 Fault scenarios, 4th paragraph after Example 6, 2nd sentence o "Errors in processing a Header element is ..." o Change "is" to "are". o Suggest change to: "Errors in processing a Header element are ..." 18. Type: E o 2.4 SOAP processing model, 4th paragraph after Example 7b, 2nd sentence o "In Example 7b, the ultimate recipient of the message - the SOAP processor which plays the "ultimatereceiver" role - must process both the Body as well as the header block aThirdBlock." o As the header block, aThirdBlock, is not a mandatory header block, the above sentence is incorrect in saying that the targeted node (ultimate recipient in this case) must process it. In fact, the previous but one paragraph says that the header block, aThirdBlock, need not be processed: "The other two header blocks are not so marked, which means that SOAP processor at which these blocks are targeted need not process them." o Suggest change to: "In Example 7b, the ultimate recipient of the message - the SOAP processor which plays the "ultimatereceiver" role - must process the Body and may process the header block aThirdBlock." 19. Type: E o 2.4 SOAP processing model, 4th paragraph after Example 7b, 3rd sentence o "It may process the header block anotherBlock, as it is targeted at itself (in the role of "next") ..." o As the ultimate recipient of the message is not the source of the message, and therefore not reflexively targeting it at itself, the reflexive pronoun should not be used here. o Suggest change to: "It may process the header block anotherBlock, as it is targeted at it (in the role of "next") ..." 20. Type: E o 2.4 SOAP processing model, 4th paragraph after Example 7b, last sentence o "If the specification for anotherBlock demanded that it be processed at the ultimate recipient, it would have required that it be marked with a mustUnderstand="true"." o As the header block, anotherBlock, is targeted at "next" node in Example 7b, the above sentence is inconsistent with the example in illustrating use of mustUnderstand with a specification that demanded processing at the ultimate recipient (instead of "next"). o Suggest change to: "If the specification for anotherBlock demanded that it be processed at the next recipient, it would have required that it be marked with a mustUnderstand="true"." 21. Type: E o 2.4 SOAP processing model, 6th paragraph after Example 7b, only sentence o "The following table summarizes how the processing actions for a header block are qualified by the mustUnderstand attribute after a node that has been appropriate targeted (via its role attribute)." o The phrase "after a node" seems to be dangling. o Suggest change to: "The following table summarizes how the processing actions for a header block are qualified by the mustUnderstand attribute with respect to a node that has been appropriate targeted (via its role attribute)." 22. Type: E o 3. Using various protocol bindings, 5th paragraph, last sentence o "a SOAP Response message exchange pattern which consists of a non-SOAP message acting as a response followed by a SOAP message included as a part of the response." o The non-SOAP message is a request, not response. o Suggest change to: "a SOAP Response message exchange pattern which consists of a non-SOAP message acting as a request followed by a SOAP message included as a part of the response." 23. Type: E o 3. Using various protocol bindings, 6th paragraph, 1st sentence o "Part 2 also offers the application designer a general feature called the Web Methods Specification feature that allow ..." o Missing "s" in "allow". o Suggest change to: "Part 2 also offers the application designer a general feature called the Web Methods Specification feature that allows ..." 24. Type: E o 3.1.1 SOAP HTTP GET usage, 2nd paragraph after Example 8b, last sentence o "... an RDF graph describes resources - ... - to other resources (or values) via properties..." o Seems to be missing the word "relationship". o Suggest change to: "... an RDF graph describes resources - ... - and their relationships to other resources (or values) via properties..." 25. Type: E o 3.1.3 Conveying Web-friendly RPCs, 2nd paragraph, last sentence o "(In the typical SOAP/RPC usage scenario, the HTTP request URI is often not the resource itself but some intermediate entity which has to evaluate the SOAP message to identify the resource.)" o Nit: Should refer to an URI as an identifier (of entity) rather than the entity itself. o Suggest change to: "(In the typical SOAP/RPC usage scenario, the HTTP request URI is often not the identifier of the resource itself but that of some intermediate entity which has to evaluate the SOAP message to identify the resource.)" 26. Type: E o 3.1.3 Conveying Web-friendly RPCs, paragraph just before Example 12b, 1st sentence o "Furthermore, in the case that the entire resource may be identified by a URI, and the supplier of the resource can be reassured that a retrieval request is safe, ..." o Nit: The use of passive voice in the above sentence implies that the supplier of the resource does not inherently know whether a retrieval request is safe and has to "be reassured" presumably by a party external to it. Is this really the case? o Suggest change to: "Furthermore, in the case that the entire resource may be identified by a URI, and the supplier of the resource can assure that a retrieval request is safe, ..." 27. Type: E o 3.1.3 Conveying Web-friendly RPCs, paragraph just before Example 13, last sentence o "Note, however, that the all the parameters ..." o Typo: spurious "the". o Suggest change to: "Note, however, that all the parameters ..." 28. Type: E o 5. Changes between SOAP 1.1 and SOAP 1.2, Document structure, 2nd bullet o "SOAP v 1.2 will not spell out the acronym." o Consistency Nit: Extra "v" in this bullet whereas all the other bullets do not have the "v". o Suggest change to: "SOAP 1.2 will not spell out the acronym." --------------------------------------------- Editorial-type comments on SOAP Version 1.2 Part 1: Messaging Framework 29. Type: E o 1. Introduction, 2nd paragraph, 3rd & 4th sentences o "Such features are left to be defined as extensions by other specifications. Such features include but are not limited to "reliability", "security", "correlation", "routing", and the concept of message exchange patterns (MEPs)." o The "concept of message exchange patterns" is defined in SOAP 1.2 and not "left to be defined as extensions by other specifications". o Suggest change to: "Such features are left to be defined as extensions by other specifications. Such features include but are not limited to "reliability", "security", "correlation" and "routing"." 30. Type: E o 1.2 Relation to Other Specifications, 2nd paragraph, 1st bullet o "The SOAP envelope has the namespace name ..." o Consistency Nit: The other bullets refer to the "element information item". o Suggest change to: "The SOAP envelope element information item has the namespace name ..." 31. Type: E o 2.6 Processing SOAP Messages, Rule 4, 2nd sentence. o "A SOAP node MUST process all SOAP header blocks targeted at it." o Confusing if left unqualified. o Suggest change to: "A SOAP node MUST process all SOAP mandatory header blocks targeted at it." 32. Type: E o 2.6 Processing SOAP Messages, Rule 4, 3rd sentence. o "A SOAP node MAY choose to ignore the application level processing specified by non-mandatory SOAP header blocks targeted at it." o Need to explain this first and only occurrence of the term "application level processing". 33. Type: E o 2.6 Processing SOAP Messages, 2nd paragraph, 1st sentence. o "In all cases where a SOAP header block is processed, the SOAP node MUST understand the SOAP header block and MUST do such processing in a manner fully conformant with the specification for that header block." o Nit: This is equivalent to saying that "... the SOAP node must understand the SOAP header block" even if mustUnderstand = 'false'. Suggest omitting this clause as its essence is covered by the following clause. o Suggest change to: "In all cases where a SOAP header block is processed, the SOAP node MUST do such processing in a manner fully conformant with the specification for that header block." 34. Type: E o 2.7.1 Forwarding Intermediaries, 1st paragraph, 1st sentence. o "The semantics of one or more SOAP header blocks in a SOAP message, or the SOAP MEP used MAY require that the SOAP message be forwarded to another SOAP node on behalf of the initiator of the inbound SOAP message." o Nit: This first and only occurrence of the term "initiator" probably needs clarification - SOAP sender or Initial SOAP sender? 35. Type: E o 5.4.2 SOAP Reason Element, 2nd paragraph, 3rd bullet o "An optional attribute information item with a [local name] of lang and [namespace name] of "http://www.w3.org/XML/1998/namespace" (see [8], Language Identification)." o The namespace name of http://www.w3.org/XML/1998/namespace is not referenced at all in [8] or Language Identification. Suggest including a reference to the pertinent section, Namespace Constraint: Prefix Declared, in [7] as well. 36. Type: E o 5.4.3 SOAP Node Element, 3rd paragraph, 3rd sentence o "SOAP nodes that do not act as the ultimate SOAP receiver MUST include this element information item" o Typo: Missing the punctuation mark - full stop (or period). o Suggest change to: "SOAP nodes that do not act as the ultimate SOAP receiver MUST include this element information item." 37. Type: E o 5.4.8 SOAP mustUnderstand Faults, 1st paragraph, 1st sentence o "When a SOAP node generates a fault with a Value of Code set to "env:MustUnderstand" for, it SHOULD ..." o Typo: Spurious "for". o Suggest change to: "When a SOAP node generates a fault with a Value of Code set to "env:MustUnderstand", it SHOULD ..." 38. Type: E o 7.1 SOAP Nodes, 2nd paragraph, 1st sentence o "Similarly, processing a SOAP body might imply the occurrence of side affects ..." o Typo: "effects" instead of "affects". o Suggest change to: "Similarly, processing a SOAP body might imply the occurrence of side effects ..." 39. Type: E o 7.3.1 Binding to Application-Specific Protocols, 1st paragraph, last sentence o "... in order to reuse the existing infrastructure associated that protocol." o Typo: missing word "with". o Suggest change to: "... in order to reuse the existing infrastructure associated with that protocol." --------------------------------------------- Editorial-type comments on SOAP Version 1.2 Part 2: Adjuncts 40. Type: E o 6.2.3 State Machine Description, Table 5, Property Value, reqres:Role o "RespondingSOAPNode Initialized as early as possible during the life cycle the message exchange." o Typo: missing word "of". o Suggest change to: "RespondingSOAPNode Initialized as early as possible during the life cycle of the message exchange." 41. Type: E o 6.3.3 State Machine Description, Table 10, Property Value, reqres:Role o "RespondingSOAPNode Initialized as early as possible during the life cycle the message exchange." o Typo: missing word "of". o Suggest change to: "RespondingSOAPNode Initialized as early as possible during the life cycle of the message exchange." 42. Type: E o 6.3.3 State Machine Description, Table 12, Action, Init row o "Set reqres:ImmediateSender to denote the sender of the request message (if determinable). making an abstraction of the request message available in reqres:InboundMessgae ." o Typo: missing word "Start". o Suggest change to: "Set reqres:ImmediateSender to denote the sender of the request message (if determinable). Start making an abstraction of the request message available in reqres:InboundMessgae ." 43. Type: E o 6.3.3 State Machine Description, paragraph after Table 12, 2nd sentence o "That is, responding SOAP nodes MAY begin transmission of a SOAP response while a SOAP request is still being received and processed." o No SOAP request in this Response MEP o Suggest change to: "That is, responding SOAP nodes MAY begin transmission of a SOAP response while a request is still being received and processed." 44. Type: E o 6.3.3 State Machine Description, paragraph after Table 12, 3rd bullet, 1st sentence o "A requesting SOAP node MAY enter the Fail state, and thus abort transmission of the outbound SOAP request, ..." o No SOAP request in this Response MEP o Suggest change to: "A requesting SOAP node MAY enter the Fail state, and thus abort transmission of the outbound request, ..." 45. Type: E o 7.5.1.3 Sending+Receiving, Table 18, Event/Condition, 1st row o "Request message transmission and response message reception completed and a well formed response message received" o Unclear what a "well formed" response message is (since it need not be an XML 1.0 serialization). 46. Type: E o 7.5.2.1 Init, Table 19, Event/Condition, 1st row o "Receive the beginning of an HTTP POST request containing well formed request message." o Unclear what a "well formed" response message is (since it need not be an XML 1.0 serialization). 47. Type: E o 7.5.2.1 Init, Table 19, Event/Condition, 3rd row o "Receive HTTP GET request containing well formed request message." o Unclear what a "well formed" response message is (since it need not be an XML 1.0 serialization). 48. Type: E o 7.5.2.2 Receiving, Table 21, Event/Condition, 1st row o "The start of an abstraction of a response message becomes available in reqres:OutboundMessage indicating that the local SOAP processor has generating a response message." o Typo: missing word "started". o Suggest change to: "The start of an abstraction of a response message becomes available in reqres:OutboundMessage indicating that the local SOAP processor has started generating a response message." 49. Type: E o 7.5.2.3 Receiving+Sending, sentence before Table 24 o "Table 24 describes the responding SOAP node's Responding state." o Nit: The state being described is "Receiving+Sending", not "Responding". o Suggest change to: "Table 24 describes the responding SOAP node's Receiving+Sending state." 50. Type: E o A.1 Rules for mapping application defined names to XML Names, Rule 5, case 4 o "Let U1, U2, ... , U8 be the eight hex digits [PROD: 4] such that Ti is "U+" U1 U2 ... U8 in the UCS-4 encoding." o Since Ti by definition is a character of the application and not a Unicode character, Mi should be used here. o Suggest change to: "Let U1, U2, ... , U8 be the eight hex digits [PROD: 4] such that Mi is "U+" U1 U2 ... U8 in the UCS-4 encoding." 51. Type: E o B.1 Validating using the minimum schema, 1st paragraph, 1st sentence o "Although W3C XML schemas are conventionally exchanged in the form of schema documents (see [4]), the schema recommendation is build on ..." o Typo: "built" instead of "build". o Suggest change to: "Although W3C XML schemas are conventionally exchanged in the form of schema documents (see [4]), the schema recommendation is built on ..." --------------------------------------------- Yin Leng
Received on Tuesday, 16 July 2002 14:42:14 UTC