Abstract

This specification defines a JSON-based manifest that provides developers with a centralized place to put metadata associated with a web application. This includes, but is not limited to, the web application's name, links to icons, as well as the preferred URL to open when a user launches the web application. The manifest also allows developers to declare a default orientation for their web application, as well as providing the ability to set the display mode for the application (e.g., in fullscreen). Additionally, the manifest allows a developer to "scope" a web application to a URL. This restricts the URLs to which the application can be navigated and provides a means to "deep link" into a web application from other applications.

Using this metadata, user agents can provide developers with means to create user experiences that are more comparable to that of a native application.

In addition, this specification defines the manifest link type, which provides a declarative means for a document to be associated with a manifest.

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/.

Implementors need to be aware that this specification is starting to stabilize. Aspects of this specification are shipping in at least one browser (see links to implementation status at the top of this document). Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.

This Working Draft is intended to meet the wide review requirements as defined in the 2014 Process Document. The deadline for comments is 5 March 2015. The next anticipated publication of this specification is a Candidate Recommendation. See Issue 308 for the specification's Candidate Recommendation status.

This document was published by the Web Applications (WebApps) Working Group as a 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). All comments are 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 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 document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

1. Usage Examples

This section is non-normative.

This section shows how developers can make use of the various features of this specification.

1.1 Example manifest

This section is non-normative.

The following shows a typical manifest.

Example 1: typical manifest
{
  "name": "Super Racer 2000",
  "short_name": "Racer2K",
  "icons": [{
        "src": "icon/lowres",
        "sizes": "64x64",
        "type": "image/webp"
      }, {
        "src": "icon/hd_small",
        "sizes": "64x64"
      }, {
        "src": "icon/hd_hi",
        "sizes": "128x128",
        "density": 2
      }],
  "scope": "/racer/",
  "start_url": "/racer/start.html",
  "display": "fullscreen",
  "orientation": "landscape"
}

2. Installable web applications

This document attempts to address the Use Cases and Requirements for Installable Web Apps.

A web application is installed if the user agent has provided the end-user with a means of instantiating a new top-level browsing context that has the manifest's members applied to it. That is, the manifest's members, or their defaults, are in effect on the top-level browsing context (see application context).

An example of installing would be a user agent that allows the end-user to add a shortcut to a web application on their device's homescreen (using the name and one of the icons found in the manifest). Then, when the end-user launches a web application through this explicit means, the manifest is applied to the browsing context prior to the start URL being loaded. This gives the user agent time to apply the relevant values of the manifest, possibly changing the display mode and screen orientation of the web application. Alternatively, an application context can be launched through a deep link (a URL that is within scope of the installed web application); in which case, the manifest is applied and the deep link is loaded within the context of web application.

2.1 Installability signals

This section is non-normative.

By design, this specification does not provide developers with an explicit API to "install" a web application. Instead, a manifest can serve as an installability signal (amongst other signals) to a user agent that a web application can be installed.

Installability signals can include things like the ones in the following list (this list is not exhaustive and some items might not apply to all user agents). For instance, the web application:

How a user agent makes use of these installability signals to determine if a web application is installable is left to implementers.

4. Display modes

A display mode represents how developers would like the user agent to present the web application to a user (e.g., in fullscreen). Display modes correspond to user interface (UI) metaphors and functionality in use on a given platform. The UI conventions of the display modes are purely advisory and implementers are free to interpret them how they best see fit.

Once a user agent applies a particular display mode to an application context, it becomes the default display mode for the top-level browsing context (i.e., it is used as the display mode when the window is navigated). The user agent MAY override the default display mode for security reasons (e.g., the top-level browsing context is navigated to another origin) and/or the user agent MAY provide the user with a means of switching to another display mode.

When the display member is missing, or if there is no valid display member, the user agent uses the browser display mode as the default display mode. As such, the user agent is REQUIRED to support the browser display mode.

Each display mode, except browser, has a recursive fallback display mode, which is the display mode that the user agent can try to use if it doesn't support a particular display mode. If the user agent does support a fallback display mode, then it checks to see if it can use that display mode's fallback display mode. This creates a fallback chain, with the default display mode (browser) being the last item in the chain.

For example, Awesome Browser only supports the minimal-ui and browser display modes, but a developer declares that she wants fullscreen in the manifest. In this case, the user agent will first check if it supports fullscreen (it doesn't), so it falls back to standalone (which it also doesn't support), and ultimately falls back to minimal-ui.

The display modes values and their corresponding fallback display modes are as follows:

fullscreen
Opens the web application without any user agent chrome and takes up the entirety of the available display area.
The fallback display mode for fullscreen is standalone.
standalone
Opens the web application to look and feel like a standalone native application. This can include the application having a different window, its own icon in the application launcher, etc. In this mode, the user agent will exclude UI elements for controlling navigation, but can include other UI elements such as a status bar.
The fallback display mode for standalone is minimal-ui.
minimal-ui
This mode is similar to fullscreen, but provides the end-user with some means to access a minimal set of UI elements for controlling navigation (i.e., back, forward, reload, and perhaps some way of viewing the document's address). A user agent can include other platform specific UI elements, such as "share" and "print" buttons or whatever is customary on the platform and user agent.
The fallback display mode for minimal-ui is browser.
browser
Opens the web application using the platform-specific convention for opening hyperlinks in the user agent (e.g., in a browser tab or a new window).
The browser display mode doesn't have a fallback display mode (conforming user agents are required to support the browser display mode).
Note

The fullscreen display mode is orthogonal to, and works independently of, the [WHATWG-FULLSCREEN] API. The fullscreen display mode affects the fullscreen state of the browser window, while the [WHATWG-FULLSCREEN] API operates on an element contained within the viewport. As such, a web application can have its display mode set to fullscreen, while document.fullScreenElement returns null, and fullscreenEnabled returns false.

4.1 The 'display-mode' media feature

The display-mode media feature represents, via a CSS media query [MEDIAQ], the display mode that the user agent is applying to the web application.

Value:
fullscreen | standalone | minimal-ui | browser
Applies to:
visual media types
Accepts min/max prefixes:
No

A user agent MUST reflect the applied display mode of the web application via a CSS media query [MEDIAQ].

4.1.1 Examples

An example in CSS:

Example 3
@media all and (display-mode: minimal-ui) {
  /* ... */
}
@media all and (display-mode: standalone) {
  /* ... */
}

Accessing the display-mode media feature in ECMAScript through matchMedia() of [cssom-view]:

Example 4
let standalone = matchMedia( '(display-mode: standalone)' );

standalone.onchange = function(e) {
  /* handle changes to display mode */
}

if (standalone.matches) {
  /* do standalone things */
}

4.1.2 Security and privacy considerations

The 'display-mode' media feature allows an origin access to aspects of a user’s local computing environment and, together with the display member, allows an origin some measure of control over a user agent’s native UI: Through a CSS media query, a script can know the display mode of a web application. An attacker could, in such a case, exploit the fact that an application is being displayed in fullscreen to mimic the user interface of another application.

Furthermore, by neglecting to define a scope member in the manifest, it's possible to put a web application into a display mode that persists cross-origin (for legacy reasons, this is the default behavior). In case where the navigation scope is unbounded, it is left to the user agent to either stop applying the manifest when a cross-origin navigation occurs or to show some sort of security warning to the user.

5. Associating a resource with a manifest

A resource is said to be associated with a manifest if the resource representation, an HTML document, has a manifest link relationship.

5.1 Linking to a manifest

The manifest keyword can be used with a [HTML] link element. This keyword creates an external resource link.

Link type Effect on... Brief description
link a and area
manifest External Resource not allowed Imports or links to a manifest.

The media type for a manifest serves as the default media type for resources associated with the manifest link type.

Note

In cases where more than one link element with a manifest link type appears in a Document, the user agent uses the first link element in tree order and ignores all subsequent link element with a manifest link type (even if the first element was erroneous). See the steps for obtaining a manifest.

To obtain a manifest, the user agent MUST run the steps for obtaining a manifest. The appropriate time to obtain the manifest is left up to implementations. A user agent MAY opt to delay fetching a manifest until after the document and its other resources have been fully loaded (i.e., to not delay the availability of content and scripts required by the document).

A manifest is obtained and applied regardless of the media attribute of the link element matches the environment or not.

6. Manifest life-cycle

This section defines algorithms for obtaining, processing, and applying a manifest, and gives recommendations to implementers on how to react when the manifest is updated.

6.1 Obtaining a manifest

The steps for obtaining a manifest are given by the following algorithm. The algorithm, if successful, returns a processed manifest and the manifest URL; otherwise, it terminates prematurely and returns nothing. In the case of nothing being return, the user agent MUST ignore the manifest declaration. In running these steps, a user agent MUST NOT delay the load event.

  1. From the Document of the top-level browsing context, let manifest link be the first link element in tree order whose rel attribute contains the token manifest.
  2. If manifest link is null, terminate this algorithm.
  3. Obtain a resource as per [HTML] and let response be the [FETCH] response. If the obtain a resource algorithm terminates prematurely or response is a network error, terminate this algorithm.
  4. Let manifest URL be the response's URL.
  5. Let manifest be the result of running the steps for processing a manifest with response's body as the text, manifest URL, and the URL that represents the address of the top-level browsing context.
  6. Return manifest and manifest URL.
Note

Authors are encouraged to use the HTTP cache directives to explicitly cache the manifest. For example, the following response would cause a cached manifest to be used one year from the time the response is sent:

HTTP/1.1 200 OK
Cache-Control: max-age=31536000
Content-Type: application/manifest+json

{
  "name": "Super Racer 2000",
  "start_url": "/start.html",
  "display": "fullscreen",
  "orientation": "landscape"
}

6.1.1 Content security policy

A user agent MUST support [CSP2].

The manifest-src and default-src directives govern the origins from which a user agent can fetch a manifest. As with other directives, by default the manifest-src directive is *, meaning that a user agent can, [CORS] permitting, fetch the manifest cross-domain. Remote origins (e.g., a CDN) wanting to host manifests for various web applications will need to include the appropriate [CORS] response header in their HTTP response (e.g., Access-Control-Allow-Origin: https://example.com).

Fig. 1 For a [HTML] document, [CSP2]'s manifest-src directive controls the sources from which a [HTML] document can load a manifest from. The same CSP policy's image-src directive controls where the icon's images can be fetched from.

6.2 Processing the manifest

When instructed to issue a developer warning, the user agent MAY report the conformance violation to the developer in a user-agent-specific manner (e.g., report the problem in an error console), or MAY ignore the error and do nothing.

When instructed to ignore, the user agent MUST act as if whatever manifest, member, or value caused the condition is absent.

The following algorithm provides an extension point: other specifications that add new members to the manifest are encouraged to hook themselves into this specification at this point in the algorithm.

Note

The extension point is meant to help avoid issues related to monkey patching.

The steps for processing a manifest are given by the following algorithm. The algorithm takes a text string as an argument, which represents a manifest, and a URL manifest URL, which represents the location of the manifest, and a URL document URL. The output from inputting an JSON document into this algorithm is a processed manifest.

  1. Let parsed manifest be an empty object.
  2. Let manifest be the result of parsing text. If parsing throws an error:
    1. Issue a developer warning with any details pertaining to the JSON parsing error.
    2. Set manifest to be the result of parsing the string "{}".
  3. If Type(manifest) is not "object":
    1. Issue a developer warning that the manifest needs to be an object.
    2. Set manifest to be the result of parsing the string "{}".
  4. Extension point: process any proprietary and/or other supported members at this point in the algorithm.
  5. Let start URL of parsed manifest be the result of running the steps for processing the start_url member with manifest, manifest URL, and document URL as arguments.
  6. Let display mode of parsed manifest be the result of running the steps for processing the display member with manifest as the argument.
  7. Let orientation of parsed manifest be the result of running the steps for processing the orientation member with manifest and display mode as arguments.
  8. Let name of parsed manifest be the result of running the steps for processing the name member with manifest as the argument.
  9. Let short name of parsed manifest be the result of running the steps for processing the short_name member with manifest as the argument.
  10. Let icons of parsed manifest be the result of running the steps for processing the icons member with manifest and manifest URL as arguments.
  11. Let scope of parsed manifest be the result of running the steps for processing the scope member with manifest, manifest URL, document URL, start URL as arguments.
  12. Return parsed manifest.

6.3 Applying the manifest

A manifest is applied to a top-level browsing context, meaning that the members of the manifest are affecting the presentation or behavior of a browsing context.

A top-level browsing context that has a manifest applied to it is referred to as an application context.

If an application context is created as a result of the user agent being asked to navigate to a deep link, the user agent MUST immediately navigate to the deep link with replacement enabled. Otherwise, when the application context is created, the user agent MUST immediately navigate to the start URL with replacement enabled.

Please note that the start URL is not necessarily the value of the start_url member: the user or user agent could have changed it when the application was added to home-screen or otherwise bookmarked.

The appropriate time to apply a manifest is when the application context is created and before navigation to the start URL begins.

6.4 Updating the manifest

By using the manifest URL, a user agent MAY periodically check if the contents of a manifest has been modified (e.g., by honoring HTTP cache directives associated with the manifest or by checking for updates after the web application has been launched). In the event that the members of the manifest have been updated, as determined by running the steps for processing a manifest and seeing if anything has changed, the user agent MAY update the metadata corresponding to the web application (e.g., by replacing the name, icons, navigation scope, or whatever other data has been changed).

In addition, even if the manifest has not been modified, the user agents MAY periodically check if resources referenced from a manifest (e.g., the icons) have been modified by honoring HTTP cache directives. If any resources have been modified, the user agent MAY replace any stale resources.

To avoid one application masquerading as another, it is RECOMMENDED that users be made aware of any such updates using implementation or platform specific conventions.

7. Manifest and its members

A manifest is a JSON document that contains startup parameters and application defaults for when a web application is launched. A manifest consists of a top-level object that contains zero or more members. Each of the members are defined below, as well as how their values are processed.

Every manifest has an associated manifest URL, which the [URL] from which the manifest was fetched.

7.1 name member

The name member is a string that represents the name of the web application as it is usually displayed to the user (e.g., amongst a list of other applications, or as a label for an icon).

Note

For all intents and purposes, the name member is functionally equivalent to having a meta element whose name attribute is application-name in a [HTML] document. In cases where no suitable name can be derived from processing a manifest, [HTML]'s application-name or the title element serve as suitable fallbacks.

The steps for processing the name member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "name".
  2. If Type(value) is not "string":
    1. If Type(value) is not "undefined", optionally issue a developer warning that the type is not supported.
    2. Return undefined.
  3. Otherwise, Trim(value) and return the result.

7.2 short_name member

The short_name member is a string that represents a short version of the name of the web application. It is intended to be used where there is insufficient space to display the full name of the web application.

The steps for processing the short_name member is given by the following algorithm. The algorithm takes a manifest as an argument. This algorithm returns a string or undefined.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "short_name".
  2. If Type(value) is not "string":
    1. If Type(value) is not "undefined", optionally issue a developer warning that the type is not supported.
    2. Return undefined.
  3. Otherwise, Trim(value) and return the result.

7.3 scope member

The scope member is a string that represents the navigation scope of this web application's application context.

The steps for processing the scope member is given by the following algorithm. The algorithm takes a manifest manifest, a URL manifest URL, a URL document URL, and a URL start URL. This algorithm returns a URL or undefined.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of the manifest with argument "scope".
  2. Let type be Type(value).
  3. If type is not "string" or value is the empty string, then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
    2. Return undefined.
  4. Let scope URL be a new URL using value as input and manifest URL as the base URL.
  5. If scope URL is failure:
  6. If scope URL is not same origin as document URL:
    1. Issue a developer warning that the scope needs to be same-origin as Document of the application context.
    2. Return undefined.
  7. If start URL is not within scope of scope URL:
    1. Issue a developer warning that the start URL is not within scope of the navigation scope.
    2. Return undefined.
  8. Otherwise, return scope URL.

7.4 icons member

The icons member is an array of icon objects that can serve as iconic representations of the web application in various contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.

Note

If no icons are listed in the manifest (or none of them are found to be suitable during processing), it is RECOMMENDED that the user agent fall back to using any icons found in the Document of the top-level browsing context. For example, an icon link type and/or a favicon.ico can serve as suitable fallbacks.

The steps for processing the icons member are given by the following algorithm. The algorithm takes a manifest, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a list of icons objects icons, which can be empty.

  1. Let icons be an empty list.
  2. Let unprocessed icons be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "icons".
  3. If unprocessed icons is an array, then:
    1. From unprocessed icons, filter out any item where HasOwnProperty(item,"src") returns false.
    2. For each potential icon in the array:
      1. Let src be the result of running the steps for processing the src member of an icon with potential icon and manifest URL.
      2. If src is undefined, move onto the next item in icons (if any are left).
      3. Otherwise, let icon be an object with properties src, type, sizes, and density. All properties initially set to undefined.
      4. Set icon's src property to be src.
      5. Let type be the result of running the steps for processing the type member of an icon passing potential icon.
      6. If type is not undefined, set icon's type property to be type.
      7. Let sizes be the list that result from running the steps for processing a sizes member of an icon passing potential icon.
      8. If sizes is not undefined, set icon's sizes property to be sizes.
      9. Let density be the result from running the steps for processing a density member of an icon are given by the passing potential icon.
      10. If density is not undefined, set icon's density property to be value.
      11. Append icon to icons.
  4. Otherwise, if unprocessed icons is not undefined:
    1. Issue a developer warning that the type is not supported.
  5. Return icons.

If there are multiple equally appropriate icons in icons, a user agent MUST use the last one declared in order at the time that the user agent collected the list of icons. If the user agent tries to use an icon but that icon is determined, upon closer examination, to in fact be inappropriate (e.g. because its content type is unsupported), then the user agent MUST try the next-most-appropriate icon as determined by examining the icon object's members.

7.5 display member

The display member is a string, whose value is one of display modes values. The item represents the developer's preferred display mode for the web application. When the member is missing or erroneous, the user agent MUST use the fallback display mode.

The steps for processing the display member are given by the following algorithm. The algorithm takes a manifest manifest as an argument, and returns a string.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest passing "display" as the argument.
  2. If Type(value) is not "string" or value is not part of the display modes values:
    1. If Type(value) is not "undefined", issue a developer warning that the type is unsupported.
    2. If value is not part of the display modes values , issue a developer warning that the value is unsupported.
    3. Return the fallback display mode's value.
  3. Otherwise, Trim(value) and set value to be the result.
  4. If value is not a display mode that the user agent supports, set value to value's fallback display mode and re-run this step.
  5. Return value.

7.6 orientation member

The orientation member is a string that serves as the default orientation for all top-level browsing contexts of the web application. The possible values is one of the OrientationLockType enum defined in [SCREEN-ORIENTATION].

If the user agent honors the value of the orientation member as the default orientation, then that serves as the default orientation for the life of the web application (unless overridden by some other means at runtime). This means that the user agent MUST return the orientation to the default orientation any time the orientation is unlocked [SCREEN-ORIENTATION] or the top-level browsing context is navigated.

Although the specification relies on the [SCREEN-ORIENTATION]'s OrientationLockType, it is OPTIONAL for a user agent to implement the [SCREEN-ORIENTATION] API. Supporting the [SCREEN-ORIENTATION] API is, of course, RECOMMENDED.

Certain UI/UX concerns and/or platform conventions will mean that some screen orientations and display modes cannot be used together. Which orientations and display modes cannot be used together is left to the discretion of implementers. For example, for some user agents, it might not make sense to change the default orientation of an application while in browser display mode.

Note

Once the web application is running, other means can change the orientation of a top-level browsing context (such as via [SCREEN-ORIENTATION] API).

The steps for processing the orientation member are given by the following algorithm. The algorithm takes a manifest manifest and display mode display mode as an argument, and returns a string.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of manifest with argument "orientation".
  2. If Type(value) is not "string":
    1. If Type(value) is not "undefined", issue a developer warning that the type is not supported.
    2. Return the empty string.
  3. Otherwise, Trim(value) and set value to be the result.
  4. If value is not one of the OrientationLockType enum values, or value is unsupported by the user agent, or the value cannot be used together with display mode:
    1. Issue a developer warning.
    2. Return the empty string.
  5. Return value.

7.7 start_url member

The start_url member is a string that represents the start URL, which is URL that the developer would prefer the user agent load when the user launches the web application (e.g., when the user clicks on the icon of the web application from a device's application menu or homescreen).

The start_url member is purely advisory, and a user agent MAY ignore it or provide the end-user the choice not to make use of it. A user agent MAY also allow the end-user to modify the URL when, for instance, a bookmark for the web application is being create or any time thereafter.

The steps for processing the start_url member are given by the following algorithm. The algorithm takes a manifest manifest, a URL manifest URL, and a URL document URL. This algorithm returns a URL.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of the manifest with argument "start_url".
  2. Let type be Type(value).
  3. If type is not "string" or value is the empty string, then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
    2. Return a new URL whose input is document URL.
  4. Let url be a new URL using value as input and manifest URL as the base URL.
  5. If url is failure:
  6. If url is not same origin as document URL:
    1. Issue a developer warning that the start_url needs to be same-origin as Document of the top-level browsing context.
    2. Return a new URL whose input is document URL.
  7. Otherwise, return url.

For example, if the value of start_url is ../start_point.html, and the manifest's URL is https://example.com/resources/manifest.json, then the result of URL parsing would be https://example.com/start_point.html.

8. Icon object and its members

Each icon object represents an icon for a web application, suitable to use in various contexts (e.g., an application menu). As icons are usually images, this specification provides developers with a means of specifying the dimensions, optimal pixel density, and media type of an icon. A user agent can use these values to select an icon that is best suited to display on the end-user's device or most closely matches the end-user's preferences.

In the following example, the developer has made the following choices about the icons of the web application:

{
  "icons": [
      {
        "src": "icon/lowres.webp",
        "sizes": "48x48",
        "type": "image/webp"
      },{
        "src": "icon/lowres",
        "sizes": "48x48"
      },{
        "src": "icon/hd_hi.ico",
        "sizes": "72x72 96x96 128x128 256x256"
      },{
        "src": "icon/hd_hi.svg",
        "sizes": "72x72",
        "density": 2
      }]
 }
Note

For all intents and purposes, an icon object is functionally equivalent to link element whose rel attribute is icon in a Document.

8.1 Content security policy of icon object

The security policy that governs whether a user agent can fetch an icon image is governed by the image-src directive [CSP2] associated with the manifest's owner Document.

For example, the following policy restricts loading icons the icons.example.com domain. Thus, trying to load icons from "other.com" would fail.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Security-Policy: img-src icons.example.com;

{
    "name": "custom manifest",
    "start_url": "http://boo",
    "icons": [{
        "src": "//icons.example.com/lowres"
      },
      {
        "src": "//other.com/hi-res"
      }]
}

8.2 density member

The density member of an icon is the device pixel density for which this icon was designed. The device pixel density is expressed as the number of dots per 'px' unit (equivalent to a dppx as defined in [css3-values]). The value is a positive number greater than 0. If the developer omits the value, the user agent assumes the value 1.0.

The steps for processing a density member of an icon are given by the following algorithm. The algorithm thanks an icon object as an argument and returns a positive number.

  1. If [[HasOwnProperty]] internal method of icon passing density as the argument returns false:
    1. Return 1.0.
  2. Let value be the result of calling the [[GetOwnProperty]] internal method of icon passing "density" as the argument.
  3. Let result be the result of parseFloat(value);
  4. If result is NaN, +∞, or less than or equal to +0, then:
    1. Issue a developer warning.
    2. Let result be 1.0.
  5. Return result.

8.3 sizes member

The sizes member is a string consisting of an unordered set of unique space-separated tokens which are ASCII case-insensitive that represents the dimensions of an icon for visual media. Each keyword is either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The keywords represent icon sizes in raw pixels (as opposed to CSS pixels). When multiple icon objects are available, a user agent can use the value to decide which icon is most suitable for a display context (and ignore any that are inappropriate).

The steps for processing a sizes member of an icon are given by the following algorithm. The algorithm takes an icon object icon. This algorithm will return a set.

  1. Let sizes be an empty set.
  2. Let value be the result of calling the [[GetOwnProperty]] internal method of icon passing "sizes" as the argument.
  3. Let type be Type(value).
  4. If type is not "string", then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
  5. Otherwise, parse value as if it was a [HTML] sizes attribute and let keywords be the result.
  6. For each keyword in keywords:
    1. Convert keyword to ASCII lowercase and add the resulting string to sizes.
  7. Return sizes.

8.4 src member

The src member of an icon is a URL from which a user agent can fetch the icon's data.

The steps for processing the src member of an icon are given by the following algorithm. The algorithm takes a icon object icon, and a URL manifest URL, which is the URL from which the manifest was fetched. This algorithm will return a URL or undefined.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of icon passing "src" as the argument.
  2. Let type be Type(value).
  3. If type is not "string", or value is the empty string, then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
    2. Return undefined.
  4. If Trim(value) is the empty string, then return undefined.
  5. Otherwise, parse value using manifest URL as the base URL and return the result.

8.5 type member

The type member of an icon is a hint as to the media type of the icon. The purpose of this member is to allow a user agent to ignore icons of media types it does not support.

There is no default MIME type for icon objects. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

The steps for processing the type member of an icon are given by the following algorithm. The algorithm takes an icon object as an argument, and returns either a string or undefined.

  1. Let value be the result of calling the [[GetOwnProperty]] internal method of potential icon passing "type" as the argument.
  2. Let type be Type(value).
  3. If type is not "string", then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
    2. Return undefined.
  4. Trim(value) and set value to be resulting string.
  5. If value is not a valid MIME type or the value of type is not a supported media format, issue a developer warning and return undefined.
  6. Return value.

9. Common conventions and dependencies

The [[GetOwnProperty]] operation and the abstract operation hasOwnProperty, parseFloat(string) function, and the Type(x) notation are defined in [ECMASCRIPT].

When instructed to Trim(x), a user agent MUST behave as if [ECMASCRIPT]'s String.prototype.trim() function had been called on the string x.

As the manifest uses the JSON format, this specification relies on the types defined in [ECMA-404] specification: namely object, array, number, string, true, false, and null. Strict type checking is not enforced by this specification. Instead, each member's definition specifies the steps required to process a particular member and what to do when a type does not match what is expected.

The URL concept and URL parsing are defined in [WHATWG-URL].

The default orientation concept and the OrientationLockType enum, are defined in [SCREEN-ORIENTATION].

The following are defined in [HTML]:

10. IANA considerations

The following registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.

10.1 Media type registration

This section contains the required text for MIME media type registration with IANA.

The media type for a manifest is application/manifest+json.

If the protocol over which the manifest is transferred supports the [MIME-TYPES] specification (e.g. HTTP), it is RECOMMENDED that the manifest be labeled with the media type for a manifest.

Type name:
application
Subtype name:
manifest+json
Required parameters:
N/A
Optional parameters:
N/A
Encoding considerations:
Same as for application/json
Security and privacy considerations:

This specification does not directly deal with high-value data. However, installed web applications and their data could be seen as "high value" (particulaly from a privacy perspective).

As the manifest format is JSON and will commonly be encoded using [UNICODE], the security considerations described in [ECMA-404] and [UNICODE-SECURITY] apply. In addition, because there is no way to prevent developers from including custom/unrestrained data in a manifest, implementors need to impose their own implementation-specific limits on the values of otherwise unconstrained member types, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Web applications will generally contain ECMAScript, HTML, CSS files, and other media, which are executed in a sand-boxed environment. As such, implementors need to be aware of the security implications for the types they support. Specifically, implementors need to consider the security implications outlined in at least the following specifications: [CSS-MIME], [ECMAScript-MIME], [HTML].

As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementors need to consider the privacy implications resulting from exposing private information to a remote host. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementors are advised to enable user awareness of information sharing, and to provide easy access to interfaces that enable revocation of permissions.

As this specification allows for the declaration of URLs within certain members of a manifest, implementors need to consider the security considerations discussed in the [WHATWG-URL] specification. Implementations intending to display IRIs and IDNA addresses found in the manifest are strongly encouraged to follow the security advice given in [UNICODE-SECURITY].

Developers need to be aware of the security considerations discussed throughout the [CSP2] specification, particularly in relation to making data: a valid source for the purpose of inlining a manifest. Doing so can enable XSS attacks by allowing a manifest to be included directly in the document itself; this is best avoided completely.

Applications that use this media type:
Web browsers
Additional information:
Magic number(s):
N/A
File extension(s):
.json, .manifest
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
The Web Applications (WebApps) Working Group can be contacted at public-webapps@w3.org.
Intended usage:
COMMON
Restrictions on usage:
none
Author:
W3C's Web Applications (WebApps) Working Group.
Change controller:
W3C.

11. 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 MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, and REQUIRED are to be interpreted as described in [RFC2119].

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

11.1 Extensibility

This section is non-normative.

This specification is designed to be extensible. Other specifications are encouraged to define new members for the manifest. However, in doing so, please follow the conventions used in this specification. In particular, use the extension point to hook into the steps for processing a manifest. Also, be sure to specify the steps for processing your particular member in the manner set forth in this specification. This will help keep this part of the platform consistent.

When specifying a new member, don't override or monkey patch anything defined in this specification. Also, don't assume your member will be processed before or after any other member. Keep your new member, and its processing, atomic and self contained. Note also that implementations are free to ignore any member they do not recognize or support.

If you are writing a specification and temporarily want to patch this specification to help implementations along, file a bug so the community is informed of what you are trying to do.

11.1.1 Proprietary manifest members

This section is non-normative.

Although proprietary extensions are undesirable, they can't realistically be avoided. As such, the RECOMMENDED way to add a new proprietary manifest member as an extension is to use a vendor prefix.

The following is an example of two hypothetical vendor extensions.

Example 5: vendor extensions
{
  ...
  "webkit_fancy_feature": "some/url/img",
  "moz_awesome_thing": { ... }
  ...
}

A. JSON-LD extensions to the manifest

The mechanisms defined by the [JSON-LD] specification can be used as an alternative mechanism for extending the manifest.

In the following example, for instance, elements from both the Dublin Core Metadata Set [DC-TERMS], the Friend of a Friend [FOAF] vocabulary, and the Description of a Project (DOAP) vocabulary are used to provide additional information in the manifest:

Example 6: JSON-LD extensions
{
  "@context": {
    "@vocab": "http://www.w3.org/TR/appmanifest/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "dct": "http://purl.org/dc/terms/",
    "doap": "http://usefulinc.com/ns/doap#"
  },
  "name": "Super Racer 2000",
  "dct:creator": "http://example.com",
  "dct:abstract": "A Super Racer Game!",
  "doap:maintainer": {
    "foaf:name": "Joe"
  },
  "icons": [{
    "src": "icon/lowres",
    "sizes": "64x64",
    "type": "image/webp"
  }, {
    "src": "icon/hd_small",
    "sizes": "64x64"
  }, {
    "src": "icon/hd_hi",
    "sizes": "128x128"
  }],
  "start_url": "/start.html",
  "display": "fullscreen",
  "orientation": "landscape"
}

Non JSON-LD implementations can simply ignore the additional JSON-LD specific metadata such as @context and the extension properties dct:creator, dct:abstract and doap:maintainer.

For implementations that do process the manifest as JSON-LD, the manifest's own property names are interpreted relative to the base URI "http://www.w3.org/TR/appmanifest/".

After processing the example above, a JSON-LD implementation would yield the following normalized output:

Example 7
_:c14n0 <http://www.w3.org/TR/appmanifest/sizes> "64x64" .
_:c14n0 <http://www.w3.org/TR/appmanifest/src> "icon/hd_small" .
_:c14n1 <http://purl.org/dc/terms/abstract> "A Super Racer Game!" .
_:c14n1 <http://purl.org/dc/terms/creator> "http://example.com" .
_:c14n1 <http://usefulinc.com/ns/doap#maintainer> _:c14n4 .
_:c14n1 <http://www.w3.org/TR/appmanifest/display> "fullscreen" .
_:c14n1 <http://www.w3.org/TR/appmanifest/icons> _:c14n0 .
_:c14n1 <http://www.w3.org/TR/appmanifest/icons> _:c14n2 .
_:c14n1 <http://www.w3.org/TR/appmanifest/icons> _:c14n3 .
_:c14n1 <http://www.w3.org/TR/appmanifest/name> "Super Racer 2000" .
_:c14n1 <http://www.w3.org/TR/appmanifest/orientation> "landscape" .
_:c14n1 <http://www.w3.org/TR/appmanifest/start_url> "/start.html" .
_:c14n2 <http://www.w3.org/TR/appmanifest/sizes> "64x64" .
_:c14n2 <http://www.w3.org/TR/appmanifest/src> "icon/lowres" .
_:c14n2 <http://www.w3.org/TR/appmanifest/type> "image/webp" .
_:c14n3 <http://www.w3.org/TR/appmanifest/sizes> "128x128" .
_:c14n3 <http://www.w3.org/TR/appmanifest/src> "icon/hd_hi" .
_:c14n4 <http://xmlns.com/foaf/0.1/name> "Joe" .

C. JSON Schema

Developers interested in validating manifest documents can find an unofficial JSON schema for the manifest format at schemastore.org. It is licensed under Apache 2.0. It is kindly maintained by Mads Kristensen. If you find any issues with the JSON schema, please file a bug at the SchemaStore repository on GitHub.

D. Acknowledgments

This document reuses text from the [HTML] specification, edited by Ian Hickson, as permitted by the license of that specification.

E. References

E.1 Normative references

[CORS]
Anne van Kesteren. Cross-Origin Resource Sharing. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/cors/
[CSP2]
Mike West; Adam Barth; Daniel Veditz. Content Security Policy Level 2. 3 July 2014. W3C Last Call Working Draft. URL: http://www.w3.org/TR/CSP2/
[CSS-MIME]
H. Lie; B. Bos; C. Lilley. The text/css Media Type. March 1998. Informational. URL: https://tools.ietf.org/html/rfc2318
[ECMA-404]
. The JSON Data Interchange Format. 1 October 2013. Standard. URL: http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
[ECMASCRIPT]
Allen Wirfs-Brock. ECMA-262 ECMAScript Language Specification, Edition 6. Draft. URL: http://people.mozilla.org/~jorendorff/es6-draft.html
[ECMAScript-MIME]
B. Hoehrmann. Scripting Media Types. April 2006. Informational. URL: https://tools.ietf.org/html/rfc4329
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Ian Hickson. HTML. Living Standard. URL: https://html.spec.whatwg.org/
[MEDIAQ]
Florian Rivoal et al. Media Queries. 19 June 2012. W3C Recommendation. URL: http://www.w3.org/TR/css3-mediaqueries/
[MIME-TYPES]
N. Freed; N. Borenstein. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SCREEN-ORIENTATION]
Mounir Lamouri; Marcos Caceres. The Screen Orientation API. 23 October 2014. W3C Working Draft. URL: http://www.w3.org/TR/screen-orientation/
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/
[UNICODE-SECURITY]
Mark Davis; Michel Suignard. Unicode Security Considerations. URL: http://www.unicode.org/reports/tr36/
[URL]
Anne van Kesteren; Sam Ruby. URL. 9 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/url-1/
[WHATWG-URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/

E.2 Informative references

[DC-TERMS]
Dublin Core Metadata Initiative. Dublin Core Metadata Initiative Terms, version 1.1. 11 October 2010. DCMI Recommendation. URL: http://dublincore.org/documents/2010/10/11/dcmi-terms/.
[FOAF]
Dan Brickley; Libby Miller. FOAF Vocabulary Specification 0.99 (Paddington Edition). 14 January 2014. URL: http://xmlns.com/foaf/spec
[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/json-ld/
[WHATWG-FULLSCREEN]
Anne van Kesteren. Fullscreen. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[css3-values]
Håkon Wium Lie; Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 30 July 2013. W3C Candidate Recommendation. URL: http://www.w3.org/TR/css3-values/
[cssom-view]
Simon Pieters; Glenn Adams. CSSOM View Module. 17 December 2013. W3C Working Draft. URL: http://www.w3.org/TR/cssom-view/