ws-addressing LC review editorial comments

Hi all,

I read the two LC drafts of WS Addressing and below are my editorial
comments (ones that I consider editorial, of course). My more
substantial comments will be sent separately.

Web Services Addressing 1.0 - Core
http://www.w3.org/TR/2005/WD-ws-addr-core-20050331/

1) in example 1-1, I suggest one leading zero in line numbers could be
dropped so it looks better (subjective, admittedly)

2) in table 1-1, namespace with prefix S11 is not necessary as it's not
used in the document

3) paragraph after table 1-1 says the examples are in XML 1.0 but this
is not a requirement, but this seems to be in conflict with the first
editorial note (in status of the document) that states that the use of
XML Schema restricts use of WSA to XML 1.0. These should be reconciled.

4) section 2.1, [metadata] says xsd:any, should say xs:any (drop the
'd')

5) the last two paragraphs describing [metadata] say: "the metadata
embedded in each of the EPRs MAY differ" but I believe the intention is
to say "the metadata embedded in different EPRs with the same [address]
MAY differ"; similarly later "to deal with conflicts between the
embedded metadata of two EPRs, ..." should likely say "to deal with
conflicts between the embedded metadata of two EPRs with the same
[address], ..."

6) last paragraph of 2.1, the reference to 2.4 should probably be in the
form of "(see 2.4 ...)", otherwise it doesn't flow with the sentence
around.

7) section 2.2 says it defines in XML Infoset-based representation and
then it doesn't use infoset terms; it uses "element" instead of "element
information item", for example. This is probably for readability
purposes and it's totally understandable, but it should be mentioned
early in 2.2 that this is the case.

8) Just above example 2-2, the URI
"http://example.com/www.fabrikam/acct" should drop the "www." part that
is inconsistent with the example.

9) in second paragraph after ednote in section 3: "Request Reply" should
probably be "Request/Reply" or "Request-Reply", i.e. with some delimiter
other than a space.

10) at the end of the same paragraph: "a variable number or replies"
should be "a variable number of replies"

11) section 3, description of [action] mentions WSDL port type where it
should probably mention WSDL interface (name changed in WSDL 2)

12) below, the description of [message id] says "a message may be
retransmitted for any purpose including communications failure" but I
don't think a communications failure is a purpose of retransmission.
Instead I'd say "a message may be retransmitted for any reason including
communications failure"

13) in the URI "http://www.w3.org/2005/03/addressing/role/anonymous" I'd
replace "role" with "address" as the rest of the document doesn't
mention roles in any way (the URI is in two places in the doc)

14) in example 3-1, instead of the ellipsis in RelationshipType
attribute value I'd put xs:anyURI, following the style of putting types
where normally one'd have values.

15) I'd rename the attribute RelationshipType to relationshipType as I
believe in W3C specs at least attributes usually start lowercased (even
if element name capitalization is inconsistent in the specs).


Web Services Addressing 1.0 - SOAP Binding
http://www.w3.org/TR/2005/WD-ws-addr-soap-20050331/

16) in example 1-1 I'd drop one leading zero from line numbers

17) section 3.2, last paragraph uses the acronym MAP without previously
introducing it, I suggest adding "(MAPs)" after the "message addressing
properties" earlier in this paragraph or just expanding the MAPs
instead, as it's only used once.

18) in section 5.5: "source should not retransmit" should probably be
"source SHOULD NOT retransmit"

19) I believe the MAY in section 6 ("receiver MAY perform additional
security ... checks") should be lower case, probably same for the SHOULD
earlier in that section, because WS-Addressing doesn't specify any means
of doing these things so it's rather informal here and the normal,
lower-case may and should would be better for readability.

20) in sections 1.2 of both documents, a reference to XML Namespaces has
a space between the link and the closing square bracket: 
"[XML Namespaces ]"



Best regards,

Jacek Kopecky

Received on Tuesday, 3 May 2005 13:19:02 UTC