Re: [sca-bindings] WS Binding CD02 rev3

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

OK, I take that as an objection to my
suggestion we handle this as editorial.

Simon N would you mind sending an email
to the list asap to open this issue so we can discuss it on Thursday?

Thanks, Simon

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

Mike Edwards/UK/IBM@IBMGB

15/06/2009 11:55

To	"OASIS Bindings" <sca-bindings@lists.oasis-open.org>
cc
Subject	Re: [sca-bindings] WS Binding CD02 rev3

Folks, 

+1 to the final form of Simon's changes. 

Unfortunately, I think that the removal of a normative statement [BWS20016]
does require an issue. 


This should be a reminder to us *NOT* to use normative statements to declare
whether a particular element or 
attribute is required (1..1) or is optional (0..1).  XSD is perfectly
capable of capturing this aspect and should not 
require anything in the text other than the use of (0..1) or (1..1) as
a marker. 

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
Email:  mike_edwards@uk.ibm.com

From:	Simon Nash <oasis@cjnash.com>
To:	Anish Karmarkar <Anish.Karmarkar@oracle.com>
Cc:	OASIS Bindings <sca-bindings@lists.oasis-open.org>
Date:	11/06/2009 22:44
Subject:	Re: [sca-bindings] WS Binding CD02 rev1

---

Anish,
See comments inline below.

  Simon

Anish Karmarkar wrote:
> Simon Nash wrote:
>> Anish,
>> Here are my comments on the latest draft.
>>
>> 1. The colon following [BWS40005] in section 4.2.2 is not correct
and
>>    should be changed to a period.  Also, [BWS40006]
and [BRS40007]
>>    should not be a bulleted list.
>>
>>    The default transport binding rules are defined in
the previous
>>    bulleted list at the start of section 4.2.2.  This
non-normative
>>    definition is followed by three normative statements
BWS40005,
>>    BWS40006 and BWS40007 that refer back to the previous
definition.
>>    These three normative statements are independent
of each other and
>>    should not be linked together, either by a colon
or by bulleted
>>    indentation.
>>
> 
> Fixed in CD02-rev3 (which isn't posted yet, but will be later).
> 
>> 2. The text for BWS20018 refers to the "semantics of this
>>    attribute".  When reading the standalone
conformance statement in
>>    Appendix B, it isn't clear which attribute is intended.
 This text
>>    should read "semantics of the @wsdli:wsdlLocation
attribute".
>>
> 
> BWS20018 says:
> "The semantics of this attribute are specified in Section 7.1
of WSDL 
> 2.0 [WSDL20]. The value of the @wsdli:wsdlLocation attribute MUST
> identify an existing WSDL 1.1 document."
> 
> Going by our conventions, I don't think the 1st sentence should be
part 
> of BWS20018. I would like to suggest the following:
> Leave the 1st statement as is, but remove it from BWS20018. BWS20018
> would now read --
> "The value of the @wsdli:wsdlLocation attribute MUST identify
an 
> existing WSDL 1.1 document."
> 
> I'll make this change in CD02-rev3, please let me know if you disagree.
> 
This is a step in the right direction, but I think it leads to the
need for further changes in the definition of @wsdli:wsdlLocation.

The change that you are suggesting would produce the following (using
paragraph boundaries to clearly separate normative and non-normative
statements):

 The @wsdli:wsdlLocation attribute MAY be specified by the binding in
 the event that the <WSDL-namespace-URI> in the ‘endpoint’ attribute
 is not dereferencable, or when the intended WSDL document is to be
 found at a different location than the one pointed to by the
 <WSDL-namespace-URI>. [BWS20016]

 If the @wsdli:wsdlLocation attribute is used the @wsdlElement attribute
 MUST also be specified. [BWS20017]

 The semantics of this attribute are specified in Section 7.1 of
 WSDL 2.0 [WSDL20].

 The value of the @wsdli:wsdlLocation attribute MUST identify an
 existing WSDL 1.1 document. [BWS20018]

The ordering of these four statements is ambiguous at best and confusing
at worst.  (Does "this attribute" mean wsdlLocation or wsdlElement?)
A better approach would be to define the meaning of wsdli:wsdlLocation
first, followed by additional rules about its usage in <binding.ws>.
This immplies moving the non-normative sentence earlier, so that it
precedes BWS20017 instead of being sandwiched between BWS20017 and
BWS20018.  The result would be as follows:

 The @wsdli:wsdlLocation attribute MAY be specified by the binding in
 the event that the <WSDL-namespace-URI> in the ‘endpoint’ attribute
 is not dereferencable, or when the intended WSDL document is to be
 found at a different location than the one pointed to by the
 <WSDL-namespace-URI>. [BWS20016]

 The semantics of this attribute are specified in Section 7.1 of
 WSDL 2.0 [WSDL20].

 If the @wsdli:wsdlLocation attribute is used the @wsdlElement attribute
 MUST also be specified. [BWS20017]

 The value of the @wsdli:wsdlLocation attribute MUST identify an
 existing WSDL 1.1 document. [BWS20018]

This is an improvement, but BWS20016 has the problem that it uses MAY
in the way that we decided was incorrect when resolving ASSEMBLY-122
(i.e., to specify a choice for user code rather than an optional
feature for implementations).  So I'd suggest taking the further step
of making the BWS20016 text non-normative, which produces the following:

 The @wsdli:wsdlLocation attribute can be used in the event that
 the <WSDL-namespace-URI> is not dereferenceable, or when the intended
 WSDL document is found at a different location than the one pointed to
 by the <WSDL-namespace-URI>.  The semantics of this attribute
are
 specified in Section 7.1 of WSDL 2.0 [WSDL20].

 If the @wsdli:wsdlLocation attribute is used, the @wsdlElement
 attribute MUST also be specified. [BWS20017]

 The value of the @wsdli:wsdlLocation attribute MUST identify an
 existing WSDL 1.1 document. [BWS20018]

 ***Note that I have made some minor wording and spelling updates to
 the above, including removing the incorrect reference to the
 ‘endpoint’ attribute***

Do you think we could make the above changes editorially, or do we need
an issue?

  Simon

> -Anish
> -- 
> 
>>   Simon
>>
>> Anish Karmarkar wrote:
>>> Created CD02-rev2 by making the ed changes pointed out by
SimonN as 
>>> well as reversed the way the 2119 keyword stmt bookmarks/crossrefs
>>> worked to match that of assembly (was a major PITA to change
it). I 
>>> also did some formating/ed changes and fixed a few refs/crossrefs.
>>> More detailed comments inlined below.
>>>
>>> CD02-rev2 (Word & PDF):
>>> http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/32884/sca-binding-ws-1.1-spec-cd02-rev2.doc
>>>
>>> http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/32885/sca-binding-ws-1.1-spec-cd02-rev2.pdf
>>>
>>>
>>> Diff between CD02-rev1 and CD02-rev2:
>>> http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/32886/sca-binding-ws-1.1-spec-cd02-rev1-rev2-diff.pdf
>>>
>>>
>>> Diff between CD02 and CD02-rev2:
>>> http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/32887/sca-binding-ws-1.1-spec-cd02-rev2-diff.pdf
>>>
>>>
>>> -Anish
>>> -- 
>>>
>>> Simon Nash wrote:
>>>> Anish,
>>>> Thanks for your work on this.  Here are my comments.
>>>>
>>>> Major issue:
>>>>
>>>>  All cross-references for conformance statements
and tags are wrong.
>>>>
>>>>  The bookmark R_BWSxxxxx should be the [BWSxxxxx]
tag in the main
>>>>  chapter text, with a cross-reference in the "Conformance
ID" column
>>>>  of Appendix B.  Instead this bookmark is the
main chapter text
>>>>  describing BWSxxxxx, with a cross-reference in the
"Description"
>>>>  column of Appendix B.
>>>>
>>>>  The bookmark BWSxxxxx should be the text describing
BWSxxxxx in the
>>>>  "Description" column of Appendix B, with
a cross-reference 
>>>> preceding the
>>>>  [BWSxxxxx] tag in the main chapter text.  Instead
this bookmark is the
>>>>  [BWSxxxxx] tag in the "Conformance ID"
column of Appendix B, with a
>>>>  cross-reference following the main chapter text
describing BWSxxxxx.
>>>>
>>>> Editorial comments:
>>>>
>>>>  1. In front matter "Related Work", change
"supercedes" to 
>>>> "supersedes".
>>>>
>>>
>>> Done.
>>>
>>>>  2. In front matter "Abstract", fix typo
"of an SCA composites".
>>>>
>>>
>>> Done.
>>>
>>>>  3. In front matter "Notices" last paragraph,
fix typo "names OASIS 
>>>> is".
>>>>
>>>
>>> Done.
>>>
>>>>  4. In section 1.1, change [[RCF2119]] to [RFC2119].
>>>>
>>>
>>> Done.
>>>
>>>>  5. In section 1.4, use Word cross-reference for
[SCA-Assembly].
>>>>
>>>
>>> Done.
>>>
>>>>  6. In section 2 bulleted list, there are 3 cross-references
to
>>>>     [SCA-Assembly] under /binding.ws/wsdlElement
which should be
>>>>     Word cross-references.
>>>>
>>>
>>> Done.
>>>
>>>>  7. In section 2 bulleted list, /binding.ws/wireFormat
and
>>>>     /binding.ws/operationSelector should be
in bold italic font.
>>>>
>>>
>>> Done.
>>>
>>>>  8. In section 2 bulleted list, cross-references
to [SCA-Assembly]
>>>>     in /binding.ws/wireFormat and /binding.ws/operationSelector
>>>>     should be Word cross-references.
>>>>
>>>
>>> Done.
>>>
>>>>  9. In section 2.3, the Word cross-reference to [SCA-JCAA]
points
>>>>     to [SCA-Policy].
>>>>
>>>
>>> Done.
>>>
>>>> 10. In section 4.1, the cross-reference (R2705) should
use square
>>>>     brackets instead of parentheses.  Also,
it should point to a
>>>>     reference in section 1.2 instead of directly
to a section of
>>>>     http://www.ws-i.org/Profiles/BasicProfile-1.2.html
(which is
>>>>     not one of the documents listed in section
1.2).
>>>>
>>>
>>> Fixed to point to the reference in section 1.2.
>>>
>>>
>>>> 11. In section 4.2.1, conformance statement [BWS40004],
fix
>>>>     typo "from the that interface".
>>>>
>>>
>>> Done.
>>>
>>>> 12. In section 4.2.2, delete the colon after [BWS40005].
>>>>
>>>
>>> Colon is necessary (per the issue resolution).
>>>
>>>> 13. In section 4.2.2, the paragraphs containing conformance
statments
>>>>     [BWS40006] and [BWS40007] should not be
indented.
>>>>
>>>
>>> They have to be indented. It is supposed to be a list. Fixed.
>>>
>>>> 14. In section 4.2.2, conformance statement [BWS40007],
fix
>>>>     typo "structureal".
>>>>
>>>
>>> Done.
>>>
>>>> 15. In section 5.1 first paragraph, add a Word cross-reference
for
>>>>     [SCA-Assembly].
>>>>
>>>
>>> Done.
>>>
>>>> 16. In section 5.1 second paragraph, change [SCA-ASSEMBLY]
to
>>>>     [SCA-Assembly} and add a Word cross-reference.
>>>>
>>>
>>> Done.
>>>
>>>> 17. In section 5.2, change Appendix XXX to Appendix B.
>>>>
>>>
>>> Done.
>>>
>>>> 18. In section 5.2, add Word cross-references for [SCA-Assembly]
and
>>>>     [SCA-Policy].
>>>>
>>>
>>> Done.
>>>
>>>> 19. In conformance statement BWS20005, fix double blank
in
>>>>     "runtime MUST".
>>>>
>>>
>>> Done.
>>>
>>>> 20. In conformance statement BWS20019, fix wrong font
(Verdana
>>>>     instead of Arial) and spurious indentation
in opening paragraph
>>>>     and first two bullets.
>>>>
>>>
>>> Not sure why this was showing up.
>>> Encountered some strange word bug (or lack of word skills).
BWS20019 
>>> now does not have any bullets.
>>>
>>>> 21. In conformance statement BWS20019, third bulleted
item does
>>>>     not have a bullet and is wrongly indented.
>>>>
>>>
>>> See above.
>>>
>>>> 22. In conformance statements BWS20021/22/23/24, fix wrong
font
>>>>     (Verdana instead of Arial).
>>>>
>>>
>>> Fixed.
>>>
>>>> 23. In conformance statement BWS20032, fix wrong font
(Verdana
>>>>     instead of Arial) and spurious indentation.
>>>>
>>>
>>> Fixed.
>>>
>>>> 24. In Appendix D, add the list of contributors.
>>>>
>>>
>>> SimonH: can you provide me a list. This needs to go in all
the 
>>> binding specs.
>>>
>>>>   Simon
>>>>
>>>> Anish Karmarkar wrote:
>>>>> Available at:
>>>>> http://www.oasis-open.org/committees/download.php/32787/sca-binding-ws-1.1-spec-cd02-rev1.doc
>>>>>
>>>>> http://www.oasis-open.org/committees/download.php/32788/sca-binding-ws-1.1-spec-cd02-rev1.pdf
>>>>>
>>>>>
>>>>> I used SimonH's issue 61 rev3 document as the starting
point. CD02 
>>>>> rev1 includes resolutions of all the resolved issues
+ all the 
>>>>> action items against the ws binding editors. Appendix
F contains 
>>>>> the revision history.
>>>>>
>>>>> The front page/footer isn't quite right (links, date,
title etc) 
>>>>> wrt what we need for CD03/PRD and will be changed
before publication.
>>>>>
>>>>> I have also attached the diff version (PDF).
>>>>>
>>>>> -Anish
>>>>> -- 
>>>>>
>>>>>
>>>>> ------------------------------------------------------------------------
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe from this mail list, you must leave
the OASIS TC that
>>>>> generates this mail.  Follow this link to all
your TCs in OASIS at:
>>>>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>>>>
>>>>
>>>
>>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe from this mail list, you must leave the OASIS TC
that
>> generates this mail.  Follow this link to all your TCs in
OASIS at:
>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 
> 



---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU