Re: [Fwd: WSDL WG Last Call comments on SAWSDL]

Hi editors,
here's a suggested wording for fixing these editorial issues:

On Tue, 2006-10-24 at 17:53 +0200, Jacek Kopecky wrote:
> -------- Forwarded Message --------
> "In terms of the WSDL 2.0 component model, a model reference is a new
> property. In particular, when used on an element that represents a WSDL 2.0
> Component (e.g. wsdl:interface, wsdl:operation, top-level xsd:element,
> etc.), the modelReference extension attribute introduces an OPTIONAL
> property {model reference} whose value is a set of URIs taken from the value
> of the attribute. The absence of the {model reference} property is equal to
> its presence with an empty value."
> 
> 1) Editorially, it would be nice to refer to WSDL 2.0 Components by name
> instead of by their corresponding element.  Esp. in the case of xsd:*, there
> is both a WSDL component and a Schema component, so by naming an xsd element
> it's not clear which component one might be referring to (the context makes
> it clear in this case, but still, we invented names for components, you
> might as well use them!)  The same style can also apply to the last
> paragraph of section 2.2.

Change the paragraph in 2.1 starting with "In terms of the WSDL 2.0
component model" to

<p>In terms of the WSDL 2.0 component model, a model reference is a new
property. In particular, when used on an element that represents a WSDL
2.0 Component (e.g. a <code>wsdl:interface</code> element representing
an <a href="http://www.w3.org/TR/wsdl20/#Interface">Interface</a>
component, a <code>wsdl:operation</code> element representing an <a
href="http://www.w3.org/TR/wsdl20/#InterfaceOperation">Interface
Operation</a> component, or a top-level <code>xsd:element</code>
representing an <a
href="http://www.w3.org/TR/wsdl20/#component-ElementDeclaration">Element
Declaration</a> component, etc.), the <em>modelReference</em> extension
attribute (with a non-empty value) introduces an OPTIONAL property
{model reference} whose value is the non-empty set of URIs taken from
the value of the attribute. An empty model reference or no model
reference are both reflected by the absence of the {model reference}
property on the given component.</p>

Similarly, change the last para of 2.2 (starting with "When used on")
to:

<p>When used on an element that represents a WSDL 2.0 Component (a
top-level <code>xsd:element</code> element representing an <a
href="http://www.w3.org/TR/wsdl20/#component-ElementDeclaration">Element
Declaration</a> component, an <code>xsd:complexType</code> element or an
<code>xsd:simpleType</code> element representing a <a
href="http://www.w3.org/TR/wsdl20/#component-TypeDefinition">Type
Definition</a> component), the loweringSchemaMapping and
liftingSchemaMapping extension attributes introduce OPTIONAL properties
{lowering schema mapping} and {lifting schema mapping}. The value of
either of these properties is a (possibly empty) set of URIs taken from
the value of the respective attribute. In contrast to the {model
reference} property, the absence of the {lifting schema mapping} and
{lowering schema mapping} properties <em>is different from</em> its
presence with an empty value, as mappings on an element must be able to
override the mappings specified on the type of the element.</p>

> 2) Secondly, there are two ways to interpret the last sentence.  Presumably,
> an empty attribute would result in the presence of an empty {model
> reference} property, which would be _semantically_ equivalent to no {model
> reference} property.   However, it might also be interpreted that in this
> situation the property could simply be omitted from the component model.  We
> had some similar text in places in WSDL that gave us a bit of a headache in
> the interchange format, which requires a canonical component model.
> Basically, two processors that are both SAWSDL aware might have different
> component models - one might omit {model reference} and one might include it
> with an empty value.  This could be dealt with in the comparison algorithm
> between two component models, but we've found it easier to just define a
> single clear mapping from XML to the component model.  In this case, for
> instance, you could state "when non-empty and used on an element..." and
> simply omit the last sentence, or you could state "The absence of the {model
> reference} property is semantically equivalent to its presence with an empty
> value."  The former seems cleaner to me as it doesn't augment the component
> model with meaningless information.

done above, dropped {model reference} in case it'd be empty

> 3) Along the lines of (1), it would be nice to be explicit about the
> components being annotated with properties in section 2.1.x.

I'd suggest adding these small paragraphs to the ends of the 2.1.x
sections:

2.1.1:

A non-empty modelReference on a WSDL interface is represented as {model
reference} property of the Interface component; the case of an empty
modelReference or no modelReference at all is represented with an
Interface component that does not have a {model reference} property.

2.1.2:

A non-empty modelReference on a WSDL interface operation is represented
as {model reference} property of the Interface Operation component; the
case of an empty modelReference or no modelReference at all is
represented with an Interface Operation component that does not have a
{model reference} property.

2.1.3:

A non-empty modelReference on a WSDL interface fault is represented as
{model reference} property of the Interface Fault component; the case of
an empty modelReference or no modelReference at all is represented with
an Interface Fault component that does not have a {model reference}
property.

2.1.4:

A non-empty modelReference on a top-level simple type used in WSDL is
represented as {model reference} property of the Type Definition
component; the case of an empty modelReference or no modelReference at
all is represented with a Type Definition component that does not have a
{model reference} property.

2.1.5:

A non-empty modelReference on a top-level complex type used in WSDL is
represented as {model reference} property of the Type Definition
component; the case of an empty modelReference or no modelReference at
all is represented with a Type Definition component that does not have a
{model reference} property.

2.1.6:

A non-empty modelReference on a top-level element declaration used in
WSDL is represented as {model reference} property of the Element
Declaration component; the case of an empty modelReference or no
modelReference at all is represented with a Element Declaration
component that does not have a {model reference} property.

2.1.7:

A non-empty modelReference on a top-level attribute declaration used in
WSDL is represented as {model reference} property of the Attribute
Declaration component; the case of an empty modelReference or no
modelReference at all is represented with a Attribute Declaration
component that does not have a {model reference} property.



Finally, when we talk about WSDL components (e.g. in 2.1.1 1st para) we
should use the official names, i.e. not italic "interface", but
"Interface", or just talk about the elements. Similarly, WSDL
distinguishes Interface Operation components and Binding Operation
components, even though the elements in XML have the same name.

Hope this helps,

Jacek

Received on Tuesday, 31 October 2006 15:23:35 UTC