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

Re: Proposed Resolution for Issue 135

From: Umit Yalcinalp <umit.yalcinalp@oracle.com>
Date: Wed, 10 Mar 2004 11:09:41 -0800
Message-ID: <404F67F5.1060404@oracle.com>
To: ygoland@bea.com
Cc: www-ws-desc@w3.org


Yaron Y. Goland wrote:

> 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

In principle, I understand what you are trying to accomplish and I am 
all for increasing readability. However,  I fear that the restructuring 
you propose will require one to access the Appendix for each component 
definition we define to see how it is formally specified. As a reader, I 
don't like to look at multiple places to understand the meaning and the 
normative definition of something and your proposal is going to require 
the readers to do exactly that.

Therefore: -1.


--umit



>
>
>
> ------------------------------------------------------------------------
>
>
>   Web Services Description Language (WSDL) Version 2.0 Part 1: Core
>   Language
>
>
>     2. Component Model
>
>
>       2.1 Definitions Component
>
> At the abstract level, the Definitions component is just a container 
> for two categories of component; WSDL components and type system 
> components.
>
> WSDL components are interfaces, bindings and services.
>
> Type system components are element declarations and type definitions 
> drawn from some type system. The former define the [local name], 
> [namespace name], [children] and [attributes] properties of an element 
> information item; the latter define only the [children] and 
> [attributes] properties.
>
> The properties of the Definitions component are as follows:
>
>     * {interfaces} A set of named interface definitions
>     * {bindings} A set of named binding definitions
>     * {services} A set of named service definitions
>     * {element declarations} A set of named element declarations, each
>       one isomorphic to a global element declaration as defined by XML
>       Schema
>
> The set of interfaces/binding/services/etc. available in the 
> Definitions component include those that are defined within the 
> component itself and those that are imported and/or included. Note 
> that at the component model level, there is no distinction between 
> directly defined components vs. imported/included components.
>
> The components directly defined within a single Definitions component 
> are said to belong to the same target namespace. The target namespace 
> therefore groups a set of related component definitions and provides a 
> hint of the intended semantics of the components.
>
> Note:
>
> It is RECOMMENDED that the value of the targetNamespace attribute 
> information item SHOULD be a dereferencible URI and that it resolve to 
> a WSDL document which provides service description information for 
> that namespace.
>
> If the service description is split into multiple documents (which may 
> be combined as needed via 4.1 Including Descriptions 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#includes>), 
> then the targetNamespace attribute information item SHOULD resolve to 
> a master document which includes all the WSDL documents for that 
> namespace. This approach enables the WSDL component designators' 
> fragment identifiers to be properly resolvable.
>
> Imported components have different target namespace values from the 
> Definitions component that is importing them. Thus importing is the 
> mechanism to use components from one namespace in another set of 
> definitions.
>
> Each WSDL or type/element component MUST be uniquely identified by its 
> qualified name. That is, if two distinct components of the same kind 
> (Interface, Binding etc.) are in the same target namespace, then their 
> QNames MUST be unique. However, different kids of components (e.g., an 
> Interface component and a Binding component) MAY have the same QName. 
> Thus, QNames of components must be unique within the space of those 
> components in a given target namespace.
>
> In addition to WSDL components and type and element components, 
> additional extension components MAY be added via extensibility 6. 
> Language Extensibility 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#language-extensibility>. 
> Further, additional properties to WSDL and type/element components MAY 
> also be added via extensibility.
>
> The definitions component is represented in XML as:
>
><definitions
>        
>
>      targetNamespace="xs:anyURI" >
>        
>
>  <documentation />?
>        
>
>  [ <import /> | <include /> ]*
>        
>
>  <types />?
>        
>
>  [ <interface /> | <binding /> | <service /> ]*
>        
>
></definitions>
>        
>
>
>     A. Component Model XML/InfoSet Bindings - Normative
>
>
>       A.1 Definitions
>
>
>         A.1.1 XML Representation of Definitions Component
>
><definitions
>        
>
>      targetNamespace="xs:anyURI" >
>        
>
>  <documentation />?
>        
>
>  [ <import /> | <include /> ]*
>        
>
>  <types />?
>        
>
>  [ <interface /> | <binding /> | <service /> ]*
>        
>
></definitions>
>        
>
> WSDL definitions are represented in XML by one or more WSDL 
> Information Sets (Infosets), that is one or more definitions element 
> information items. A WSDL Infoset contains representations for a 
> collection of WSDL components which share a common target namespace. A 
> WSDL Infoset which contains one or more import element information 
> items 4.2 Importing Descriptions 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#imports> 
> corresponds to a collection with components drawn from multiple target 
> namespaces.
>
> The target namespace represents an unambiguous name for the intended 
> semantics of the WSDL Infoset. The targetNamespace URI SHOULD point to 
> a human or machine processable document that directly or indirectly 
> defines the semantics of the WSDL Infoset.
>
> The definitions element information item has the following Infoset 
> properties:
>
>     * A [local name] of definitions .
>     * A [namespace name] of "http://www.w3.org/@@@@/@@/wsdl".
>     * One or more attribute information items amongst its [attributes]
>       as follows:
>     * A REQUIRED targetNamespace attribute information item as
>       described below in 2.1.2.1 targetNamespace attribute information
>       item
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Definitions_targetnamespace_attribute>.
>     * Zero or more namespace qualified attribute information items.
>       The [namespace name] of such attribute information items MUST
>       NOT be "http://www.w3.org/@@@@/@@/wsdl".
>     * Zero or more element information items amongst its [children],
>       in order as follows:
>     * An OPTIONAL documentation element information item (see 5.
>       Documentation
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#eii-documentation>).
>     * Zero or more element information items from among the following,
>       in any order:
>     * Zero or more include element information items (see 4.1
>       Including Descriptions
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#includes>)
>     * Zero or more import element information items (see 4.2 Importing
>       Descriptions
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#imports>)
>     * Zero or more namespace-qualified element information items. The
>       [namespace name] of such element information items MUST NOT be
>       "http://www.w3.org/@@@@/@@/wsdl".
>     * An OPTIONAL types element information item (see 3. Types
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#eii-types>).
>     * Zero or more element information items from among the following,
>       in any order:
>     * interface element information items (see 2.2.2 XML
>       Representation of Interface Component
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Interface_XMLRep>).
>     * binding element information items (see 2.8.2 XML Representation
>       of Binding Component
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Binding_XMLRep>).
>     * service element information items (see 2.12.2 XML Representation
>       of Service Component
>       <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Service_XMLRep>).
>     * Zero or more namespace-qualified element information items. The
>       [namespace name] of such element information items MUST NOT be
>       "http://www.w3.org/@@@@/@@/wsdl".
>
>
>           A.1.1.1 targetNamespace attribute information item
>
> The targetNamespace attribute information item defines the namespace 
> affiliation of top-level components defined in this definitions 
> element information item. Interfaces, Bindings and Services are 
> top-level components.
>
> The targetNamespace attribute information item has the following 
> Infoset properties:
>
>     * A [local name] of targetNamespace
>     * A [namespace name] which has no value
>
> The type of the targetNamespace attribute information item is xs:anyURI.
>
>
>         A.1.2 Mapping Definitions' XML Representation to Component
>         Properties
>
> The mapping between the properties of the Definitions component (see 
> 2.1.1 The Definitions Component 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Definitions_details>) 
> and the XML Representation of the definitions element information item 
> (see 2.1.2 XML Representation of Definitions Component 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#Definitions_XMLRep>) 
> is described in Table 2-1 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#tab_Definitions_Mapping>.
>
> Table 2-1. Mapping between Definitions Component Properties and XML 
> Representation
>
> Property
>
> 	
>
> Mapping
>
> {interfaces}
>
> 	
>
> The interface definitions corresponding to all the interface element 
> information items in the [children] of the definitions element 
> information item, if any, plus any included or imported interface 
> definitions (see 4. Modularizing WSDL descriptions 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#modularize>).
>
> {bindings}
>
> 	
>
> The binding definitions corresponding to all the binding element 
> information items in the [children] of the definitions element 
> information item, if any, plus any included or imported binding 
> definitions (see 4. Modularizing WSDL descriptions 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#modularize>).
>
> {services}
>
> 	
>
> The service definitions corresponding to all the service element 
> information items in the [children] of the definitions element 
> information item, if any, plus any included or imported service 
> definitions (see 4. Modularizing WSDL descriptions 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20.html#modularize>).
>
> {element declarations}
>
> 	
>
> The element declaration components corresponding to all the element 
> declarations defined as descendants of the types element information 
> item, if any, plus any imported element definitions. At a minimum this 
> will include all the global element declarations defined by XML Schema 
> element element information items. It MAY also include any definition 
> from some other type system which describes the [local name], 
> [namespace name], [attributes] and [children] properties of an element 
> information item.
>

-- 
Umit Yalcinalp                                  
Consulting Member of Technical Staff
ORACLE
Phone: +1 650 607 6154                          
Email: umit.yalcinalp@oracle.com
Received on Wednesday, 10 March 2004 14:10:25 GMT

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