RE: Sample Application described in WSDL using HTTP binding and s howing messages from Asir Vedamuthu on 2004-06-23 (www-ws-desc@w3.org from June 2004)

From: Asir Vedamuthu <asirv@webmethods.com>
Date: Wed, 23 Jun 2004 06:53:05 -0700
To: 'David Orchard' <dorchard@bea.com>, Asir Vedamuthu <asirv@webmethods.com>, www-ws-desc@w3.org
Message-ID: <5B10E50E14A4594EB1B5566B69AD94072EF5D1@maileast>
Thank you for your clarification.

> Are suggesting that we should change it to say that the 
> target namespace MUST be ignored?  Or that my example is broken?

Slightly different. I am suggesting that {target namespace} MUST be absent.
May be, that was the intention but not spelled out right in Part 3.

Per your example, since QName of element decl 'Genre' is,
 [target namespace] = http://www.w3.org/2002/ws/music/2004/
 [name] = Genre

I would expect

> GET /Music/Artist?genre="electronica"
                    ^^^^^
'genre' to be a QName instead of just [local name].


> I did suggest a # of mechanisms for how to serialize a QName into a URI...

I read your blog [1]. Possible QNames in Schema for URI style are,

(a) Element tag is a QName
(b) Element content is of type QName

Possible mappings to URI data model are,

(c) QName -> segment in path component
(d) QName -> parameter name in query component
(e) QName -> parameter value in query component

Possible combinations are,

(f) (a), (c)
(g) (a), (d)
(h) (b), (c)
(i) (b), (e)

of them, (f) and (h) are equivalent.

Mapping your suggested QName to URI serializations,

1, 2, 3, 4, 5, 7, 8, 9, -> (f) or (h)
10, 11, 14, 15, 16, -> (g)
? -> (i)

Well, this serialization is an interesting exercise. In practice, I wouldn't
expect everything (like attributes and complex types) to map from XML data
model to URI data model. In this context, I am wondering if QName is an
interesting case for URI serialization? If not, then my suggestions apply.
Repeating them,

* schema restriction for URI style: {target namespace} of an element
declaration in the complex type that defines the body of an input element
MUST be absent. This rules out (a).

* schema restriction for URI style: {type definition} of an element
declaration in the complex type that defines the body of an input element
MUST NOT be a xs:QName, xs:NOTATION, or any simple type derived from
xs:QName or xs:NOTATION. This rules out (b).

BTW, xforms spec doesn't support QNames,
http://www.w3.org/TR/2003/REC-xforms-20031014/slice11.html#serialize-urlenco
de

> I'm not sure what you are suggesting.  I think roughly we are 
> trying to define a mechanism for serializing a subset of the contents 
> of a simpleType into a URI.

We are in-sync on this. But, this restriction is not spelled out right in
Part 3. Suggested rephrase is, "{type definition} of an element declaration
in the complex type that defines the body of an input element MUST be a
simple type." This rules out complex types.

[1] http://www.pacificspirit.com/blog/2004/04/29/binding_qnames_to_uris

Asir


-----Original Message-----
From: David Orchard [mailto:dorchard@bea.com] 
Sent: Tuesday, June 22, 2004 4:15 PM
To: Asir Vedamuthu; www-ws-desc@w3.org
Subject: RE: Sample Application described in WSDL using HTTP binding and
showing messages


awesome review.  Comments inline.

> -----Original Message-----
> From: Asir Vedamuthu [mailto:asirv@webmethods.com]
> Sent: Tuesday, June 22, 2004 11:53 AM
> To: David Orchard; www-ws-desc@w3.org
> Subject: RE: Sample Application described in WSDL using HTTP 
> binding and
> showing messages
> 
> 
> One of your observations is,
> 
> "Overall, there is an explosion of schemas and operations 
> that are needed
> because of the binding. I think this kind of sucks and comes 
> close to making
> the http binding useless as it stands."
> 
> I am not surprised by your statement, "there is an explosion 
> of schemas and
> operations that are needed". XML Schema is a language for 
> describing the
> structure and contents of XML documents. In this case, we are 
> using XML
> Schema + binding for describing the path and query component 
> of URI data
> model. This is a stretch. But, not free though. It comes with 
> a certain
> level of pain :-(
> 
> I am surprised by your statement, "comes close to making the 
> http binding
> useless". I request you to explain why?

If I am creating an HTTP based web service, would I use WSDL 2.0 HTTP
binding or some other description format (text?) for describing my service?
In my mind, I don't see this adding much value for an Amazon/Atom/some other
service because of the complexity and lack of re-use of the schema
constructs.  For example, we have to create a "GET/PUT/POST/DELETE"
operation for interactions with each level of the hierarchy, ie Artist,
Album, Artist properties, Album properties.  I would have thought we could
have some way of more simply saying "I've got a structure of Artists +
props, Albums + props, and they are completely RESTFUL, which means you can
do GET/PUT/POST/DELETE on various nodes in the tree".  But this is just my
personal observation.

> 
> I would expect the following restrictions (in addition to 
> what is spelled
> out in RPC style [1]) on XML schema for URI style:
> 
> (a) {target namespace} of an element declaration [2] in the 
> complex type
> that defines the body of an input element MUST be absent.
> 
> Why? In David's example,
> "<xs:element name="ArtistQuery">
>     <xs:complexType>
>       <xs:complexContent>
>         <xs:extension base="tns:ArtistIDBase">
>           <xs:sequence>
>             <xs:element name="Name" type="xs:string" minOccurs="0"/>
>             <xs:element name="Genre" type="xs:string" 
> minOccurs="0"/> .."
> 
> QName of element decl 'Genre' is,
>  [target namespace] = http://www.w3.org/2002/ws/music/2004/
>  [name] = Genre
> 
> I am not aware of a mechanism to serialize this QName to URI 
> path/query
> component.

Are suggesting that we should change it to say that the target namespace
MUST be ignored?  Or that my example is broken?

I did suggest a # of mechanisms for how to serialize a QName into a URI...

> 
> 
> (b) {type definition} of an element declaration [2] in the 
> complex type that
> defines the body of an input element MUST be a simple type.
> 
> Why? I am not aware of a mechanism to serialize a complex 
> type value to URI.
> In part 3, I read a statement close to this, but not quite 
> the same - "If
> the children elements of the input sequence are defined using 
> an XML Schema
> type, they MUST derive from xsd:simpleType, .." [3]. 
> 'xsd:simpleType' is the
> xml rep of a simple type. There isn't any simple type whose name is
> xsd:simpleType.
> 

I'm not sure what you are suggesting.  I think roughly we are trying to
define a mechanism for serializing a subset of the contents of a simpleType
into a URI.

> 
> (c) {type definition} of an element declaration [2] in the 
> complex type that
> defines the body of an input element MUST NOT be a xs:QName, 
> xs:NOTATION, or
> any simple type derived from xs:QName or xs:NOTATION. 
> 
> Why? Lexical rep of these types are context sensitive, aka 
> namespace binding
> context. I am not aware of a mechanism to specify namespace 
> bindings (other
> than XPointer xmlns() scheme) in a URI path/query component.
> 

See above.  I think we are trying to make sure we don't have to serialize a
namespace name into a URI.  I think we could come up with a standardized
Qname to URI binding, or a parameterized QName to URI binding with one such
binding defined.

> 
> PS: I don't know why URI style places a restriction on binary 
> simple types:
> "MUST NOT derive from xsd:hexBinary or xsd:base64Binary" [3]. 
> Any thoughts?
> 
> [1]
> http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20
> .html#RPCStyle
> [2] http://www.w3.org/TR/xmlschema-1/#Element_Declaration_details
> [3]
> http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20
> -bindings.html
> #_operation_uri_style
> 
> Asir
> 
> -----Original Message-----
> From: www-ws-desc-request@w3.org 
> [mailto:www-ws-desc-request@w3.org] On
> Behalf Of David Orchard
> Sent: Tuesday, June 22, 2004 1:23 PM
> To: www-ws-desc@w3.org
> Subject: RE: Sample Application described in WSDL using HTTP 
> binding and
> showing messages
> 
> 
> 
> As promised, I've updated the music example.  I fixed the 
> bugs that Asir
> pointed out, added a number of design notes, put more 
> comments in the WSDL,
> added another couple of examples, added HTML formatting.
> 
> http://www.pacificspirit.com/Authoring/wsdl/ArtistWSDL2uriform
> encoding.html
> 
> Hopefully this will be more useful to reviewers.
> 
> Cheers,
> Dave
> 
> > -----Original Message-----
> > From: www-ws-desc-request@w3.org 
> [mailto:www-ws-desc-request@w3.org]On
> > Behalf Of David Orchard
> > Sent: Wednesday, June 09, 2004 5:12 PM
> > To: www-ws-desc@w3.org
> > Subject: Sample Application described in WSDL using HTTP binding and
> > showing messages
> > 
> > 
> > 
> > This is potential primer material that explores how to use 
> > the WSDL http binding to describe interactions with an HTTP 
> > service.  This is an example of music information and 
> > purchasing Web service.  It is styled after the CDDB database 
> > http://www.gracenote.com/gn_products/cddb.html and 
> > allmusic.com sites.  It has generated a number of questions 
> > where I don't think the WSDL as exists can express certain 
> > things.  I'm grateful for any reviews or comments on this.  
> > It could be put into the primer as well.
> > 
> > An Artist has:
> >  - ID
> >  - Name
> >  - Biography
> >  - Genre
> >  - Image
> >  - Web site
> > 
> > Clients have 3 types of interactions: retrieve all/specific 
> > information, change/add/delete information, and search based 
> > upon a subset of the Artist fields. 
> > 
> >  - Get Artist complete information for a given Artist
> >  - Get Artist field contents (Name, Biography, etc.) for a 
> > given Artist
> >  - Add Artist
> >  - Update Artist
> >  - Get Artist list by Artist name, genre
> > 
> > Schema
> > <?xml version="1.0" encoding="UTF-8"?>
> > <xs:schema 
> > targetNamespace="http://www.w3.org/2002/ws/music/2004/" 
> > xmlns:xs="http://www.w3.org/2001/XMLSchema" 
> > xmlns:tns="http://www.w3.org/2002/ws/music/2004/" 
> > elementFormDefault="qualified" attributeFormDefault="unqualified">
> >   <xs:element name="Music">
> >     <xs:complexType name="Music">
> >       <xs:sequence>
> >         <xs:element ref="tns:Artist" maxOccurs="unbounded"/>
> >         <xs:element ref="tns:ArtistRef" maxOccurs="unbounded"/>
> >         <xs:any namespace="##other" processContents="lax"/>
> >       </xs:sequence>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- To do a /Music/Artist/5, need to have a type with only 
> > 1 child -->
> >   <xs:complexType name="ArtistIDBase">
> >     <xs:sequence>
> >       <xs:element name="id" type="xs:ID"/>
> >     </xs:sequence>
> >   </xs:complexType>
> >   
> >    <!-- When Adding an artist, the ID isn't known -->
> >   <xs:element name="ArtistWithoutID">
> >     <xs:complexType name="ArtistWithoutId">
> >       <xs:sequence>
> >         <xs:element name="Name" type="xs:string"/>
> >         <xs:element name="Biography" type="xs:string"/>
> >         <xs:element name="Genre" type="xs:string"/>
> >         <xs:element name="Image" type="xs:anyURI"/>
> >         <xs:element name="Site" type="xs:anyURI"/>
> >         <xs:any namespace="##other" processContents="lax"/>
> >       </xs:sequence>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- Need to have ID + all of the fields for <artist> returns -->
> >   <!-- probably better modelling in schema to combine the id 
> > with the non-id fields -->
> >   <xs:element name="Artist">
> >     <xs:complexType name="Artist">
> >       <xs:complexContent>
> >         <xs:extension base="tns:ArtistIDBase">
> >           <xs:sequence>
> >             <xs:element name="Name" type="xs:string"/>
> >             <xs:element name="Biography" type="xs:string"/>
> >             <xs:element name="Genre" type="xs:string"/>
> >             <xs:element name="Image" type="xs:anyURI"/>
> >             <xs:element name="Site" type="xs:anyURI"/>
> >             <xs:any namespace="##other" processContents="lax"/>
> >           </xs:sequence>
> >         </xs:extension>
> >       </xs:complexContent>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- Need a query structure to do queries, ie 
> &name=thieverycorp -->
> >    <xs:element name="ArtistQuery">
> >     <xs:complexType name="ArtistQuery">
> >       <xs:complexContent>
> >         <xs:extension base="tns:ArtistIDBase">
> >           <xs:sequence>
> >             <xs:element name="Name" type="xs:string" minOccurs="0"/>
> >             <xs:element name="Genre" type="xs:string" 
> minOccurs="0"/>
> >             <xs:element name="Rating" type="xs:decimal" 
> > minOccurs="0"/>
> >           </xs:sequence>
> >         </xs:extension>
> >       </xs:complexContent>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- ID + REF structure for getting back list of IDs that 
> > can be used to create URI -->
> >   <xs:element name="ArtistIDRef">
> >     <xs:complexType name="ArtistIDRef">
> >       <xs:complexContent>
> >         <xs:extension base="tns:ArtistIDBase">
> >           <xs:sequence>
> >             <xs:element name="Name" type="xs:string"/>
> >           </xs:sequence>
> >         </xs:extension>
> >       </xs:complexContent>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- Artist Field names for doing field queries -->
> >   <xs:element name="ArtistIDFieldName" type="tns:ArtistField"/>
> >   <xs:complexType name="ArtistField">
> >     <xs:complexContent>
> >       <xs:extension base="tns:ArtistIDBase">
> >         <xs:sequence>
> >           <xs:element name="Field" type="tns:ArtistFieldNames"/>
> >         </xs:sequence>
> >       </xs:extension>
> >     </xs:complexContent>
> >   </xs:complexType>
> >   
> >   <!-- Artist Field Name + Value for setting field -->
> >   <xs:element name="ArtistFieldNameAndValue">
> >     <xs:complexType name="ArtistFieldNameAndValue">
> >       <xs:complexContent>
> >         <xs:extension base="tns:ArtistField">
> >           <xs:sequence>
> >             <xs:element name="Value"/>
> >           </xs:sequence>
> >         </xs:extension>
> >       </xs:complexContent>
> >     </xs:complexType>
> >   </xs:element>
> >   
> >   <!-- List of field names -->
> >   <xs:simpleType name="ArtistFieldNames">
> >     <xs:restriction base="xs:string">
> >       <xs:enumeration value="Name"/>
> >       <xs:enumeration value="Biography"/>
> >       <xs:enumeration value="Genre"/>
> >       <xs:enumeration value="Image"/>
> >       <xs:enumeration value="Site"/>
> >     </xs:restriction>
> >   </xs:simpleType>
> >   
> >   <!-- URI for getting back opaque URIs -->
> >   <xs:complexType name="uri">
> >     <xs:sequence>
> >       <xs:element name="uri" type="xs:anyURI"/>
> >     </xs:sequence>
> >   </xs:complexType>
> > </xs:schema>
> > 
> > 
> > 
> > Interacting using the x-www-form-uriencoded style
> > WSDL
> > 
> > <?xml version="1.0" encoding="UTF-8"?>
> > <wsdl:definitions xmlns:musicw="http://example.com/Artist" 
> > xmlns:wsdl="">
> > 	<xs:import href="Music-Artist.xsd"/>
> > 	<wsdl:interface name="Artist">
> > 		<wsdl:operation name="ArtistSearch" method="GET">
> > 			<wsdl:input ref="music:ArtistQuery"/>
> > 			<wsdl:output ref="music:Music"/>
> > 		</wsdl:operation>
> > 		<wsdl:operation name="ArtistRefSearch" method="GET">
> > 			<wsdl:input ref="music:ArtistQuery"/>
> > 			<wsdl:output ref="music:Music"/>
> > 		</wsdl:operation>
> > 		<wsdl:operation name="GetArtist" method="GET">
> > 			<wsdl:input ref="music:ArtistID"/>
> > 			<wsdl:output ref="music:Artist"/>
> > 		</wsdl:operation>
> > 
> > 		<!-- Given a uri in a field for an artist, 
> > simply dereference the URI -->
> > 		<wsdl:operation name="GetArtistOpaqueURI" method="GET">
> > 			<wsdl:input ref="music:uri"/>
> > 			<wsdl:output ref="music:ArtistWithoutURI"/>
> > 		</wsdl:operation>
> > 		
> > 		<wsdl:operation name="GetFieldByFieldName" method="GET">
> > 			<wsdl:input ref="music:ArtistFieldName"/>
> > 			<wsdl:output ref="xsd:any"/>
> > 		</wsdl:operation>
> > 		<wsdl:operation name="AddArtistServerID" method="POST">
> > 		   <wsdl:input ref="music:ArtistWithoutID"/>
> > 		   <wsdl:output ref="music:ArtistRef"/>
> > 		 </wsdl:operation>	 
> > 		 <wsdl:operation name="AddArtistClientID" method="POST">
> > 		   <wsdl:input ref="music:Artist"/>
> > 		   <wsdl:output ref="music:ArtistRef"/>
> > 		 </wsdl:operation>
> > 		<wsdl:operation name="DeleteArtist" method="DELETE">
> > 			<wsdl:input ref="music:ArtistID"/>
> > 		</wsdl:operation>
> > 		<wsdl:operation name="UpdateArtist" method="PUT">
> > 			<wsdl:input ref="music:Artist"/>
> > 			<wsdl:output ref="music:Artist"/>
> > 		</wsdl:operation>
> > 		<wsdl:operation name="UpdateField" method="PUT">
> > 			<wsdl:input 
> > ref="music:ArtistFieldNameAndValue"/>
> > 		</wsdl:operation>
> > 
> > 	</wsdl:interface>
> > 	<wsdl:binding name="Artist" interface="Artist" 
> > http:defaultMethod="GET">
> > 	<wsdl:operation ref="ArtistSearch" location="Artist/{Name}"/>
> > 	<wsdl:operation ref="ArtistRefSearch" 
> > location="ArtistRef/{Name}"/>
> >   	<wsdl:operation ref="GetArtist" location="Artist/{ID}"/>
> >   	<wsdl:operation ref="GetArtistOpaqueURI" location="{uri}"/>
> >   	<wsdl:operation ref="GetFieldByFieldname" 
> > location="Artist/{ID}/"/>
> >   	<wsdl:operation ref="AddArtistServerID" 
> > location="Artist" method="POST"/>
> >  	<wsdl:operation ref="AddArtistClientID" 
> > location="Artist" method="POST"/>
> >   	<wsdl:operation ref="DeleteArtist" 
> > location="Artist/{ID}" method="DELETE"/>
> >   	<wsdl:operation ref="UpdateArtist" 
> > location="Artist/{ID}" method="PUT"/>
> >   	<wsdl:operation ref="UpdateArtistField" 
> > location="Artist/{ID}" method="PUT"/>
> > 	</wsdl:binding>
> > </wsdl:definitions>
> > 
> > Message Examples
> > 
> > Example: ArtistSearch 
> > GET /Music/Artist?genre="electronica"
> > 
> > Return:
> > <Music>
> >   <Artist>
> >     <ID>5</ID>
> >     <Name>Thievery Corp</Name> 
> >     <Genre>Electronica</Genre>
> >     <site>http://thievery.com</site>
> >   </Artist>
> > </Music>
> > 
> > Example: GetAllArtists
> > GET /Music/Artist
> > 
> > Returns:
> > <Music>
> >   <Artist>
> >     <ID>5</ID>
> >     <Name>Thievery Corp</Name>
> >     <Genre>Electronica</Genre>
> >     <site>http://thievery.com</site>
> >   </Artist>
> > </Music>
> > 
> > Example: GetArtistReferences
> > GET /Music/ArtistRef?genre="electronica"
> > 
> > Return:
> > <Music>
> >   <ArtistRef>
> >     <ID>5</ID>
> >     <Name>Thievery Corp</Name> 
> >   </ArtistRef>
> > </Music>
> > 
> > Example: GetArtist 
> > GET /Music/Artist/5
> > 
> > Return:
> > <Artist>
> >   <ID>5</ID>
> >   <Name>Thievery Corp</Name>
> >   <Genre>Electronica</Genre>
> >   <site>http://thievery.com</site>
> > </Artist>
> > 
> > Example: GetArtistOpaqueURI
> > * This assumes the URI="id/xyz"
> > GET /Music/Artist/id/zyz
> > 
> > Return:
> > <Artist>
> >   <Name>Thievery Corp</Name>
> >   <Genre>Electronica</Genre>
> >   <site>http://thievery.com</site>
> > </Artist>
> > 
> > 
> > Example: GetFieldByFieldName
> > GET /Music/Artist/5?field="site"
> > 
> > Return:
> > <site>http://thievery.com</site>
> > 
> > Example: AddArtistServerId
> > POST /Music/Artist
> > <Artist>
> >     <Name>Thievery Corp version 2</Name>
> >     <Genre>Electronica</Genre>
> >     <site>http://newbetterthievery.com</site>
> > </Artist>
> > 
> > Returns:
> > Content-Location: /Music/Artist/6
> > * How is the HTTP Content-location mapped to xml in this 
> > case?  Is it dropped?  Should there be XML returned?
> > 
> > Example: AddArtistClientID
> > * I don't think this works in the current WSDL http binding
> > POST /Music/Artist/7
> > <Artist>
> >     <ID>7</ID>
> >     <Name>Thievery Corp version 3</Name>
> >     <Genre>Electronica</Genre>
> >     <site>http://newwaybetterthievery.com</site>
> > </Artist>
> > 
> > Returns:
> > Content-Location: /Music/Artist/7
> > 
> > Example: DeleteArtist
> > DELETE /Music/Artist/5
> > 
> > Example: UpdateArtist
> > * I don't think this works in the current WSDL http binding
> > PUT /Music/Artist/5
> > <Artist>
> >     <ID>5</ID>
> >     <Name>Thievery Corp</Name>
> >     <Genre>Electronica</Genre>
> >     <site>http://newbetterthievery.com</site>
> >   </Artist>
> > 
> > Example: UpdateArtistField
> > * I don't think this works in the wsdl as is
> > PUT /Music/Artist/5/site
> > <site>http://newbetterthievery.com</site>
> > 
> > 
>
Received on Wednesday, 23 June 2004 09:56:20 UTC