W3C home > Mailing lists > Public > www-ws-desc@w3.org > March 2004

Proposed Resolution for Issue 135

From: Yaron Y. Goland <ygoland@bea.com>
Date: Wed, 10 Mar 2004 10:00:44 -0800
Message-ID: <404F57CC.7080802@bea.com>
To: www-ws-desc@w3.org
In writing a specification one tries to strike a balance between 
readability and reference-ability. WSDL 2.0 has done a good job in 
striking this balance by adopting a structure for section 2 where the 
functional behaviors are described in sections 2.x.1 and infoset/xml 
information is presented in sections 2.x.2 and 2.x.3.

We would propose a small organizational change which we believe will 
make WSDL 2.0's readability better without harming its 
reference-ability. The purpose of this change is to let the reader focus 
on the functional definition of the components in a single section and 
then have a separate section to understand how the functional component 
model is represented in the infoset and XML

Specifically, we propose the following transformation:

Step 1. A new appendix A entitled "Component Model XML/InfoSet Bindings 
  - Normative" should be added. All existing appendix's should have 
their letters bumped up by one.

Step 2. Appendix A should have a hierarchy structure that is identical 
to the 2.x hierarchy structure. E.g. A.1 Definitions, A.2 Interface, etc.

Step 3. All sections 2.x.2 and 2.x.3 should be moved into their 
corresponding A.X and be renumbered A.x.1 and A.x.2.

Step 4. Each 2.x title (e.g. 2.8 Binding) should be deleted and each 
2.x.1 title (e.g. 2.8.1 Binding Component) should be promoted (e.g. 2.8 
Binding Component).

Step 5. At the end of each 2.x section the line "The [Insert Section 
text title here] is represented in XML as:". Following this line the XML 
short form schema definition should be copied from section A.x.1. E.g. 
"The Binding Component is represented in XML as:".

None of the previous applies to sections 2.14 - 2.16.

I realize that step 5 introduces redundant text, the XML definition will 
now appear in two sections. The reason for the redundancy is that I 
think most people will more quickly grasp what's being said if they can 
see the XML pseudo-schema.

I have included a small sample of what section 2.1 would look like after 
the suggested transformation.

	Thanks,

		Yaron




Received on Wednesday, 10 March 2004 13:00:49 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 7 December 2009 10:58:30 GMT