mnot’s blog

Design depends largely on constraints.” — Charles Eames

Wednesday, 18 May 2005

WADLing towards Web Description

Marc Hadley has released WADL in the wild, and I’m intrigued; based on a first look, I’d say it’s the most promising Web (as opposed to Web Services) description language yet.

Why? First of all, it’s very resource-oriented; you can clearly and easily see the deliniation between different described resources. It encourages good practices, and supports generative URIs both in query strings and in path segments, which I think is crucial. It’s simple and easy to read.

Initial Feedback and Questions

That said, I can’t pass by an opportunity to give some feedback and ask some questions :) Many of my thoughts are based on experiences with my straw-man webdesc format (and its implementation in Python). I’m not attached to that particular format (there are far too many flying around already!), but I would like to see WADL waddle towards webdesc in a few ways.

1) First of all, the resources section is a great start, but as I understand the design, if you have a long list of resources, it’ll show up as a long, flat list of resource elements in WADL, like this:

<resources>
  <resource uri="http://www.example.com/">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/button1">
  ...
  </resource>
  <resource uri="http://www.example.com/control-panel/button1">
  ...
  </resource>
</resources>

It seems to me that it would be much better to exploit the hierarchical nature of both URIs and XML to do something like this;

<resources>
  <resource uri="http://www.example.com">
    <resource uri="control-panel/">
      <resource uri="button1"/>
      <resource uri="button2"/>
    </resource>
  </resource>
</resources>

That way, you could refer into the tree of resources, relocate them easily, and so forth. Adding metadata that inherits down the tree would also be more naturally expressed this way.

2) I also wonder if it would be better to separate the mapping of URIs from the nature of the resources themselves; I know that WSDL has too much abstraction, but it seems like there’s a real advantage to having a map of URIs to resource types, like this;

<resources>
  <resource uri="http://www.example.com" type="#main">
    <resource uri="control-panel/" type="#control">
      <resource uri="button1" type="#button1" />
      <resource uri="button2" type="#button2" />
    </resource>
  </resource>
</resources>

so that you could, later in the document, have:

<resource id="main">
  <operation name="get">
    ....
  </operation>
</resource>

That way, you can reuse resource types separate from their mapping to a particular URI space; for example, if you want to deploy an application in multiple places.

I did it like this in webdesc;

<URIStructure base="http://www.example.com/" resource="#main">
    <pathSegment value="control-panel" resource="#control">
       <pathSegment value="button1" resource="#button1"/>
       <pathSegment value="button2" resource="#button2"/>
    </pathSegment>
</URIStructure>

This leads to a design where instead of using escape characters in the URI, you can just use the markup to indicate generative URIs, like this;

<URIStructure base="http://ldap.example.com/" resource="#ldapmain">
  <pathSegment value="people" resource="peopleContainer">
    <pathSegment type="#personName" resource="person"/>
    <!-- @type indicates that this pathSegment is generative, with that type -->
  </pathSegment>
</URIStructure>

3) Instead of the ref/name convention; why not use URIs to identify components? They’d allow you to refer to a type (or an operation, or a resource…) anywhere on the Web.

4) Also, WADL needs to more explicitly document extensibility, and also document what the scope of extension elements attached at particular points is. This is necessary so that you can say, for example, that you require HTTP authentication, or support compression, on an application-wide, per-resource, resource and children, per-operation, or per-representation basis.

Minor Nits

5) Does WADL have a namespace or a media type itself? It should (especially the latter, considering what it’s describing!).

6) How do you escape ‘{’ and ‘}’ characters, both of which are legal in URIs? (And, please don’t reference a language-specific convention in a language-neutral description format!)

7) I’m not crazy about ‘parameter,’ as it seems very RPC-ish. Not sure what else would be better, though.

8) With regard to ‘representation,’ keep in mind that some entity bodies are representational of that resource’s state; e.g., on a 4xx or 5xx status response, and with many POST requests. Some of the language should be adjusted to reflect that.

9) The language describing @element should be more explicit; I’d suggest “For XML-based representations, specifies the qualified name of the root element.”


Filed under: Web XML

5 Comments

Bill de hOra said:

Y'all seem to be going out of your way to not use RDF. I'll try to write something up about it.

Thursday, May 19 2005 at 3:29 AM +10:00

Stefan Tilkov said:

Didn't Mark Baker already do that with RDF-Forms (http://www.markbaker.ca/2003/05/RDF-Forms/)?

Thursday, May 19 2005 at 4:35 AM +10:00

Mark Nottingham said:

I actually stopped work on webdesc because I wanted to base it on the RDF data model, and describe it with RDF Schema and OWL (rather than basing it on the Infoset and XML Schema).

To do that, I felt that I needed a human-readable mapping to XML, because I didn’t want to force RDF on people who want to use it; one experimental technology at a time is enough.

Thursday, May 19 2005 at 7:38 AM +10:00

Danny said:

Yet another resource description format, that's nice. Pass the XSLT ;-)

I'm really in two minds about exploiting the hierarchies of URIs (/XML) as you suggest. The syntax structure of URIs does certainly lend itself to this (I've been playing around with pulling the path apart with my Pymplex thing). But whether the use of the syntax in this fashion is a good general idea I don't know - it's kind of adding semantics to the names, which already have them defined in another 'dimension' - i.e. they are just opaque names.

If you accept the other dimension and ascribe additional meaning to the path, then sure, the generative URI (and presumably degenerative) mappings follow pretty easily, and the use of XML syntax hierarchy seems another obvious way of exploiting it.

Maybe I've spent too much time around graphs, but I can't help feeling that wiring a tree low down into the system model like this is an artificial blockage. Didn't the path hierarchy follow from the filesystem hierarchy - so where are the symlinks in this model? Or will Web 3.0 be Gopher?

There's some similar stuff in OpenURL:
http://www.niso.org/standards/standard_detail.cfm?std_id=783

Thursday, May 19 2005 at 3:35 PM +10:00

Mark Nottingham said:

Danny,

Thanks for the OpenURL ref; will take a look.

WRT opacity — I couldn’t disagree more; the point of the opacity axiom is that you mustn’t assume things about the structure of URIs *without* authoritative knowledge, either from the URI spec or its delegates, or from the URI authority itself. This is what I did with URISpace — what we’re talking about here is a very similar path.

Hopefully, the number of description formats will get smaller as we’re able to focus on the few — or only — good ones.

Thursday, May 19 2005 at 3:41 PM +10:00

Creative Commons