Re: More feedback on WADL

Sorry for the slow reply, I was traveling in the UK last week and  
only had limited time and email access. More comments and responses  
inline below.

>>> * 2.2 Types -- can this section contain definitions from any type  
>>> system (e.g., XML Schema, RelaxNG, OWL, BNF, etc.) or just XML  
>>> Schema? My preference, I think, is to call it "schemaTypes" and  
>>> make it Schema-specific.
>>>
>>>
>> It was intended as a container for any type of description. Types  
>> is perhaps a bad choice of name, schemas might be better. I'm not  
>> sure about making it schema specific though, since I'd expect the  
>> child elements to convey the type of schema language (XSD,  
>> RelaxNG, etc).
>>
>
> I think the options for what this container can container are:
>   - any type system's type definitions
>   - any type system's type definitions that can agree on an  
> identifier convention (QNames, URIs)
>   - XML Schema type definitions
>
I'm having a problem with 'type' in the above since it has a quite  
specific meaning for W3C XML Schema and also a more generic meaning  
that could include a W3C XML Schema global element declaration.

> It might be helpful to nail down the 'element' attribute's  
> semantics before making this call; I'd expect that there'd be a  
> tight relationship between the two, i.e.,
>
>   1) 'types' can contain any type system definition; 'element' can  
> refer to any of them (and therefore would probably be better called  
> 'type')

My intent was that element would refer to the definition of an  
element, e.g. a W3C XML Schema global element declaration or a  
RelaxNG element pattern. Its referring to a particular element in a  
particular namespace so I think that 'element' is the right name and  
that 'type' could be confusing, particularly to W3C XML Schema users.

>   2) 'types' can contain any type system definition that uses  
> QNames as identifiers; 'element' can refer to any of them (and  
> therefore maybe 'qname' is a better name, despite how much I  
> dislike them)
>   2a) 'types' can contain any type system defintion that uses / can  
> use URIs as identifiers; 'element' can refer to any of them (and  
> therefore maybe 'uri' is a better name)
>   3) 'types' can only contain XML schema type definitions;  
> 'element' refers to one of them (and therefore they both probably  
> need a more Schema-specific name).
>
> (1) will have problems with *unintentional* collisions between type  
> systems / symbol spaces. Note that intentional collisions can be a  
> good thing; e.g., I might want to describe a structure in both XML  
> Schema and RelaxNG. The problem with (1) is that there's no  
> agreement to use QNames as the underlying type system.
>
But there *is* an agreement that elements are named with QNames so  
any language that supports definition of element structures will be  
fine - I think.

> I'm inclined towards either (3) or (2a); (3) makes it clear that if  
> you're not using Schema, you're using reference and container  
> elements through extensibility, while (2a) gives you a nice way to  
> accommodate other type systems, and reinforces URI centricity --  
> always a good thing in a Web description format ;)
>
> I don't like (2) because it somewhat arbitrarily restricts the  
> mechanism to XML-based formats that use QNames as identifiers  
> (therefore ruling out OWL, for example).
>
I don't know enough about OWL to comment, I'll go have a look.

>
>
>>> * 2.2.1 Include says that this element is to be used to allow "a  
>>> resource state representation description to be included by  
>>> reference." How does that work, considering that this is in the  
>>> context of the types section? I would have understood if you were  
>>> referring to externally-sourced type definitions, but that  
>>> doesn't seem to be the case. Was the intent to allow inclusion of  
>>> an abstract type for reuse?
>>>
>>>
>> The intent was to be able to include a schema (with a small s)  
>> document rather than having to inline it.
>>
>
> OK. The phrase 'resource state representation' is confusing here,  
> then.
>
I can fix that.

>
>
>>> 2.4 Operation - Since it's HTTP-specific, why not call this  
>>> method? Operation is very WSDL/RPC-ish. Perhaps something like  
>>> <method name="GET" id="fooGET">...
>>>
>>>
>> Right, the operation thing was to allow you specify a name for the  
>> combination of resource, HTTP method and request. For GET these  
>> tend to collapse to a single meaning but for POST you can thinks  
>> in terms of different operations based on request contents. Make  
>> sense ?
>>
>
> Yes. It would also be workable to use 'method' and explicitly say  
> that multiple occurrences of a method indicates alternate requests  
> that can be sent. Weaning people away from RPC is good :)
>
I'd be OK with that kind of inversion.

>
>
>>> 2.4.2 Request Parameters still uses NMTOKENs and QNames for  
>>> identification; did you miss these in the conversion to URIs?  
>>> (See also 2.6.1)
>>>
>>>
>> I didn't miss these, it was a deliberate choice. Use of ID for the  
>> parameter name would restrict you to only having one parameter  
>> with a particular name per description whereas I think many  
>> resource URIs could have the same query parameter name. Parameters  
>> are not something that get cross referenced within a description  
>> so there's no need to use ID.
>>
>
> Fair enough; I misunderstood where you were going here (it appeared  
> at first glance that name was the target for a QName, a la wsdl).
>
> type's description limits it to schema languages that use QNames as  
> identifiers; see discussion above. This is another reason I'd  
> prefer URI-centric schema identifiers to be used.
>
>
>> The use of NMTOKEN was a (perhaps vain) attempt to constrain the  
>> value space to be useable as a query .
>>
>
> Hm. Perhaps just keep this in the schema, and do it in prose, to  
> make it obvious it isn't schema-specific.
>
OK.

>
>
>>> Shouldn't the semantic expressed by the repeating attribute be  
>>> function of the referenced type definition?
>>>
>>>
>> Not sure what you mean, can you elaborate ?
>>
>
> You allow people to say whether a parameter is repeatable by using  
> the 'repeating' attribute. Since the parameter ultimately  
> references a type definition, shouldn't it be the job of whatever  
> schema language is being used to convey that?
>
That would be possible, e.g. using list types in W3C XML Schema, but  
I wanted to keep things simple. If you use the schema language to  
define this aspect of the parameter then you end up having to engage  
lots more machinery before you can decide whether a particular  
parameter can have one value or more. Even with the status quo one  
could still use schema language constructs to further refine the  
cardinality.

>
>
>>> WRT URI Component Substitution -- what's the use case for this?  
>>> It seems to make implementation more complex, and I'm thinking a  
>>> cleaner separation between the resource identity and the  
>>> parameters to it, by confining the parameters to the request  
>>> section. Or are you using 'parameters' in two different senses?
>>>
>>>
>> Two different senses. I wanted to support generative URIs like:
>>
>> http://example.com/widgets/${widgetId}
>>
>> as well as  URIs like
>>
>> http://example.com/widgets/${widgetId}?foo=bar
>>
>> The idea is that if a parameter name matches one embedded in the  
>> URI then you don't append the ?name= bit, you just substitue the  
>> value in the URI, if theres no match then you append the query  
>> parameter.
>>
>> E.g. if you have two parameters: widgetId and foo with values 10  
>> and bar respectively then:
>>
>> uri="http://example.com/widgets/${widgetId}" -> http://example.com/ 
>> widgets/10?foo=bar
>> uri="http://example.com/widgets" -> http://example.com/widgets/10? 
>> widgetId=10&foo=bar
>>
>
> I see. I'm not sure the shortcut is worth the added machinery; it  
> seems like there might be some strange corner cases in there; I'll  
> think about it and see if I can tease any out.
>
OK.

>
>
>>> My preferred solution would be to constrain the resource element  
>>> to path segments only, leaving query parameters in the request  
>>> description, and differentiate between static path segments and  
>>> generative names with a 'type' attribute, like this:
>>>
>>> <resources base="http://www.example.com/">
>>>    <resource name="widgets/">
>>>       <resource type="foo:myResourceName">
>>>           <method name="GET">
>>>              <request>
>>>                  <parameter name="myParam" type="my:paramType"/>
>>>              </request>
>>>           </method>
>>>       </resource>
>>>    </resource>
>>> </resources>
>>>
>>>
>>>
>> I'm not sure I understand the design here, is foo:myResourceName a  
>> path segment that is expected to be substituted for some value at  
>> runtime ?
>>
>
> Yes. resource/@name gives you a static name, resource/@type gives  
> you a generative URI.
>
How, in the above example, would I dereference foo:myResourceName ?  
Is there some kind of semantic to the QName compared to a simple  
parameter name like 'myParam' in the above example. E.g. is  
foo:myResource name supposed to be pointing to a <parameter> element  
somewhere ?

Would something like

<resources base="http://www.example.com/">
    <resource name="widgets">
       <resource parameter="myResourceName" type="xsd:string">
           <method name="GET">
              <request>
                  <parameter name="myParam" type="my:paramType"/>
              </request>
           </method>
       </resource>
    </resource>
</resources>

also fit the bill where resource/@name defines a fixed path segment  
and resource/@parameter defines a generative path segment ?

Maybe

<resources base="http://www.example.com/">
    <resource name="widgets">
       <resource>
           <parameter name="myResourceName" type="xsd:string"/>
           <method name="GET">
              <request>
                  <parameter name="myParam" type="my:paramType"/>
              </request>
           </method>
       </resource>
    </resource>
</resources>

would be better where the parameterization of the resource is even  
more explicit and follows the same syntax for request and  
representation parameters.

>
>
>>> Furthermore, I'd prefer to constrain the resource element to be  
>>> associated with *one* path segment only, so that there's a  
>>> stronger link between Web resources and XML structures describing  
>>> them (and, eventually, code implementing them).
>>>
>>> I know that's a big change (and I may have already mentioned it),  
>>> but I'd like to weigh the two approaches against each other in  
>>> discussion.
>>>
>>>
>>>
>> Again, I'm not sure I understand, do you mean that you'd disallow  
>> something like
>>
>> <resources>
>>   <resource uri="http://example.com/">
>>   ...
>>   <resource uri="widgets/${widgetId}">
>>     ...
>>   </resource>
>>     ...
>>   </resource>
>> </resources>
>>
>> And require an extra resource element for the "widgets" path  
>> segment ?
>>
>
> Yes. The idea is to put as much of the URI structure as is  
> practical in the XML, to reinforce the resource modelling. I'm also  
> concerned with the kind of code that's mapped to the style  
> currently in WADL; it seems like you could get into situations  
> where it would be a maintainability problem, because people want to  
> change the structure of their application (e.g., by adding new  
> resources, moving them around) and they have to dig into code  
> pretty deeply to adjust it to the new description.
>
> Also, keep in mind that an alternative to the above is
>
> <resources base="http://example.com/widgets/">
>    <resource type="my:widgetid"/>
> </resources>
>
> IME, once you get into the actual application, there aren't too  
> many "dummy" resources in the middle.
>
Having thought about this a fair bit I've concluded that it offers a  
nice simplification in implementation terms. I think if we couple  
that with the ability to specify a root path on the resources element  
as you suggest then we'd be in fine shape - though see my discussion  
on resource/@type above where instead of your example above we'd have  
something like:

<resources base="http://example.com/widgets/">
    <resource>
      <parameter name="widgetId" type="my:widgetid"/>
    </resource>
</resources>

Marc.

---
Marc Hadley <marc.hadley at sun.com>
Business Alliances, CTO Office, Sun Microsystems.