Widgets 1.0: URI Scheme

Abstract

Many specifications in the Web stack depend on a context being defined that includes a current URI. This is easily provided for documents retrieved over HTTP, or from the local file system, but is currently undefined for documents extracted from within a widget package. Such a limitation has a number of implications which this document intends to address.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This is the 18 June 2009 First Public Working Draft version of the "Widgets 1.0: URI Scheme" specification. The purpose of this draft is to give external interested parties an opportunity to publicly comment on a URI scheme for use inside widgets or other such applications of web technology that do not run on the web.

This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. The public is encouraged to send comments to the Web Apps Working Group's public mailing list public-webapps@w3.org (archive). See W3C mailing list and archive usage guidelines. A detailed list of changes from the previous version is also available from the W3C's CVS server.

Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

Note: User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardisation.

Table of Contents

• 1 Introduction
• 2 Not in this specification
• 3 Requirements
• 4 The widget URI scheme
  • 4.1 Syntax
  • 4.2 Base URI and Relative URI Reference Resolution
  • 4.3 Usage as Origin
  • 4.4 Mapping widget URIs to Widget Resources
• Acknowledgments
• Normative References
• Informative References

1 Introduction

This specification defines the widget URI scheme for use inside widgets or other such applications of web technology that do not run on the web.

2 Not in this specification

There are many different efforts that have specified URI schemes to access the content of Zip archives, or endeavour to do so. While these efforts have merit, and while W3C Widgets rely on Zip as a packaging format, the use cases that this specification addresses are radically different. In fact, it is possible that both this scheme and another defined to access Zip archive content would be used jointly, with little or no overlap in functionality.

The scheme defined in this specification could be used to implement inter-widget communication, but that is outside the scope of this current document.

3 Requirements

Must allow addressing resources inside a widget

The scheme must be able to address Zip relative paths as defined in the Widgets: Packaging and Configuration [Widgets-PC] specification.

Must allow resolving relative URL references inside a widget

It must be possible for a document inside a widget to use a relative reference to another without any specific knowledge of the scheme being used. For instance, if a document located at dahuts/dextrogyrous.html features a link to levrogyrous.html that link must resolve to dahuts/levrogyrous.html.

Must not allow addressing resources outside a widget

There is no requirement on how widgets are stored and potentially unpacked within a given user agent, but irrespective of how that is performed, including for instance by storing the unpacked widget on the local file system, it must be impossible to address resources outside of the widget using this scheme.

Must provide an origin URI for widget-contained documents

Many mechanisms in widgets (e.g. cookies, local storage, XMLHttpRequest) key off the URI or part thereof from which they are used. Since widgets are for all intents and purposes local applications that do not have an origin, this scheme must provide integration with these mechanisms.

Must be independent of any file system

Addressing based on this scheme must only map onto Zip relative paths and remain independent of any file system on which the widget may be stored.

Must not conflict with existing URI usage in web runtimes

This scheme must enable maximal reuse of existing web runtimes, and therefore not conflict with the architecture of existing URI usage.

Must not require widget developers to be aware of it for basic tasks

Using this scheme as the URI of resources inside a widget must not force widget developers to be aware of its existence for simple tasks such as linking between widget resources, and would ideally not require such knowledge for advanced tasks either.

Must be compatible with the Widgets 1.0: Packaging and Configuration localisation model

Widgets 1.0: Packaging and Configuration [Widgets-PC] defines a runtime localisation model that allows URI references to be resolved to different resources depending on the user agent's locale settings, this URI scheme must enable such resolution.

A careful review of existing schemes has found that none matches the needs above.

4 The widget URI scheme

The widget URI scheme is primarily intended for usage with URIs that are synthesised by the user agent as it absolutises URI references found in documents contained in widgets or defines base URIs for them.

Note: Note that using widget URIs directly when authoring content is discouraged, and authors should stick to using schemeless relative URI references.

As a widget is initialised the user agent may generate an identifier that will be used as the authority part of the widget absolute URI. As of this specification that identifier has no semantics and must be ignored while resolving the URI reference to a representation. If present, the authority will be said to be opaque. Future versions of this specification may define more precise syntax and semantics for this opaque authority.

4.1 Syntax

The ABNF syntax [ABNF] for widget URIs is as follows:

widget-URI  = "widget:" "//" [ authority ] "/" zip-rel-path [ "?" query ] [ "#" fragment ]

Where the zip-rel-path non-terminal is defined in the Widgets 1.0: Packaging and Configuration specification [Widgets-PC] and the others reference RFC 3986 [URI].

Example widget URIs could thus be: widget://beefdead/dahuts/sightings/french-alps.svg or widget:///secret-identities/marcosc/batman.foaf

4.2 Base URI and Relative URI Reference Resolution

The base URI for a resource contained in a widget is constructed by concatenating widget://, optionally the opaque authority, and the Zip relative path to the resource.

Resolution of relative URI references is performed using the mechanism appropriate for the language in the context of which the reference appears, typically following chapter 5 of [URI] or possibly [HTML5].

4.3 Usage as Origin

Mapping from a widget URI to an origin is depends on the rules defined for this purpose by the document type being referenced.

Within an HTML 5 context [HTML5], the origin of a resource inside a widget is defined by an extension to the HTML5 origin algorithm. If the <scheme> component obtained after step 5 is widget, then the tuple that is returned is "widget", optionally the opaque authority part, and nothing for the <port> component. Furthermore, the ASCII and Unicode serialisations for widget origins are as defined in HTML 5 for other schemes, except that the port is always considered to be the default one for the given protocol.

4.4 Mapping widget URIs to Widget Resources

The process of resolving a widget URI to a resource within a given widget is as follows:

1. Let uri be the URI reference to resolve. If uri is a relative URI reference, make it absolute as defined in [URI].
2. Let path be the path component of uri. Remove the leading U+002F SOLIDUS ("/") from path.
3. Run the algorithm defined in Rule for finding a file within a widget package using path as its parameter. What it returns is the file entry being sought.

Note that neither the query nor the fragment parts of the widget URI are used in the resolution process. They must nevertheless be kept as part of the URI and processed according the rules defined by the content type being referenced.

Acknowledgments

The following people were instrumental in producing this specification:

Art Barstow, Marcos Caceres, Thomas Roessler, Larry Masinter, and Jere Kapyaho.

Normative References

[HTML5]

HTML 5. Ian Hickson et al. W3C Working Draft 23 April 2009.

[URI]

Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005.

[Widgets-PC]

Widgets 1.0: Packaging and Configuration, M. Caceres. W3C, December 2008.

[ABNF]

Augmented BNF for Syntax Specifications: ABNF, RFC5234. D. Crocker and P. Overell. January 2008.

Informative References

[HTTP]

Hypertext Transfer Protocol -- HTTP/1.1. RFC 2616, R. Fielding, et al. June 1999.

[HTTPS]

HTTP Over TLS. RFC 2818, E. Rescorla. May 2000.