Infinitesque

Subjects:

WebCap: Web-based Capability List File Format and Model

This version:

Revision 1 (2006-03-23)

Principal author:
John L. Clark
Additional contributor:
John L. Clark

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.

WebCap is related to, and draws inspiration from, RDF [RDF-XML] and XML Catalogs [XMLCatalogs].

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.

<capabilities xmlns="ahttp://infinitesque.net/2006/ns/capabilities/">
  <relationship>
    <sameAs xmlns="http://www.w3.org/2002/07/owl#"/>
  </relationship>

  <description>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>This capabilities file describes URI equivalencies for
      accessing source code for the example.org project.</p>
    </div>
  </description>

  <map>
    <global>svn://example.org/project/trunk/</global>
    <local>file:///home/john/development/project/</local>
    <exposed>http://example.org/project/</exposed>

    <map>
      <all>source/</all>

      <map>
        <global>util.xslt</global>
        <local>util.xslt</local>
        <exposed>util.xsl</exposed>
      </map>

      <map>
        <global>convert.xslt</global>
        <local>convert.xslt</local>
        <exposed>convert.xsl</exposed>
      </map>
    </map>

    <map>
      <global>tests/</global>
      <local>file:///home/john/tmp/project/tests/</local>

        <map>
          <all>test1/</all>

          <map>
            <all>input.xml</all>
          </map>

          <map>
            <all>output.xml</all>
          </map>
        </map>

        <map>
          <all>test2/</all>

          <map>
            <all>input.xml</all>
          </map>

          <map>
            <all>output.xml</all>
          </map>
        </map>
    </map>
  </map>
</capabilities>

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.

References

Dave Beckett(University of Bristol), ed. RDF/XML Syntax Specification2004-02-10.W3C Recommendation 10 February 2004

Tim Berners-Lee(World Wide Web Consortium)Roy T. Fielding(Day Software)Larry Masinter(Adobe Systems Incorporated)Uniform Resource Identifier (URI): Generic Syntax2005-01.Standards Track RFC, January 2005

Jonathan Marsh(Microsoft), ed. XML Base2001-06-27.W3C Recommendation 27 June 2001

Norman Walsh(Sun Microsystems, Inc.), ed. XML Catalogs2005-10-07.OASIS Standard V1.1, 7 October 2005

This page was last modified on 2006-03-23 00:00:00Z.

This page was first published on .

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License.

See the version of this page with comments enabled to read or add comments.