WSDL 2.0 LC Comments

WSD WG, below are comments from myself and my colleagues re: the WSDL
2.0 Last Call drafts dated 2004-08-03. We realize that these comments
are late, but respectfully ask that you consider them carefully.

--Jeff

-----
Section 2.3: Fault declarations should be moved down into
interface/operation, and not be defined as first-class components of
interface.  Fault references ought to work as message references do:

* The following argument from Section 2.3.1 applies equally well to
messages.  Why aren't they treated consistently?  "The Interface Fault
component provides a clear mechanism to name and describe the set of
faults an interface may generate.  This allows operations to easily
identify the individual faults they may generate by name.  This
mechanism allows the ready identification of the same fault occurring
across multiple operations and referenced in multiple bindings as well
as reducing duplication of description for an individual fault."

* Interface Fault Components are not globally reusable.  The solution is
half-baked.

* Interface Fault Components do not provide any practical re-use.  The
99% case just renames @element.

* Interface Fault Components are awkward because they cannot be bound
within the context of an operation, preventing, for example, the
assignment of a different reason string to the 'same' fault within
different operations.  Making these 'error messages' clear for debugging
scenarios will require creating Interface Fault Components that are
otherwise identical.

* It would be much cleaner if the Interface Operation and Binding
Operation components had parallel properties.  As it is, only one has
{fault references}.

-----
Section 2.3.1 states: "Interface Fault components are local to Interface
components; they cannot be referred to by QName..."  However, Section
2.6.3 states that "{fault reference}" is "the actual value of the ref
attribute information item", an xs:QName.  Please make this consistent
here and for the other components throughout the document which have
this inconsistency.

-----
Section 2.4.1 defines a {safety} property and a corresponding safe
attribute.  These constructs should be removed.  Tooling can't analyze
developer code for the purpose of automatically setting the safe
attribute, so by default "safety" will be set to false.  We expect
developers to have little incentive to set the safety property manually,
and even when they do we are not convinced they will be able to do so
correctly.  In addition it's not clear why safety is singled out as the
only semantic declaration worthy of inclusion in the WSDL core.

-----
Section 2.4.2 states: "If elements with the same qualified name appear
as children of both the input and output elements, then they MUST both
be declared using the same type."  Does this imply that an explicit type
must be declared for all child elements?  If so it should be stated
explicitly.

-----
Section 2.4.2 RPC Style defines an extension for use in the {style}
property (see section 2.4.1.1).  As an extension this should be moved to
Part 2.

-----
Section 2.4.2 RPC Style is unclear as to whether local element children
may contain extension attributes.  Such attributes should be explicitly
allowed; for instance as identifiers to enable the element to be signed
(xml:id, wsu:Id).

-----
Section 2.4.2 RPC Style does not appear to allow element wildcards.
Such wildcards are necessary to enable versioning.

-----
Section 2.4.2.1 allows multiple returns.  Why?  Is the expectation that
one would generate an (anonymous?) struct to hold the result?  We'd
prefer that the signature was restricted to a single return.
 
-----
Section 2.4.3 states: "At least one of the [children] MUST be an input,
output, infault, or outfault element information item."  Allowing an
operation to only have an infault or outfault child doesn't make sense.
Suggest removing infault and outfault from this list.

-----
Section 2.4.3.3 says that the safe attribute has no default value, yet
Table 2-5 says the {safety} property does.  While this is not in direct
conflict, it could be clearer that the first case is talking about an
attribute default, and the second is not really a default at all, but a
guaranteed result of the transformation from Infoset to the Component
Model.  There may be similar occurrences of the word "default" in
relation to the component model elsewhere in the spec.

-----
Section 2.5.1 Message Reference Component allows message content models
to consist of any single element, any named element, or none.  The
restriction of messages to a single element child is not derived from
SOAP 1.1 or SOAP 1.2.  Multiple element children is a type of message
exchange currently in use.  (Microsoft supports this in ASMX.)  We
request the facility to specify a sequence of named or unnamed elements
to enable WSDL to be used to describe such message exchanges.

-----
Table 2-6 and Table 2-7 specify that an error results if the
messageLabel attribute doesn't match the MEP.  However Table 2-13
suggests it's not an error if the messageLabel attribute doesn't match
the MEP.  It's not clear whether there is a reason for these to be
inconsistent.  Please make it an error throughout the spec if the
messageLabel does not match the MEP.

-----
Table 2-12 says the {operation reference} is the actual value of the ref
attribute.  However, the {operation reference} property is earlier
defined (2.11.1) to be an Interface Operation Component.  Furthermore
Section 2.4.1 states that Interface Operation Components cannot be
referred to unambiguously by QName, which is not reflected in the
mapping in Table 2-12.  Please make these sections consistent.

-----
Section 2.13: Service Components implement a single interface.  This
change from WSDL 1.1 impacts tooling negatively.  Tooling exists for
WSDL 1.1 that serializes a single service element with ports bound to
more than one portType.  There may also be tooling that serializes
multiple service elements to separate ports on some basis other than
whether they implement the same portType.  A service serializing its
description as multiple service elements (as this change requires)
forces it and its client implementations to add an additional layer of
identification to equate the service element QNames.

-----
Table 2-13 implies there may not be any endpoints in a service (it says
"if any").  However Section 2.13.2 states that there are always "one or
more endpoint[s]".  The "if any" thus appears to be in error and should
be removed.

-----
Section 2.14 builds the address into the WSDL core rather than
expressing it through a binding-specific extension (as in WSDL 1.1).
This also constrains address to a URI.  We expect bindings that require
alternate forms of address (e.g., WS-Addressing Endpoint Reference).

-----
Section 2.15: Support for versions of XML other than XML 1.0 complicates
the spec substantially without providing corresponding benefits in
interoperability.  Until a version of XML Schema that provides
facilities for handling XML 1.1 is developed and deployed there is
little real utility in building support for XML 1.1 into WSDL.  The
introduction of new simple types for schema in section 2.15 should be
removed completely, and references to these types should revert to the
corresponding XML Schema 1.0 types.  Section 2 can likewise be greatly
simplified.

-----
Section 3 states: "Note: Support for the W3C XML Schema Description
Language [XML Schema: Structures],[XML Schema: Datatypes] is required of
all processors."  We consider it sufficient to just say what it means
when XML Schema is used, and whether it was used correctly.

-----
Section 3.1 and 3.2 describe rather intricate rules for which schema
components are visible to the WSDL.  A table or diagram would help
greatly in communicating this information.

-----
Section 4.1 describes wsdl:include as non-transitive, that is, you can't
refer to components in an included document that have themselves been
included.  This is inconsistent with xs:include, as well as restricting
the options available for modularization of WSDL files.  Please remove
the restriction making wsdl:include non-transitive.  (Note that
wsdl:import should remain explicitly non-transitive, just as xs:import
is.)

-----
Section 5: The wsdl:documentation element is not mapped into the WSDL
Component model.  This relegates information embedded there to the same
status as an XML comment.  If the wsdl:documentation element provides no
semantic difference than an XML comment, we request that it be removed.
But we prefer that the contents of the wsdl:documentation element be
reflected in the Component model by adding a new property to each
component (e.g., {documentation}) whose value is the XML Element
Information Item of the wsdl:documentation element.  This provides
access to the contents of the documentation element, but also to
annotations (specifically xml:lang) specified on that element.

-----
Section 8.3 on Processor Conformance is untestable (unlike Section 8.1).
Document conformance is adequate for a specification that defines
metadata rather than runtime processing.  Remove section 8.3.

-----
Section 8.3 states: "A conformant WSDL processor MUST fail if it
processes an element containing a wsdl:include statement having a URI
that is not dereferenceable to a legal WSDL document."  What if it
already happens to have a copy of the to-be-included (or to be imported)
WSDL?  The value of requiring a failure in this case is unclear, and
we'd like this restriction to be relaxed.

-----
Appendix D is incomplete and therefore misleading about the amount of
change required to migrate from WSDL 2.0 to 1.1.  Please complete this
section.

-----
Part 2: Extensions

Section 2.1.1 Fault Replaces Message and 2.1.2 Message Triggers Fault
don't allow a fault to go to an alternate location in the case where a
wsa:FaultTo [WS-Addressing] header is specified.  Generalize these rules
so that addressing mechanisms can be accommodated without defining new
MEPs.

-----
Section 2.1.2: What does the term "propagate" mean in the context of
sending a fault? Please clarify.

-----
Section 2.1.1 and 2.1.2 say that the fault message must be delivered.
This implies that the endpoint does not have the option to generate but
not send the fault.  While always useful for debugging, faults are
sometimes logged but not sent to prevent information disclosure and
denial of service attacks.  SOAP 1.2 allows this.


-----
Section 3.1: The Application Data Feature should be replaced by a
construct similar to the SOAP header binding extension in WSDL 1.1:

* The intended semantic of the AD property URI suggests an architectural
commitment beyond any required by SOAP -- application versus some other
processing layer?  Such distinctions are premature at this point in Web
service development and have unclear implications on interoperability.

* Wrapping the name of the XML Schema element for a header block with
two elements and two attributes provides little additional information,
sacrifices readability, and introduces opportunities for errors in WSDL
generation and parsing.

* The dataHeaders header block introduces descriptive markup in SOAP
messages.  Description languages should not introduce significant markup
in the instances they describe.

* The dataHeaders header block implies that endpoints will not be able
to successfully exchange messages unless they agree on a WSDL 2.0
description.  XML Schema does not impose this restriction on the use of
XML.  WSDL 1.1 does not impose this restriction on SOAP messages.  WSDL
2.0 should not impose this restriction either.

* The rules for when to include the dataHeaders block and what to
include in it are underspecified.

* While both the SOAP Module and the missing SOAP header construct
declare a name for a header block (the former a URI and the latter a
URI:local name pair), SOAP Module does not provide a structural
description of the header block (e.g., an XML Schema element).  This
precludes tooling and intermediaries from serializing, deserializing,
and/or validating the header without external header-specific knowledge.
Such processing has proved useful for the SOAP Body and should be
enabled for SOAP headers too.

* The declaration of SOAP 1.1 and 1.2 headers in WSDL is currently in
use.  (Microsoft supports this in ASMX.)  We expect this useful practice
to continue going forward.

-----
Part 3: Bindings

Section 3.8.1: Serialization as "application/x-www-form-urlencoded" does
not appear to constrain XML elements to be unqualified, but neither does
it explain how namespaced elements are to be serialized.

-----
Microsoft does not currently plan to implement Section 3: WSDL HTTP
binding.  If there is only weak support from other implementers perhaps
it would be wisest to drop this binding or factor it out into a Working
Group Note.

-----
EOF

Received on Tuesday, 9 November 2004 01:04:20 UTC