- From: Jonathan Marsh <jmarsh@microsoft.com>
- Date: Thu, 12 May 2005 06:51:47 -0700
- To: <www-ws-desc@w3.org>
- Message-ID: <7DA77BF2392448449D094BCEF67569A50784D020@RED-MSG-30.redmond.corp.microsoft.com>
Charlton's proposed WS-A comments.
________________________________
From: Charlton Barreto [mailto:charlton_b@mac.com]
Sent: Thursday, May 12, 2005 12:10 AM
To: Jonathan Marsh
Subject: LC review of WS-Addressing
Hi Jonathan,
All my comments are editorial (sorry for getting this out so late).
Core
Section 2
- The "EPR" acronym should be introduced in this section, e.g. "...and
syntax of an endpoint reference (EPR)."
Section 2.1
- "A reference may contain a number of individual parameters which are
associated...." Might I recommend that this be changed to, "A reference
may contain a number of individual parameters that are associated...."
- "The metadata embedded in an EPR is not necessarily a complete
statement of the metadata pertaining to the endpoint.Moreover...."
should be changed to have a space between "endpoint." and "Moreover".
- "To deal with conflicts between the embedded metadata of two EPRs, or
between embedded metadata and metadata obtained from a different source,
or to ascertain the current validity of embedded metadata..." should be
changed to, "To deal with conflicts between the embedded metadata of two
EPRs, between embedded metadata and metadata obtained from a different
source, or to ascertain the current validity of embedded metadata...."
Section 2.2
- "...URI "http://example.com/www.fabrikam/acct"..." should be changed
to be consistent with the referenced example - "...URI
"http://example.com/fabrikam/acct"...".
- "This specification provides no concept of endpoint identity and
therefore does not provide any mechanism to determine equality or
inequality of EPRs and does not specify the consequences of their
equality or inequality." Might I suggest this be reworded to read, "This
specification provides no concept of endpoint identity, therefore
providing neither any mechanism to determine equality or inequality of
EPRs, nor specifying the consequences of their equality or inequality."
Section 2.3
- "Other specifications that build on or use WS-Addressing may define a
lifecycle model for endpoint references created according to that
specification." Might I suggest that this be reworded to read, "Other
specifications that build on or use WS-Addressing may define a lifecycle
model for endpoint references created according to their requirements."
Section 2.5
- "When designing endpoint reference extensions designers should
consider whether they desire standard processing per this specification
in cases where their extension is not recogonised or understood." - this
needs to be updated to correctly reference "recognised".
Section 3
- "The basic interaction pattern from which all others are composed is
"one way"." It would be preferable to use "one way" in a manner
consistent with the use of the term for the WSDL 1.1 tranmission
primitive - "One-way".
- "Request Reply" is a common interaction pattern...." Likewise, it
would be preferable to use "Request Reply" in a manner consistent with
the use of the term for the WSDL 1.1 transmission primitive -
"Request-Response".
- "...or to a particular WSDL MEP." Since this spec primarily references
WSDL 1.1 transmission primitives, shouldn't this be consistently worded
as "...or to a particular WSDL transmission primitive or MEP." (to
capture support of WSDL 1.1 and 2.0)?
- In the description for [action], we have "...within a WSDL port type."
Shouldn't this be consistently worded as "...within a WSDL port type or
interface." (to capture support of WSDL 1.1 and 2.0)?
- "A reply message MUST NOT contain more than one [relationship]
property using the predefined reply URI" should have a full stop ("A
reply message MUST NOT contain more than one [relationship] property
using the predefined reply URI.")
Section 3.2
- "EPR's" should actually be referenced as "EPRs" for the sake of
consistency.
SOAP Binding
Section 1
- Line (003) should be formatted to better fit the typically 72-80 char
wide browser window - for example:
(003) <wsa:MessageID>
http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DA
</wsa:MessageID>
Section 2.2
Section 3.2
- Should "...note that extensions to WS-Addressing could be written to
specify different targetting..." be reworded as, "...note that
extensions to WS-Addressing could be written to specify different
targets..."?
- The MAP acronym should be introduced in this section, e.g. "...
message addressing properties (MAP) to SOAP header blocks."
Section 3.4
- In Example 3-2 we should format the <fabrikam:...> elements to display
nicely in the standard 72-80 char wide browser window - for example:
<fabrikam:CustomerKey wsa:IsReferenceParameter='true'>
123456789
</fabrikam:CustomerKey>
<fabrikam:ShoppingCart wsa:IsReferenceParameter='true'>
ABCDEFG
</fabrikam:ShoppingCart>
Section 6
- We should reference "EPR's" as "EPRs" for consistency.
WSDL Binding
Section 2
- The title would better read, "Including WSDL Metadata in endpoint
references," where ERP would be introduced in the following paragraph
as, "An endpoint reference (EPR) metadata section...." In any case,
"EPRs metadata" reads awkwardly. I feel that it would better read as
"EPR metadata".
- "...URI "http://example.com/www.fabrikam/acct"..." should be changed
to be consistent with the referenced example - "...URI
"http://example.com/fabrikam/acct"...".
- In Example 2-1,
wsdli:wsdlLocation="http://example.com/fabrikam
http://example.com/fabrikam.wsdl">
seems to be in error. Should this not be:
wsdli:wsdlLocation="http://example.com/fabrikam.wsdl">
This also appears in Example 2.2.
Section 2.1
- "An NCName that identifies one endpoint amongst the set identified by
by the service name above" should read "An NCName that identifies one
endpoint amongst the set identified by the service name above."
Section 2.2
- "In the case of WSDL 1.1, additional ports may be conveyed by the WSDL
1.1 service definition which are not alternative access channels to the
endpoint." Might I suggest this read, "In the case of WSDL 1.1,
additional ports may be conveyed by the WSDL 1.1 service definition that
are not alternative access channels to the endpoint."
Section 3.1
- "E.g. in the case of the WSDL SOAP/HTTP synchronous binding...." We
should never capitalize "e.g." - it would be preferred to use "For
example, in the case of the WSDL SOAP/HTTP synchronous binding...."
Section 4.1
- "WS-Addressing defines a global attribute, wsaw:Action, that may be
used to explicitly define the value of the [action] property for
messages in a WSDL description." Might I suggest this be changed to
"WS-Addressing defines a global attribute, wsaw:Action, which may be
used to explicitly define the value of the [action] property for
messages in a WSDL description."
- Example 4-1 - the <operation> line should be formatted to better
display on 72-80 char width browsers. For example,
<operation name="GetLastTradePrice"
pattern="http://www.w3.org/2004/08/wsdl/in-out">
Section 5
- We should not refer to WSDL 1.1 "Message Exchange Patterns" given that
in WSDL 1.1. they were referenced as "Transmission Primitives" - the
title may be kept the same but the following sentence should read,
"...transmission primitives and MEPs defined by WSDL 1.1 and WSDL 2.0,
respectively."
Section 5.1
- We should not refer to WSDL 1.1 "Message Exchange Patterns", but WSDL
1.1 "Transmission Primitives". Similarly, the following sentence should
read, "This section describes which of the core message properties are
mandatory or optional for messages in the various transmission
primitives defined by WSDL 1.1."
Section B.2
- "Removed several occurances..." should be changed to, "Removed several
occurrences...."
Received on Thursday, 12 May 2005 13:52:04 UTC