Re: Proposed Resolution for Issue 135

Yaron,

why appendix? Why not, say, section 3? (with all sections starting with
the current 3 bumped up) I agree with Amy that the text doesn't belong
in an appendix, but I could see it in a section following the functional
definition section.

On the other hand, I kinda see the drawbacks for implementors, and I
think that the audience that would really benefit from your proposed
changes is already targeted by the primer.

Best regards,

                   Jacek Kopecky

                   Systinet Corporation
                   http://www.systinet.com/




On Wed, 2004-03-10 at 19:00, 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
> 
> 
> 
> ______________________________________________________________________
> 
> 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), 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. 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 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.
>       * 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).
>       * 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)
>       * Zero or more import element information items (see 4.2
>         Importing Descriptions)
>       * 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).
>       * 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).
>       * binding element information items (see 2.8.2 XML
>         Representation of Binding Component).
>       * service element information items (see 2.12.2 XML
>         Representation of Service Component).
>       * 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) and the XML Representation of the
> definitions element information item (see 2.1.2 XML Representation of
> Definitions Component) is described in Table 2-1.
> 
> 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).
> 
> {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).
> 
> {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).
> 
> {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.
>

Received on Thursday, 11 March 2004 10:16:40 UTC