RE: Comments on Primer Sections 1 - 3

Hi Arthurs,
 
Thanks for the comments. Please see my response below.
 
Overall I agree with most of your suggestions. If you would like, you
have my permission to check in directly to CVS. 

Best Regards,
Kevin
  

 



  _____  

From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of Arthur Ryman
Sent: Monday, Jun 13, 2005 11:50 AM
To: www-ws-desc@w3.org
Subject: Comments on Primer Sections 1 - 3




1. Section 1.3. I strongly recommend that the primer should not use RFC
2110 keywords. This is too formal. The primer should be informal. There
is no point in repeating formal definitions that appear in Part 1 or 2.
The language should be informal and seay to read. Everyone agrees that
the XML Schema primer [1] is a good example. It does not use RFC 2110. 

[Kevin] we have fixed all the uppercase keywords such as MUST, SHOULD,
etc in the content of the primer. 
 
We should aslo remove the first paragraph in 
 
2. Section 2.2.1. The statement: 

xmlns="http://www.w3.org/2005/05/wsdl" 
This is the XML namespace for WSDL 2.0 itself. Because we have not
defined a prefix for it, any unprefixed elements or attributes are
expected to be WSDL 2.0 elements or attributes (such as the description
element). 


is a little misleading since WSDL 2.0 attributes are unprefixed. Perhaps
restrict this statement to just elements, and mention that attributes
are unprefixed. 

3. Throughout. Sometimes we say WSDL, sometimes WSDL 2.0. Check that all
instances use WSDL 2.0 where appropriate. 

4. Figure 3-1 Infoset diagram. 

-the cardinality of <types> is 0..1, not 0..* 

- in <interface> has extends, not Extends 

- the cardinality of <endpoint> is 1..*, not 0..* 

- in the Note, <description> may not include <feature> or <property> 

5. Section 3.2, the text: 

In other words, the children elements of the description element should
be ordered as follows: 

*	An optional documentation comes first, if present. 

*	then comes zero or more elements from among the following, in
any order: 


*	Zero or more include 

*	Zero or more import 

*	Zero or more extensions 

*	An optional types follows 

*	Zero or more elements from among the following, in any order: 


*	interface elements 

*	binding elements 

*	service elements 

*	Zero or more extensions.


	should be (redunant "Zero or more" eliminated) : 

In other words, the children elements of the description element should
be ordered as follows: 

*	An optional documentation comes first, if present. 

*	then comes zero or more elements from among the following, in
any order: 


*	include 

*	import 

*	extensions 

*	An optional types follows 

*	Zero or more elements from among the following, in any order: 


*	interface elements 

*	binding elements 

*	service elements 

*	extensions.


	6. Section 3.3. The text: 

The WSDL 2.0 component model is particularly helpful in defining the
meaning of import and include. WSDL 2.0 include allows components from
another WSDL 2.0 document having the same targetNamespace to be merged
in with the components of the current WSDL 2.0 document, and is
transitive (i.e., if the included document also includes a WSDL 2.0
document, then those components will also be merged, and so on). WSDL
2.0 import allows components from another WSDL 2.0 document having a
different targetNamespace to be merged in with comonents of the current
WSDL 2.0 document, and is not transitive. 

is not accurate. The behaviour of import and include should not be
described in terms of transitive merging of components. The component
model contains all the components that get referenced, directly or
indirectly from the root WSDL 2.0 document. import is used to declare
that a WSDL document refers to components from another namespace. 

[1] http://www.w3.org/TR/xmlschema-0/ 

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@fido.ca
intranet: http://labweb.torolab.ibm.com/DRY6/