WebCap: Web-based Capability List File Format and Model

Abstract

This document defines WebCap, a simple language for explicitly
grouping sets of URIs having a specific relationship to one another for
a particular purpose.

1 Introduction

WebCap is a file format and a data model for organizing and exposing
URIs. WebCap provides a way for users to bundle related URIs together in a
way that takes advantage of the hierarchical form of those URIs when it is
available, in order to make managing URIs more like managing names in a
filesystem. URIs are managed in bundles in order to provide the user with
a way to process those URIs across contextual boundaries based upon the
bundling relationship.

2 Use Cases

2.1 Expressing Intended Access Priveleges on a Set of Files

Alice has a set of files on her desktop computer, some of which
she would like to directly publish on the Internet. Each of these files
has at least one URI–its local file URI. Alice
would like to annotate each of these URIs with an additional URI
reference indicating its web-accessible URL. She would like to do this
without specifying a full URI for each annotation, but would instead
like to organize them hierarchically as her files are organized. When
Alice adds a new name to her list of published items, she would like to
provide the name in as simple a manner as possible, so that full URIs
for both the file and its publishing location are based upon the context
of her chosen organizational scheme.

3 Examples

The following WebCap document might be used to describe both
equivalent http URLs as well as working copy URLs
for a (small) source code repository, part of which should be published
(or exposed) in a web environment.

The WebCap document above expresses the following 11 URI mapping
bundles. The first URI in each mapping bundle is the stable or
global identifier for the resource, the second URI
is the local identifier for the resource, and the
third (when it exists) is the exposed identifier
for the resource. When it exists, this third URI indicates that it is a
member of the capabilities set provided by the document; in this case, the
author may intend that the specific capability is that web users can read
the resource using the exposed URI. Also, within each URI mapping bundle,
earlier URIs have the relationship
http://www.w3.org/2002/07/owl#sameAs with later URIs.
(According to the OWL ontology, this means that these URIs represent the
same resource.)

svn://example.org/project/trunk/

file:///home/john/development/project/

http://example.org/project/

svn://example.org/project/trunk/source/

file:///home/john/development/project/source/

http://example.org/project/source/

svn://example.org/project/trunk/source/util.xslt

file:///home/john/development/project/source/util.xslt

http://example.org/project/source/util.xsl

svn://example.org/project/trunk/source/convert.xslt

file:///home/john/development/project/source/convert.xslt

http://example.org/project/source/convert.xsl

svn://example.org/project/trunk/tests/

file:///home/john/tmp/project/tests/

svn://example.org/project/trunk/tests/test1/

file:///home/john/tmp/project/tests/test1/

svn://example.org/project/trunk/tests/test1/input.xml

file:///home/john/tmp/project/tests/test1/input.xml

svn://example.org/project/trunk/tests/test1/output.xml

file:///home/john/tmp/project/tests/test1/output.xml

svn://example.org/project/trunk/tests/test2/

file:///home/john/tmp/project/tests/test2/

svn://example.org/project/trunk/tests/test2/input.xml

file:///home/john/tmp/project/tests/test2/input.xml

svn://example.org/project/trunk/tests/test2/output.xml

file:///home/john/tmp/project/tests/test2/output.xml

This WebCap document could then be used to generate a number of XML
Catalog documents (depending on the direction of URI resolution desired)
as well as an "equivalent" RDF/XML file (or RDF serialized to another
format, such as TriX).

4 WebCap Document Format

WebCap documents must be well-formed XML documents. WebCap elements
defined in this specification have
ahttp://infinitesque.net/2006/ns/capabilities/ as their XML
Namespace URI, and this specification uses cap to
represent this XML Namespace URI in QNames where the context does not
otherwise provide this mapping.

4.1 Root cap:capabilities Element

The root element of a WebCap document is the
cap:capabilities element. First, it contains a
cap:relationship element that describes the intended RDF
relationship that exists between entries in a mapped bundle. Next, it
contains an optional cap:description element that allows a
user to enter a colloquial description of the nature of the mapping
contained in the current document. Finally, the root element contains a
sequence of one or more cap:map elements that provide the
mapped URI bundles.

4.2 cap:relationship Element

The cap:relationship allows the user to define an RDF
property between resources identified within mapped bundles in the
current WebCap document. This element SHOULD contain a single child
element; the RDF
URI reference for the property to use is determined from the
QName of this element as described in section
2.1 of the RDF/XML Syntax Specification. If A and B are any two
members of a mapped bundle in the current document, this RDF property is
considered to hold between those two members if B comes after A in
document order. For this reason, the RDF property defined within the
cap:relationship element SHOULD be a transitive
property.

This single property is intended to describe how the members of
mapped bundles within the current document are related, which should be
homogenous within a given WebCap document. In order to make additional
statements about these resources and their relationships, users should
use distinct WebCap documents or more powerful applications, such as
RDF.

4.3 cap:description Element

The cap:description element may have arbitrary content;
its purpose is to provide a location for a human-readable description of
the purpose of the current WebCap document. We suggest using either
plain text or XHTML content within this description.

4.4 cap:map Element

The cap:map defines a single URI mapping bundle within
a WebCap capability list and potentially provides a basis for other
bundles. This element may contain either a cap:all element or
a selection of no more than one each of cap:local,
cap:global, and cap:exposed elements, which
designate the members of the current mapping bundle. This element may
also contain any number of additional cap:map elements; these
define additional mapping bundles and do not contribute to the current
mapping bundle.

Applications SHOULD ignore other children of the
cap:map element in the
ahttp://infinitesque.net/2006/ns/capabilities/ namespace, and
SHOULD treat children of the cap:map in other namespaces as
additional entries in the current mapping bundle. Other specifications
SHOULD define the intended meaning of the URIs in such entries.

4.5 cap:local, cap:global, and
cap:exposed Elements

These elements directly designate one URI component of the mapping
bundle for the parent cap:map. Each of these elements MUST be
a child of a cap:map element, and the contents of each of
these elements MUST be a shorthand reference
(which is syntactically the same as a relative reference). To determine
the effective URI for this component, follow these steps:

Let the parent cap:map element of the current
element be the current map. If the parent of the current map is
another cap:map element, let that element be the parent
map.

If the parent map contains a child element with the same
QName as the current element, resolve the value of the current
element against the component URI of that element and return
that value.

Otherwise, if the parent map contains a child element with
the name cap:all, resolve the value of the current
element against the component URI of that element and return
that value.

Otherwise, resolve the value of the current element
against the Base URI (computed as described in the XML Base
recommendation [XMLBase]) of the current
element and return that value.

Otherwise, resolve the value of the current element against
the Base URI (computed as described in the XML Base recommendation
[XMLBase]) of the current element and return that
value.

A cap:local URI SHOULD be considered to be a locally
available identifier for a resource without an expectation of global
uniqueness (such as a URI using the file
scheme). A cap:global URI SHOULD be considered to be a
globally unique identifier for a resource without an expectation of any
retrieval semantics. A cap:exposed URI SHOULD be considered
to be the globally unique identifier for a resource that is or will be
available for the defining capability offered by the current WebCap
document.

4.6 cap:all Element

The cap:all element is shorthand for designating
several URI components at once. This element MUST be the child of a
cap:map element, its current map, and the current map MUST be
the child of another cap:map element, the parent map. The
contents of this element MUST be a shorthand
reference. A cap:all element is equivalent to a
sequence of the same cap:local, cap:global, and
cap:exposed elements that are children of the parent map,
with their contents all equal to the contents of this element.

5 For the Future

This section describes ideas for enhancement in future versions of
this specification.

This section is non-normative.

Allow more than one of an element with a given (namespace,
local-name) pair within a map element. In particular,
determine the relationship semantics and the resolution mechanism for
child maps in such a case.

Allow an info element within a map for
metadata purposes.

Provide a mechanism for including and/or referencing other
WebCap documents from a given WebCap document.

Provide a Relax NG schema for WebCap documents.

Add additional ways for formally describing the purpose of a
given WebCap document.

Define what errors mean and how they ought to be handled.

grounding URI

A grounding URI has the same syntax as a
URI as defined in section 3 of RFC 3986 [RFC3986], and can be used to resolve
shorthand references.

shorthand reference

A shorthand reference has the same syntax as a
relative-ref as defined in section 4 of RFC
3986 [RFC3986] and can be resolved against an
application-specific grounding URI to obtain
a URI using the mechanism defined in section 5 of RFC 3986.