RE: proposal for improving <documentation>

In general, I quite agree.  Fuller extensibility is better.

However, there is one really cool aspect of XSD's extensibility model.  The
xsd:appInfo wildcard is namespace="##any", which means that extensions in
the wsdl namespace (targetnamespace) could be included.  And the only way
that determinism allows optional extensions in the targetnamespace is
through a container element like appInfo.

Schema V.next could be backwards and/or forwards compatible with schema 1.0
in the same namespace.  WSDL 1.N can't be compatible with WSDL 1.2 (assuming
it's still 1.2 :-) unless the WSDL 1.2 elements stay in the wsdl 1.2 ns and
the WSDL 1.N extensions are in a different namespace.  

IMO, Schema has a cleaner and better versioning strategy that WSDL because
of this simple "tweak".  I personally think that a combination of the
approaches is the best fit - allow ##other as wsdl currently does, and also
provide an appinfo like element with <any
targetnamespace="##targetnamespace"/> at the end of each element's type
definition for permitting compatible changes.

As an aside, I find very frustrating that Schema doesn't make it simpler to
allow full extensibility in a simpler manner.  grumble.

Cheers,
Dave
> -----Original Message-----
> From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]On
> Behalf Of Jonathan Marsh
> Sent: Thursday, September 18, 2003 10:46 AM
> To: www-ws-desc@w3.org
> Subject: RE: proposal for improving <documentation>
> 
> 
> 
> [Speaking personally. I just can't keep quiet on this one!]
> 
> XSD has xsd:annotation/xsd:appInfo because they don't allow extension
> elements in arbitrary spots.  We do, so we can add machine-readable
> information anywhere in WSDL.  The extra complexity in the syntax is
> therefore completely unnecessary, and not backward compatible 
> with WSDL
> 1.1.  I have always thought Schema's extensibility model was 
> needlessly
> Byzantine and hope we won't make the same mistake.
> 
> > -----Original Message-----
> > From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]
> On
> > Behalf Of Sanjiva Weerawarana
> > Sent: Thursday, September 18, 2003 4:45 AM
> > To: www-ws-desc@w3.org
> > Subject: proposal for improving <documentation>
> > 
> > 
> > I'd like to propose that we change <documentation> to be
> > consistent with XSD's <annotation> element:
> > 
> > <xsd:annotation>
> >   <xsd:documentation> human readable stuff </xsd:documentation>
> >   <xsd:appInfo> machine readable stuff </xsd:appInfo>
> > </xsd:annotation>
> > 
> > So, I propose we drop <wsdl:documentation> and replace it
> > with:
> > 
> >     <wsdl:annotation>
> >       <wsdl:documentation> human readable stuff 
> </wsdl:documentation>
> >       <wsdl:appInfo> machine readable stuff </wsdl:appInfo>
> >     </wsdl:annotation>
> > 
> > This allows tools to use this hook and furthermore we'd
> > be consistent with XSD, which is said to be a good thing ;-).
> > 
> > Sanjiva.
> > 
> 
>