The app: URI scheme

W3C First Public Working Draft 16 May 2013

This version:
Latest published version:
Latest editor's draft:
Marcos Cáceres, Mozilla Corporation.
Bug tracker:
Issue tracker on github


This specification defines the app: URI scheme and rules for dereferencing an app: URI, which can be used to address resources inside a package (e.g., a 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 [XHR].

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 defines a URI scheme for addressing resources within a packaged web application.

This document was published by the System Applications Working Group as a First Public 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-sysapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a First Public 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 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 App URI
    1. 6.1 Synthesizing an app: 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. Privacy and Security Considerations
  8. 7 Use Cases
  9. Acknowledgements
  10. Normative references
  11. 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 app: URI scheme and rules for dereferencing an app: URI. As a replacement technology for the file URL scheme, the app: URIs serve a number of functions:

  1. An app: URI is a safer alternative to the file URL scheme, as it does not allow addressing outside a sand-boxed environment. Additionally, it does not expose the location of a file on user's local device, nor their username, as in the case with some Unix-based implementations.

  2. An app: 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. An app: 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 app: URI scheme to be used with other technologies that rely on HTTP responses, such as [XHR]. 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 for security reasons).

2 Example of usage

This section is non-normative.


running instance
Given an packaged application (ToyApp.zip), a user agent creates a running instance with a unique app: URI.

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

<!doctype html>
//Example using HTML's Location object
var loc =  window.location; 
console.log(loc.protocol === "app:"); //true 
console.log(loc.host === "c13c6f30-ce25-11e0-9572-0800200c9a66"); //true 
console.log(loc.href === "app://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html"); //true 
console.log(loc.origin === "app://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 an app: 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 === "app://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 [XHR].

function process() {
  // process the resulting data 

var xhr = new XMLHttpRequest();
xhr.onload = (hxr) => process (xhr.responseText);
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 app: URIs as well as dereference them.

5 Package

A package is the logical container that contains the files being addressed via the app: uri scheme.

6 App URI

An app: URI is a string that conforms to the production of the following [ABNF]:

appuri = scheme "://" authority path [ "?" query ] [ "#" fragment ]
scheme = "app"
authority = 1*unreserved / uuid 
Where path, query, fragment, and unreserved are defined in [IRI]. And, and uuid is defined in [UUID]. See Synthesizing an app: URI for more information on the use of UUID in construction of the authority field.

6.1 Synthesizing an app: URI

When synthesizing an app: URI, a user agent MUST generate a string that conforms to appuri, and normalize it using syntax-based normalization as 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 then app: URI (e.g., in the case of a packaged application, it represents an instance of an application).

How long the identifier represented by the authority is bound to an instance of an application is application specific (e.g., it may be reset when the user clears the user agent's private data, or can last until the application is uninstalled from an end-user's device). See privacy and security considerations.

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 (but it's not mandatory! Other types of authorities, like reverse domain name notation, are allowed). Using a [UUID] makes it improbable that two URIs 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 path component in identifying a resource within a package [URL]. However, when dereferencing, the query and fragment components don't play any part in locating a file inside of package.

For example, the following app: 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 an app: 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" like a HTTP request (except the request and response are performed over "app://" instead of "http://").

For simplicity, this specification 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 app: URI to a file in a app package a user agent MUST apply the rules for dereferencing an app: URI.

Note: A user agent can deference a URI scheme using other means/technologies (e.g., a proxy or local web server), but the end result needs to be indistinguishable from the result that would be obtained by following the specification.

The rules for dereferencing an app: 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. Ignore any [HTTP] request headers.

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

  4. Resolve URI into an absolute URL using the document's origin as the base.

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

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

  7. Let path be the path component of URI.

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

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

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

  11. Let content-type be the result of applying [SNIFF] to determine the content-type.

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

Privacy and Security Considerations

This section is non-normative.

Because [UUID]s used by the app: URI scheme are effectively a digital finger print, an application developer could use a UUID to personally identify a user. This can allow a developer to, for example, restore cookies even if the user has cleared cookies from a user agent. As such, user agents should provide end-users with a means of regenerating the authority component of an app: URI. For example, the UUID for an application could be regenerated every time the application is started. Or the UUID could be regenerated when the user clears private data from the user agent.

When dereferencing an app: URI, a user agent needs to make sure that only files that were in the package can be accessed (i.e., those files should be sand-boxed). User agents need to watch out for symbolic links (or similar) inside a package, which can attempt to trick the user agent into accessing files that are on other parts of the file system.

As this specification relies on the standardized heuristics for determining the content type of files defined in the [SNIFF] specification, implementors need to consider the security considerations discussed in the [SNIFF] specification.

7 Use Cases

For developers, this specification attempts to address the following use cases:

  1. Provide a URI scheme that is compatible with the features and security model of [HTML], so that applications that are packaged can make full use of [HTML]'s capabilities and those of related technologies. For example, the app: uri scheme should be usable as a document's address so that it can serve as its origin, and it should be compatible with APIs that rely on [HTTP] responses, like [XHR].

  2. Provide a URI scheme that is secure, in that it is constrained to just resources within a package.

  3. Provide an addressing scheme that is easy to work with - and that developers are already accustomed to working with. The developer should not be bother as to wether they are using http:// or app:// - the Web's capabilities and APIs need to just work!


The bulk of the text in this specifications was derived from the Widget URI scheme specification. The Systems Application working group acknowledge the hard work of the Web Applications Working Group in laying down the foundations for this specification.

Thanks also to Robin Berjon, who helped edit this specification when it was part of WebApps.

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.
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. WHATWG.
A Universally Unique Identifier (UUID) URN Namespace. IETF.

Informative references

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