Web Application Interaction Format (WAIF)

This Version: http://iandavis.com/2005/web-description/waif-20050727
Latest Version: http://iandavis.com/2005/web-description/waif-20050727
Previous Version: None
Author: Ian Davis (http://purl.org/NET/iand)

Abstract

This specification describes the Web Application Interaction Format (WAIF). WAIF is designed for describing interactions with web applications, particularly those using XML as a representation format.

Introduction

This document describes the Web Application Interaction Format (WAIF). The main goals of this format are:

Make it possible to describe applications based on the Web Architecture of resources identified by URIs.
Make it possible to describe applications and services and how to interact with them in a simple and intutive fashion.
Make it possible to separate the application interface from the multiplicity of possible implementations.
Make it possible to determine when two syntactically different parameters from different services have the same meaning.
Make it possible to reuse components within and between descriptions.

Model

WAIF describes web applications in terms of components and their properties. The principle component is the Service which represents a web application or service. A Service specifies the interactions that it supports along with a base URI that can be used to derive the URI for each interaction. An interaction deals with a specific type of resource and utilizes representations of that resource to manipulate it. An interaction may specify a path component to be combined with the service's base URI and also define a number of parameters that may be supplied as part of the URI query string. Parameters may be required or optional and may be grouped into sets which can also be required or optional. A parameter specifies a name to be used in the query string and can refer to a definition of its format and abstract purpose.

Service

A Service represents a web application or web service that makes resources available typically via HTTP.

The following properties are applicable to Service components:

baseUri - a string that represents the root URI of the service. Interactions supported by the service will be located by appending path fragments and query parameters to this value. This property is required and must occur once only.
homepage - a reference to a web page deemed to be the home page of the service for human readers. This property may occur zero or one times.
supports - a reference to an WebInteraction component that is supported by the Service. This property is optional and may occur any number of times.

WebInteraction

An WebInteraction component represents an operation or action that is supported by a Service.

The following properties are applicable to WebInteraction components:

method - a string that represents an HTTP method (e.g. GET, POST etc.). The value of this property must be an uppercase string. This property is required and must occur once only.
resourceType - a reference to a ResourceType component which represents the type of web resource that this WebInteraction is dealing with. This property may occur zero or one times.
representationType - a reference to a RepresentationType component which describes a representation understood by this Web Interaction. This property is optional and may occur any number of times.
uriPath - a string that represents a path fragment that should be appended to the Service baseUri property in order to locate the Web Interaction. This property may occur zero or one times.
requiredParameter - a reference to a Parameter component that represents a parameter that must be supplied as part of this Web Interaction. This property is optional and may occur any number of times.
optionalParameter - a reference to a Parameter component that represents a parameter that may optionally be supplied as part of this Web Interaction. This property is optional and may occur any number of times.
anyParametersFrom - a reference to a ParameterSet component that represents a group of parameters any of which may optionally be supplied as part of this Web Interaction. This property is optional and may occur any number of times.
allParametersFrom - a reference to a ParameterSet component that represents a group of parameters all of which must be supplied as part of this Web Interaction. This property is optional and may occur any number of times.
oneParameterFrom - a reference to a ParameterSet component that represents a group of parameters one of which must be supplied as part of this Web Interaction. This property is optional and may occur any number of times.
allOrNoParametersFrom - a reference to a ParameterSet component that represents a group of parameters that must either all be supplied or all omitted as part of this Web Interaction. This property is optional and may occur any number of times.

ResourceType

A ResourceType represents the abstract type of HTTP resource that a WebInteraction is dealing with. Resource here refers to the RFC2616 concept of a network object or service that can be identified by a URI.

The ResourceType component has no special properties.

RepresentationType

A RepresentationType represents a type of representation that is understood by the Service and is supported in a particular Web Interaction. Representation here refers to the RFC2616 concept of a data representation of a resource.

For Interactions using the GET method, the RepresentationTypes listed will typically be alternate response formats that can be supplied by the WebInteraction and selected via standard HTTP practice. For POST based Interactions, the RepresentationTypes listed will be those accepted by the Web Interaction.

The following properties are applicable to RepresentationType components:

mediaType - a string that represents an RFC media type appropriate for the type of representation. This property may occur zero or one times.
schemaType - a reference to an XML Schema type that describes the format of the representation. This property may occur zero or one times.

Parameter

A Parameter represents a query parameter used by a Web Interaction.

The following properties are applicable to Parameter components:

name - a string representing the name of the parameter. When constructing the URI for the WebInteraction the name property is used to build standard HTML name/value pairs in the query string part of the URI. This property is required and must occur once only.
schemaType - a reference to an XML Schema type that describes the format of the parameter's value. This property may occur zero or one times.
purpose - a reference to a Purpose component that represents the abstract purpose of this parameter. This property may be used to infer common behaviour across different Service Interactions. This property may occur any number of times.
defaultValue - a string representing a value that must be supplied whenever the client does not have an existing value corresponding to the parameter. This property may occur zero or one times.
fixedValue - a string representing a value that must be supplied whenever this parameter is used. If present, no other value must be used with this parameter. This property overrides any other value specification for the parameter. This property may occur zero or one times.

ParameterSet

A ParameterSet component represents a group of Parameter components. A Parameter can be a member of any number of ParameterSet components. Membership of a ParameterSet does not imply any form of relationship between Parameters.

The following properties are applicable to ParameterSet components:

parameter - a reference to a Parameter component that represents a member of the Parameter Set. This property may occur any number of times.

Purpose

A Purpose component represents an abstract concept that is associated with a Parameter. Parameters that share the same Purpose can be inferred to be equivilent despite any syntactic differences.

The Purpose component has no special properties.

General Properties

The following properties may be used with any component:

label - a string that serves as documentation for the component by providing a short name suitable for presenting in a list or menu. This property can be supplemented with an xml:lang attribute to provide labels in different languages. This property is optional and may occur any number of times with any combination of languages.
comments - a string that serves as documentation for the component by providing a longer comment suitable for presenting as a reminder of the components purpose. This property can be supplemented with an xml:lang attribute to provide labels in different languages. This property is optional and may occur any number of times with any combination of languages.
docs - a reference to a web page that provides full documentation for the component. This property is optional and may occur any number of times.

Summary of Component Properties

Property	Applies To	Value Type	Occurrence
homepage	Service	reference to web page	0 or 1
baseUri	Service	string	1
provides	Service	reference to WebInteraction	any number
method	WebInteraction	string	1
label	Any Component	string	any number
comments	Any Component	string	any number
docs	Any Component	reference to web page	any number
resourceType	WebInteraction	reference to ResourceType	0 or 1
representationType	WebInteraction	reference to RepresentationType	any number
uriPath	WebInteraction	string	0 or 1
requiredParameter	WebInteraction	reference to Parameter	any number
optionalParameter	WebInteraction	reference to Parameter	any number
mediaType	RepresentationType	string	0 or 1
schemaType	Parameter, RepresentationType	reference	0 or 1
name	Parameter	string	1
purpose	Parameter	reference to Purpose	any number
defaultValue	Parameter	string	0 or 1
fixedValue	Parameter	string	0 or 1
anyParametersFrom	WebInteraction	reference to ParameterSet	any number
allParametersFrom	WebInteraction	reference to ParameterSet	any number
oneParameterFrom	WebInteraction	reference to ParameterSet	any number
allOrNoParametersFrom	WebInteraction	reference to ParameterSet	any number
parameter	ParameterSet	reference to Parameter	any number

XML Serialization

The XML serialization of WAIF (WAIF/XML) is a sane profile of RDF/XML strictly conforming to the XML Schema described later in this document. This simplifies processing by plain XML tools such as XPath and SAX by providing a deterministic document structure. Tools that store WAIF natively as RDF may utilize any RDF construct internally but must omit these when serializing as WAIF/XML. Other RDF-specific serialisation formats are possible and are not subject to the same processing constraints. However, all serializing WAIF tools that must support WAIF/XML output in order to provide interoperability.

No namespace URI has been assigned yet. All samples use http://example.com/wd# temporarily.

When accessed via HTTP, WAIF XML documents should be served with an application/rdf+xml media type. If unable to serve as application/rdf+xml, servers should use application/xml as an alternative. Servers must not use a media type of text/xml when serving WAIF XML.

Cross-Referencing Components

Components can be identified with a URI. The identifying URI must consist of the document location followed by a hash symbol (#), followed by an identifier name conforming to the XML NC-NAME production.

In the XML serialisation, RDF constructs are used only for cross-referencing WAIF components. The following attributes from the RDF namespace are used:

rdf:ID assigns a unique identifier for the component. The value MUST match the XML NC-NAME production and MUST be unique within the document. In other words, there must be only one rdf:ID attribute with any given value within a single document. This attribute is optional, but components without such an attribute cannot be cross-referenced. Informally this attribute is similar to the name attribute of anchor elements in HTML documents.
rdf:resource denotes a reference to a component labelled with an rdf:ID attribute. This reference may be to a component defined within the same document or to another document. The value of this attribute is a relative URI reference interpreted according to any base URI in effect. Informally this attribute functions in a similar way to the href attribute of anchor elements in HTML documents. Intra-document references can be constructed by prefixing the target rdf:ID value with a hash (#), e.g. '#component'

For example, in a document located at http://example.com/sample1.xml, the following Service component is described:

 
<wf:Service rdf:ID="foo">
  <wf:label>foo service</wf:label>
</wf:Service>

In this case the URI for the component would be http://example.com/sample1.xml#foo

Components and other resources such as web pages can be referred to using reference properties. The value of a reference property is a URI reference which can resolve to the component or web page.

In the XML serialization of WAIF, the reference is specified using the rdf:resource attribute on the property.

For example, in a document located at http://example.com/sample2.xml, the following WebInteraction component is described:

 
<wf:WebInteraction rdf:ID="action">
  <wf:label>an interaction</wf:label>
</wf:WebInteraction >

This WebInteraction component could be referred to within the same document using the rdf:resource attribute, e.g.

 
<wf:Service rdf:ID="foo">
  <wf:label>foo service</wf:label>
  <wf:supports rdf:resource="#action"/>
</wf:Service>

No other elements or attributes from the RDF namespace are allowed in the XML serialisation of WAIF documents.

Notes

These notes are areas that I want to expand upon in possible future versions but haven't had the time to evaluate properly yet.

Constructing Interaction URIs

To determine the URI for an Interaction:

Take the baseURI of the Service being used
Append the value of the Interaction's uriPath property, if any
If the Interaction has parameters, append a question mark
For each parameter append the parameter's name, an equals sign and the value to be used (all escaped as per URI rules)

Faults

This specification does not attempt to describe application-specific faults. Services utilizing the Web Architecture will respond to error conditions with standard HTTP response codes and these are well-described by the relevant specifications.

Comparison with WSDL

Existing web service description formats such as WSDL do not address the goals outlined at the start of this document. For comparison, in WSDL:

it is impossible to assign a URI to a resource such as a web page, or XML document. Instead, a URI is assigned for the service as a whole.
a new vocabulary of endpoints, interfaces, bindings etc have to be mapped onto the existing web terminology of URIs, resources and representations.
it is difficult to describe the interface to a service independent of the service itself, e.g. an appplication that can be deployed independently in many places such as blogging software
it is impossible to coordinate any kind of semantics of service parameters
it is difficult to reuse definitions within a document or from other documents

Examples

The following is a description of six API methods provided by del.icio.us

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rdf:RDF [
  <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#">
]>
<rdf:RDF 
  xmlns:wf="http://example.com/wf#" 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://example.com/wf# http://iandavis.com/2005/web-description/waif.xsd">

  <wf:Service rdf:ID="DeliciousService">
    <wf:label>del.icio.us</wf:label>
    <wf:baseUri>http://del.icio.us/api/</wf:baseUri>
    <wf:homepage rdf:resource="http://del.icio.us/"/>
    <wf:provides rdf:resource="#Dates"/>
    <wf:provides rdf:resource="#Tags"/>
    <wf:provides rdf:resource="#Posts"/>
    <wf:provides rdf:resource="#RecentPosts"/>
    <wf:provides rdf:resource="#AllPosts"/>
    <wf:provides rdf:resource="#UpdateDate"/>
  </wf:Service>

  <wf:WebInteraction rdf:ID="Dates">
    <wf:comment xml:lang="en">returns a list of dates with the number of posts at each date.</wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>posts/dates</wf:uriPath>
    <wf:resourceType rdf:resource="#DateList"/>
    <wf:representationType rdf:resource="#DateListXml"/>
    <wf:optionalParameter rdf:resource="#TagParameter"/>
  </wf:WebInteraction>

  <wf:WebInteraction rdf:ID="Tags">
    <wf:comment xml:lang="en">returns a list of tags the user has used.</wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>tags/get</wf:uriPath>
    <wf:resourceType rdf:resource="#TagList"/>
    <wf:representationType rdf:resource="#TagListXml"/>
  </wf:WebInteraction>

  <wf:WebInteraction rdf:ID="Posts">
    <wf:comment xml:lang="en">
      returns a list of posts on a given date, filtered by tag. if no 
      date is supplied, most recent date will be used
    </wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>posts/get</wf:uriPath>
    <wf:resourceType rdf:resource="#PostList"/>
    <wf:representationType rdf:resource="#PostListXml"/>
    <wf:optionalParameter rdf:resource="#TagParameter"/>
    <wf:optionalParameter rdf:resource="#DateParameter"/>
  </wf:WebInteraction>

  <wf:WebInteraction rdf:ID="RecentPosts">
    <wf:comment xml:lang="en">
      returns a list of most recent posts, possibly filtered by tag, maxes out at 100.
    </wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>posts/recent</wf:uriPath>
    <wf:resourceType rdf:resource="#PostList"/>
    <wf:representationType rdf:resource="#PostListXml"/>
    <wf:optionalParameter rdf:resource="#TagParameter"/>
    <wf:optionalParameter rdf:resource="#CountParameter"/>
  </wf:WebInteraction>

  <wf:WebInteraction rdf:ID="AllPosts">
    <wf:comment xml:lang="en">
      returns all posts. use sparingly. call update function first
      to see if you need to fetch this at all
    </wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>posts/all</wf:uriPath>
    <wf:resourceType rdf:resource="#PostList"/>
    <wf:representationType rdf:resource="#PostListXml"/>
    <!-- multiple representations allowed -->
    <wf:optionalParameter rdf:resource="#TagParameter"/>
  </wf:WebInteraction>

  <wf:WebInteraction rdf:ID="UpdateDate">
    <wf:comment xml:lang="en">
      returns the last update time for the user. combine this
      with posts/all to see if the data returned has changed
      since last fetch. this call is pretty lightweight. don't
      call posts/all unless you have to.
    </wf:comment>
    <wf:docs rdf:resource="http://del.icio.us/doc/api"/>
    <wf:method>GET</wf:method>
    <wf:uriPath>posts/update</wf:uriPath>
    <wf:resourceType rdf:resource="#Date"/>
    <wf:representationType rdf:resource="#DateXml"/>
  </wf:WebInteraction>

  <wf:ResourceType rdf:ID="DateList">
    <wf:comment xml:lang="en">A list of dates on which items have been tagged</wf:comment>
  </wf:ResourceType>

  <wf:ResourceType rdf:ID="TagList">
    <wf:comment xml:lang="en">A list of tags used by the user</wf:comment>
  </wf:ResourceType>

  <wf:ResourceType rdf:ID="PostList">
    <wf:comment xml:lang="en">A list of posts made by this user</wf:comment>
  </wf:ResourceType>

  <wf:ResourceType rdf:ID="Date">
    <wf:comment xml:lang="en">A date</wf:comment>
  </wf:ResourceType>

  <wf:RepresentationType rdf:ID="DateListXml">
    <wf:comment xml:lang="en">The response used for lists of dates</wf:comment>
    <wf:mediaType>application/xml</wf:mediaType>
  </wf:RepresentationType>

  <wf:RepresentationType rdf:ID="TagListXml">
    <wf:comment xml:lang="en">The response used for lists of tags</wf:comment>
    <wf:mediaType>application/xml</wf:mediaType>
  </wf:RepresentationType>

  <wf:RepresentationType rdf:ID="PostListXml">
    <wf:comment xml:lang="en">The response used for lists of posts</wf:comment>
    <wf:mediaType>application/xml</wf:mediaType>
  </wf:RepresentationType>

  <wf:RepresentationType rdf:ID="DateXml">
    <wf:comment xml:lang="en">The response used for item lookups</wf:comment>
    <wf:mediaType>application/xml</wf:mediaType>
  </wf:RepresentationType>

  <wf:Parameter rdf:ID="TagParameter">
    <wf:comment xml:lang="en">
        The name of a tag
    </wf:comment>
    <wf:name>tag</wf:name>
    <wf:schemaType rdf:resource="&xsd;string"/>
  </wf:Parameter>

  <wf:Parameter rdf:ID="DateParameter">
    <wf:comment xml:lang="en">
      A date to filter by
    </wf:comment>
    <wf:name>dt</wf:name>
    <wf:schemaType rdf:resource="&xsd;string"/><!-- ISO date -->
  </wf:Parameter>

  <wf:Parameter rdf:ID="CountParameter">
    <wf:comment xml:lang="en">
        number of items to retrieve
    </wf:comment>
    <wf:name>count</wf:name>
    <wf:schemaType rdf:resource="&xsd;positiveInteger"/>
  </wf:Parameter>

</rdf:RDF>

Amazon - two of Amazon's ecommerce web service operations are described (ItemLookup and SimilarityLookup). This is a fairly comprehensive example demonstrating required parameters, fixed value parameters, parameter sets and referencing XML Schema types.
Talis Prism and Innopac, both library OPAC services are partially described. These demonstrate two different web services conceptually providing the same function. The syntax of each service are wildly different but the parameters are related by sharing common purpose properties defined in opac.rdf. Given knowledge that the user has an ISBN and wishes to perform a search books matching that ISBN it should be possible to use these descriptions to determine how to construct the HTTP request for both types of software.

XML Schema

The schema is split into two parts: WAIF namespaced elements and a reduced RDF attributes schema for the two RDF attributes used in this specification.

RDF Schema

To follow...

Acknowledgements

I have drawn inspiration from the following specifications and proposals:

WADL by Marc Hadley
WDL by Dave Orchard
NSDL by Norman Walsh
RDF Forms by Mark Baker
WRDL by Paul Prescod
SMEX-D by Tim Bray

References

...incomplete...

RFC2616: IETF RFC 2616: Hypertext Transfer Protocol - HTTP/1.1, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, June 1999, http://www.ietf.org/rfc/rfc2616.txt.
WEBARCH: Architecture of the World Wide Web, Volume One, I. Jacobs, N. Walsh , et. al., Editors, W3C Recommendation, 15 December 2004, http://www.w3.org/TR/2004/REC-webarch-20041215/.
XML10: Extensible Markup Language (XML) 1.0 (Third Edition), F. Yergeau, J. Paoli, C. M. Sperberg-McQueen, et. al., Editors, W3C Recommendation, 04 February 2004, http://www.w3.org/TR/2004/REC-xml-20040204
XMLNS: Namespaces in XML 1.1, R. Tobin, D. Hollander, A. Layman, et. al., Editors, W3C Recommendation, 04 February 2004, http://www.w3.org/TR/2004/REC-xml-names11-20040204.