Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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].
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/.
Note: The working group reached consensus to stop work on this specification. It is being published for archival reasons and is no longer being progressed along the W3C's Recommendation Track.
Publication as a Working Group Note 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. 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.
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:
Lack of HTTP response semantics: meaning that it is not possible to use, for instance, [XMLHTTPRequest] to retrieve resources from within a package.
Security/privacy issues: on Unix systems, naive implementations expose the user name as part of the path, as well as the full path on the file system to where a file is residing (e.g., "/Users/username/app/index.html"). In addition, the file URL scheme potentially opens up the ability for an attacker to address any file on the file system.
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:
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).
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).
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).This section is non-normative.
An example of a widget URI is:
widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html
Using the widget URI above, the following example shows [HTML]'s window.location using the widget URI.
<!doctype html>
<script>
//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
</script>
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
document.body.appendChild(img);
</script>
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)
process(json);
} 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");
xhr.send();
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.
A user agent is an implementation of this specification that is able to synthesize widget URIs as well as dereference them.
A package is the logical container that contains the files being addressed via the widget URI scheme (for example, a [Widgets] package).
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 / uuidWhere
path, query, fragment, and unreserved are defined in [IRI]. And, and uuid is defined in [UUID].
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].
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 |
widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html |
 instance 2 |
widget://ab52dda1-c0a8-43c1-bc76-2912307e7010/index.html |
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.
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):
widget://c1..66/example.gif?hellowidget://c1..66/example.gif?hello=foo&bar=bazwidget://c1..66/example.gif?hello#hi-thereThis 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:
If the request is not a [HTTP] GET request, return a [HTTP] 501 Not Implemented response and terminate this algorithm.
Let URI be the value of the [HTTP] Request URI.
Resolve URI into an absolute URL.
If the URI does not conform to the widgeturi ABNF, return a [HTTP] 400 Bad Request response and terminate this algorithm.
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).
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:
Let path be the path to the file being sought by the user agent.
Let potential-file be the result of attempting locate the file at path.
If potential-file is not found at the given path inside the container, return a [HTTP] 404 Not Found response.
If retrieving potential-file results in a error (e.g., the file is corrupt, locked, etc.), return a [HTTP] 500 Internal Server Error response.
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.
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.
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.