Re: More feedback on WADL

On 22/07/2005, at 3:02 PM, Marc Hadley wrote:
>> * 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

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')
   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.

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).


>> * 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.


>> 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 :)


>> 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.


>> 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?


>> 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.


>> 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.


>> 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.


--
Mark Nottingham     http://www.mnot.net/

Received on Saturday, 23 July 2005 17:15:04 UTC