Re: More feedback on WADL

On 03/08/2005, at 1:47 PM, Marc Hadley wrote:
>>
>> 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.

I'm using the term in a very generic way here -- more generic than  
just XML; i.e., any data typing system.


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

Well, I'm not sure there's agreement on that here, but it sounds like  
you're going down the path of #2, which limits the mechanisms to type  
systems that talk in terms of QNames / elements as identifiers. In  
which case, @element is reasonable (although I have a slight personal  
preference for @qname; 'element' implies an instance, not a class)  
and /types is a little too generic; the 'XML' is assumed. Perhaps  
'xml_types' or 'element_types'?

That said, I prefer URIs as identifiers, not only because they're  
full of Web goodness, but also because they're more universal. Also,  
I don't believe this system will be usable with RDF, requiring it to  
be pushed to extensibility.


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

Cool, I think that's a real improvement.


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

That's reasonable. I sometimes wonder if we should go down the road  
of defining a 'little' schema language along these lines, not only  
for parameters, but also for content; e.g., a set of XPaths and names  
bound to them.


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

Sorry; I got caught using a QName... argh! I'm melting!

This should be a URI-reference, e.g., #myResourceName.


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

That looks good, although 'parameter' is confusing here; many people  
will think 'URI query string parameter'.


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

I like the motivation here, but I'm still confused, just looking at  
the syntax, as to what's generative in the path segment vs. what's  
generative in the query component. If you could differentiate those  
somehow, it would be perfect.



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

My goal is to take as much of the URI structure as possible out of  
the string and into the XML, to make it more apparent and more  
modular (so you can revise the service more easily, and reference  
different parts in the description directly). While this might be  
good for your implementation, it makes mine more difficult, because I  
want to preserve a one-to-one resource-to-object mapping, and this  
approach effectively hides a resource.


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