Widget URI scheme

W3C Working Draft 27 September 2011

This Version:
Latest published version:
Latest editor's draft:
Previous version:
Marcos Cáceres


This specification defines the widget URI scheme and rules for dereferencing a widget URI, which can be used to address resources inside a package (e.g., a [Widgets] package or similarly packaged application). The dereferencing model relies on HTTP semantics to return resources in a manner akin to a HTTP GET request. Doing so allows this URI scheme to be used with other technologies that rely on HTTP responses to function as intended, such as [XMLHTTPRequest].

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 is the 27 September Working Draft of the Widget URI scheme specification.

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 document was published by the Web Applications WG as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

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. 1 Introduction
  2. 2 Example of usage
  3. 3 Conformance
  4. 4 User agent
  5. 5 Package
  6. 6 Widget URI
    1. 6.1 Synthesizing a widget URI
    2. 6.2 The authority component
    3. 6.3 Query and Fragment components
    4. 6.4 Dereferencing and retrieval of files from a container
  7. Security Considerations
  8. Acknowledgements
  9. Normative references
  10. Informative references

1 Introduction

This section is non-normative.

HTML applications that run locally on a file system have traditionally relied on the file URL scheme of [RFC1738] as a document's address. Although usable in a great deal of cases, relying on the file URL scheme has several serious drawbacks:

As stated by [RFC1738]:

The file URL scheme is unusual in that it does not specify an Internet protocol or access method for such files; as such, its utility in network protocols between hosts is limited.

To overcome the above limitations of the file URL scheme, this specification standardizes the widget URI scheme and rules for dereferencing a widget URI. As a replacement technology for the file URL scheme, widget URIs serve a number of functions:

  1. A widget URI is a safer alternative to the file URL scheme, as it does not allow addressing outside a sand-boxed environment (e.g., a [Widgets] package). Additionally, it does not expose the location of a file on user's local device, nor their user name, as in the case with some Unix-based implementations (e.g., as happens on Mac Os X).

  2. A widget URI can serve as a document's address, which can serve as the origin for [HTML] or [SVG] applications. This enables the use of many features that rely on the same-origin policy (e.g., [WebStorage]) and allows a user agent to resolve the attribute values of certain DOM elements (e.g., the img element's src attribute).

  3. A widget URI provides a means to retrieve a file from within a package using similar semantics to performing a GET request over [HTTP]. This allows the Widget URI scheme to be used with other technologies that rely on HTTP responses, such as [XMLHTTPRequest]. It also allows the DOM elements to respond accordingly based on how resources are loaded or if a HTTP-like error occurs (e.g., firing an event when a resource is not found, or access is denied).

2 Example of usage

This section is non-normative.

An example of a widget URI is:


Using the widget URI above, the following example shows [HTML]'s window.location using the widget URI.

<!doctype html>
//Example using HTML's Location object
var loc =  window.location; 
console.log(loc.protocol ===  "widget:"); //true 
console.log(loc.host     ===  "c13c6f30-ce25-11e0-9572-0800200c9a66"); //true 
console.log(loc.href     ===  "widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html"); //true 
console.log(loc.origin   ===  "widget://c13c6f30-ce25-11e0-9572-0800200c9a66"); //true 
console.log(loc.pathname === "/index.html"); //true 
console.log(loc.hash     === "#example"); //true 
console.log(loc.port     === ""); //true

This example shows a widget URI being resolved in [HTML].

var img = document.createElement("img");

//the following setter triggers HTML's resolve algorithm 
img.src = "example.gif"; 

//and the expected output: 
console.log(img.src === "widget://c13c6f30-ce25-11e0-9572-0800200c9a66/example.gif") //true

//Append the image to the document

This example shows a resource within a packaged application being retrieved over [XMLHTTPRequest].

function process(data) {
 // process the resulting data 

function handler() {
 if(this.readyState == 4 && this.status == 200) {
		var text = this.responseText;
		var json = JSON.parse(text) 
 } else if (this.readyState == 4 && this.status != 200) {
      // fetched the wrong page or there was an error...

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = handler;
xhr.open("GET", "playlist.json");

3 Conformance

Everything in this specification is normative except for sections explicitly marked as non-normative, examples, and notes.

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

There is one class of product that can claim conformance to this specification: a user agent.

4 User agent

A user agent is an implementation of this specification that is able to synthesize widget URIs as well as dereference them.

5 Package

A package is the logical container that contains the files being addressed via the widget URI scheme (for example, a [Widgets] package).

6 Widget URI

A widget URI is a string that conforms to the production of the following [ABNF]:

widgeturi    = scheme "://" authority path [ "?" query ] [ "#" fragment ]
scheme       = "widget"
authority    = unreserved / uuid 
Where path, query, fragment, and unreserved are defined in [IRI]. And, and uuid is defined in [UUID].

6.1 Synthesizing a widget URI

When synthesizing a widget URI, a user agent must generate a string that conforms to widgeturi normalize it using syntax-based normalization defined in [IRI].

6.2 The authority component

The authority is a unique identifier that represents the instance of a software application that is making use of the widget URI (e.g., in the case of a [Widgets] package, it represents an instance of a widget). The identifier represented by the authority is bound to an instance of an application for the life of that application instance: that is, until that instance is destroyed (e.g., the application is uninstalled from an end-user's device).

For example, in the figure below two applications instances are created from one package, but instance has a unique authority:


instance 1
instance 2

The reason for having a unique authority is, amongst other things, to prevent multiple instances from overriding each other's data.

It is recommended that a [UUID] be used as the value of the authority component. Doing so makes it improbably that two will be alike, and also makes them hard to guess.

6.3 Query and Fragment components

The query and fragment components, when present, complement the zip-relative-path component in identifying a resource within a package. However, when dereferencing, the query and fragment components don't play any part in locating a file inside of package.

For example, the following widget URIs all return the same file (example.gif):

6.4 Dereferencing and retrieval of files from a container

This section describes how a user agent retrieves files from inside a container by dereferencing a widget URI, and how a user agent handles error conditions (e.g., when a file is not found). The purpose of this dereferencing model is to make retrieval of files from a container "look and feel" to a user agent like a HTTP request (except the request and response are performed over "widget://" instead of "http://").

For simplicity, does not define any means for cache control for content inside a container (e.g., dealing with e-tags). However, a user agent MAY implement [HTTP] cache controls if they so desire.

A response means a HTTP response and can include any HTTP response fields (e.g., the name of the user agent as the Server:) and any entity header fields the user agent deems will be helpful to a developer (e.g., Content-Length, Last-Modified, Date, Content-Encoding, Content-MD5). In the case of an error in the request (i.e., status codes 500, 501, 400, 404), the user agent MAY include a message describing the error in the [HTTP] response body.

To dereference a widget URI to a file in a widget package a user agent must apply the rules for dereferencing a widget URI.

The rules for dereferencing a widget URI are as follows:

  1. If the request is not a [HTTP] GET request, return a [HTTP] 501 Not Implemented response and terminate this algorithm.

  2. Let URI be the value of the [HTTP] Request URI.

  3. Resolve URI into an absolute URL.

  4. If the URI does not conform to the widgeturi ABNF, return a [HTTP] 400 Bad Request response and terminate this algorithm.

  5. If the URI uses the scheme 'widget', but the authority does not match the one assigned to this application, return a [HTTP] 403 Forbidden response and terminate this algorithm (i.e., prevent inter-application content access).

  6. If the user agent implements [Widgets], let potential-file be the result of running the rule for finding a file within a widget package using the path component as the argument.

    Otherwise, if [Widgets] is not supported:

    1. Let path be the path to the file being sought by the user agent.

    2. Let potential-file be the result of attempting locate the file at path.

  7. If potential-file is not found at the given path inside the container, return a [HTTP] 404 Not Found response.

  8. If retrieving potential-file results in a error (e.g., the file is corrupt, locked, etc.), return a [HTTP] 500 Internal Server Error response.

  9. If the user agent implements [Widgets], let content-type be the result of applying the rule for identifying the media type of a file using potential-file as an argument. Otherwise, use [SNIFF] to determine the content-type.

  10. Return a [HTTP] 200 OK response, with the value of content-type as the [HTTP] Content-Type header, and with potential-file as the response body.

Security Considerations

This section is non-normative.

When dereferencing a widget URI, a user agent needs to make sure that a symbolic link (or similar) inside a package does not break out of the package and end up pointing to a physical file on the end-users device.


Graphic icons used some examples of this specification were created by Ömer ÇETİN and are available for use under a Creative Commons Attribution 3.0 license.

Normative references

Augmented BNF for Syntax Specifications: ABNF. IETF.
HTML Standard (Work in progress). WHATWG.
Hypertext Transfer Protocol -- HTTP/1.1 IETF.
Key words for use in RFCs to Indicate Requirement Levels. IETF.
Internationalized Resource Identifiers (IRIs). IETF.
Media Type Sniffing (Work in progress). IETF.
A Universally Unique IDentifier (UUID) URN Namespace. IETF.
Widget Packaging and XML Configuration. W3C.

Informative references

XMLHttpRequest (Work in progress). W3C.
Uniform Resource Locators (URL) (Obselete). IETF.
Scalable Vector Graphics (SVG) Tiny 1.2 Specification. W3C.
Web Storage (Work in Progress). W3C.