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