Widgets 1.0: Widget URIs

W3C Working Draft 08 October 2009

This Version:
Latest Published Version:
Latest Editor's Draft:
Previous version:
Robin Berjon, Vodafone


This specification defines the widget URI scheme that is used to address resources inside a widget package [WIDGETS].

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 http://www.w3.org/TR/.

This document was published by the Web Applications WG as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). The Last Call period ends 10 November 2009. All feedback is welcome.

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.

This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.

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.

Table of Contents

1. Introduction

This section is non-normative.

Resources inside a widget package are identified and located using a method that is specific to widgets technology. Widget URIs reflect this by providing these specific locators with their own syntax so that resources in widget packages can be readily identified.

In general, authors of widget content use relative URI references. Widget URIs are therefore primarily synthesised by the user agent as it absolutises URI references found in documents contained in widgets packages.

1.1 Not in this specification

There are many different efforts specifying URI schemes to access the content of Zip archives and formats based on Zip, or endeavour to do so. While these efforts have merit, and while W3C Widgets is one such format, the use cases that this specification addresses are substantially different: rather than identify packaged resources from the outside, widget URIs identify them only on the inside of a package, irrespective of that package's own location. 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.

Uniquely identifying widgets, or multiple instances of the same widget package, as well as enabling inter-widget communication are also outside the scope of this document.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

There are three classes of products that can claim conformance to this specification:

3. Definitions

Throughout this specification, wherever the term URI [URI] is used, it can be replaced interchangeably with the term IRI [RFC3987]. All widget URIs are IRIs, but the term URI is more common and was therefore preferred for readability.

4. Widget URIs

Widget URIs are URIs as per [URI] and [RFC3987], with specific aspects described in the following sections.

4.1 Syntax

A valid widget URI must adhere to the IRI grammar rule from [RFC3987], and its scheme component must be the case-insensitive string "widget".

A valid widget URI reference must adhere to the IRI-reference grammar rule from [RFC3987], and if it is an absolute URI reference then it must be a valid widget URI.

A producer must generate URIs that are normalised according to chapter 5.3.2. "Syntax-Based Normalization" of [RFC3987].

A consumer must be able to parse any valid widget URI.

Note that assigning semantics or interpretation to the query or fragment components is outside the scope of this specification. The ways in which they are used depends on the content types that they are applied to, or what executable script decides to do with them.

Example widget URIs could thus be: widget://beefdead/dahuts/sightings/alpes-françaises.svg (assuming the generated opaque authority is beefdead) or widget:///secret-identities/marcoscàceres/batman.foaf if there is no authority component.

4.2 Authority

A producer may include an authority component in URIs. If present, the authority component is said to be opaque, meaning that the authority component has a syntax as defined by [RFC3987] but that the authority component is devoid of semantics.

A consumer should ignore the authority component, when present.

4.3 Base URI and Relative URI Reference Resolution

When computing the base URI for a resource contained in a widget package a producer must concatenate widget://, optionally the opaque authority, the U+002F SOLIDUS (/) character, and the Zip relative path to the resource.

When resolving a relative URI references against a base URI, a consumer must use the mechanism defined in chapter 5.2. of [URI].

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

4.4 Mapping widget URIs to files within a widget package

To resolve a widget URI to a resource within a given widget package a consumer must apply the following algorithm (or one that guarantees the same result):

  1. Let uri be the URI reference to resolve. If uri is a relative URI reference, make it absolute as defined in chapter 5.2. of [URI].
  2. Run the algorithm defined in Rule for finding a file within a widget package using the path component as its parameter (excluding any query or fragment components). Return the result, file or error, that was returned.

A. Usage as Origin

In some contexts one needs to map a URI into an origin, for instance in the [HTML5] HTML5 origin algorithm.

Mapping from a widget URI to an origin takes place as follows:

  1. Let url be the valid widget URI for which the origin is being determined.
  2. Parse url with a consumer.
  3. Let scheme be widget.
  4. If url contains an opaque authority, let host be its value. Otherwise, generate a unique value that will always be the same for a given widget package and that no two widget packages will share and assign it to host.
  5. Let port be null.
  6. Return the tuple (scheme, host, port).

B. Requirements

This section is non-normative.

Must allow addressing resources inside a widget package
The scheme must be able to address Zip relative paths as defined in the Widgets: Packaging and Configuration [WIDGETS] specification.
Must allow resolving relative URL references inside a widget package
It must be possible for a document inside a widget package 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 package 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] 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.

C. Acknowledgments

This section is non-normative.

The following people were instrumental in producing this specification:

Art Barstow, Marcos Caceres, Thomas Roessler, Larry Masinter, Marcin Hanclik, Mark Baker, and Jere Kapyaho.

D. References

D.1 Normative references

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. Internet RFC 3987. URL: http://www.ietf.org/rfc/rfc3987.txt
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifiers (URI): generic syntax. January 2005. Internet RFC 3986. URL: http://www.ietf.org/rfc/rfc3986.txt
Marcos Caceres. Widgets 1.0: Packaging and Configuration. 23 July 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20090723/

D.2 Informative references

Ian Hickson; David Hyatt. HTML 5. 23 April 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-html5-20090423/