Re: Some editorial issues with the Metadata document

On Mon, 2007-01-08 at 11:49 -0500, David Hull wrote:
>     * I believe this has already been done to death, but my $0.02 on
>       table 3-1 is that it's not immediately clear what "REQUIRED"
>       means.  I'd naively  think it meant that the MAPs are required,
>       but that seems redundant in the row marked "yes" for MAPs in input
>       message.  From the subsequent text I gather it means "you have to
>       include the required MAPs."  Since the requirements are clearly
>       spelled out in section 5, perhaps "see section 5", or "as per
>       section 5" or such might be clearer.

The table is mixing several information making it difficult to read.

Here is a proposal, hoping it's better:

Table 3-1. Indicate the presence of MAPs in output messages depending on
the use of the wsdl:required attribute on the wsaw:UsingAddressing
element and the use of the MAPs in the Input message.

     wsdl:required
 MAPs in Input message
MAPs in Output message?
          true
Yes
Yes
          true
No
The endpoint MUST
generate a SOAP Fault.
         false
Yes
Yes
         false
No
Optional. If using SOAP,
MAP headers MUST NOT
have a
soap:mustUnderstand
attribute with a value
of "true"

>     * In the text after the table, we might want to refer back to the
>       place where we defined "WS-A is engaged".  Similarly "this
>       specification" is a bit ambiguous.  I believe we mean either "the
>       rest of the specification (core and SOAP)" or "the whole of WS-A"
>       (including perhaps parts yet to be added on?), and not just the
>       Metadata document.

A proposal:
[[
 If WS-A is engaged, use of the message addressing properties MUST be
fully compliant with this specification; in particular, senders MUST use
all message addressing properties mandated by the Web Services
Addressing 1.0 - Core[WS-Addressing Core], applicable WS-Addressing
protocol bindings (e.g. Web Services Addressing 1.0 - SOAP
Binding[WS-Addressing SOAP Binding]), and this specification, and MUST
follow all applicable WS-Addressing normative requirements.
]]
should read
[[
 If Web Services Addressing 1.0 is used, messages MUST follow the
constraints on message addressing properties defined by Web Services
Addressing 1.0 - Core[WS-Addressing Core]. SOAP 1.1 and SOAP 1.2 MUST
also conform to section 8, Conformance [Web Services Addressing 1.0 -
SOAP Binding [1]].
]]

The Web Services Addressing 1.0 metadata specification doesn't add new
constraints on Web Addressing 1.0 once a SOAP node decided to use Web
Services Addressing. It simply requires or not the use of Web Services
Addressing 1.0.

[1] http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/#conformance


btw, 3.1.1 has a typo: s/wsaw:UsingAddresing/wsaw:UsingAddressing/

Philippe

Received on Monday, 8 January 2007 20:09:47 UTC