In a previous entry I described some enhancements that were under consideration for an updated version of the WADL specification. The resulting updated WADL specification is now available along with the associated W3C XML Schema and RelaxNG Schema.

In revising the specification I made a couple of breaking changes to simplify the language and improve clarity so this version of the specification uses a new XML namespace for the WADL elements. Here's what's new:

Resource References

As previously described, resource elements can now act as references to resources described elsewhere to avoid duplication and promote re-use.

Identification of Links

As previously described, a link element has been added to support identification of links within representations and to indicate the resource such links identify.

Documentation

A doc element has been added as an optional first child element of all of the other WADL defined elements. The doc element has an xml:lang attribute to identify the language of the documentation, a title attribute that provides a short plain text description of the element being documented, and contains mixed content for the detailed documentation. E.g.:

<application xmlns="..." xmns:xhtml="...">

  <doc xml:lang="en" title="Online widget catalogue">
    <xhtml:p>An online widget catalogue for all your widgeting needs.</xhtml:p>
  </doc>
  
  <resources base="http://example.com/">
    <doc xml:lang="en" title="Commercial widgets">
      <xhtml:p>Widgets for the commercial sector.</xhtml:p>
    </doc>
    ...
  </resources>
  
</application>

Multiple sibling doc elements can be used when documentation is available in multiple languages.

Resource Rework

A resource element can now encompass multiple path segments within a URI and path segments can either be static or contain embedded path parameters. E.g.:

<resources base="http://example.com/">
  <resource path="applications/widgets/{widgetId}">
    ...
  </resource>
</resources>

The above extract describes a set of resources identified by the URIs conforming to the following template:

http://example.com/applications/widgets/{widgetId}

Where {widgetId} is replaced by the value of the widgetId parameter when accessing a particular resource.

Parameter Rework

The path_variable, query_variable and representation_variable elements have been replaced by a single param element.

The param element has the union of the attributes from the variable elements it replaces and adds a style attribute that indicates the use of the parameter (plain, matrix or form) and a default attribute to indicate the default value of the parameter if not explicitly specified.

A new option element supports enumerated parameter values without the need to resort to XML Schema.

Future Work

With these changes I'm now pretty happy with the base language but there remain a couple of things that still need more work:

• Support for declaring security requirements. Declaring the need for HTTP basic or digest authentication would be straightforward but often other schemes are used and this area needs some further research.
• WADL can already be used to describe Web applications that use a variety of data formats but I'd like to explore whether specific formats, e.g. JSON, would benefit from additional support in WADL.

I believe that both of the above can be addressed with non-breaking extensions to the language.