This specification defines a JSON-based manifest, which 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 the user launches the web application. The manifest also allows developers to declare a default orientation for their web application, as well as how the application is to be displayed by the user agent (e.g., in fullscreen).

Using this meta data, 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.

Implementors need to be aware that this specification is extremely unstable. 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 join the aforementioned mailing lists, or subscribe to the repository on GitHub, and take part in the discussions.

Usage Examples

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

Example manifest

The following shows a typical manifest.

{
  "name": "Super Racer 2000",
  "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" }

Using a link element to link to a manifest

Example of using a link element to associate a website with a manifest. The example also shows how to use [[!HTML]]'s link and meta elements to give the web application a fallback name and set of icons.

<!doctype>
<html>
<title>Store finder - search</title>

<!-- Startup configuration -->
<link rel="manifest" href="manifest.json">

<!-- Application metadata -->
<meta name="application-name" content="Store Finder">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<link rel="icon" sizes="512x512" href="hi_def.png">

Use cases and requirements

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

Common conventions and dependencies

The [[\GetOwnProperty]] operation, and the Type(x) notation are defined in [[!ECMASCRIPT]]. Processing also relies on various algorithms defined in [[!HTML]], [[!FETCH]], and [[!URL]].

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.

Display modes

A display mode describes the manner in which a developer would like the web application to be shown to a user (e.g., in fullscreen). Display modes are intended to correspond to the user interface metaphors and functionality in use on a given platform.

Once a user agent applies a particular display mode to a web application, it becomes the default display mode for the top-level document of the browsing context (i.e., it is used as the display mode for all top-level documents to which the window is navigated). Other specifications, as well as the end user, MAY override the default display mode.

When a display mode is not supported by a user agent, its fallback mode MUST be used instead.

The display modes values are as follows:

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 is the fallback display mode to be used as the default if there is no valid display member in the manifest, or none of the other display modes are supported by the user agent. This display mode MUST be supported by the user agent.
minimal-ui
Same as standalone, but MUST 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 MAY include other platform specific UI elements, such as "share" and "print" buttons or whatever is customary on the platform and user agent.
minimal-ui fallback mode is browser.
standalone
Opens the web application as close as possible as a standalone application. The user agent SHOULD make the web application look like a native application on the running platform. Often, that will include having a different window, its own icon in the application switcher, etc. The web application MUST not have UI elements for controlling navigation, but MAY include other UI elements such as a status bar.
standalone fallback mode is minimal-ui.
fullscreen
Opens the web application without any user agent chrome and takes up the entirety of the available display area.
fullscreen fallback mode is standalone.

Manifest

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.

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, or the resource has a well-known manifest.

Obtaining a manifest

A user agent can obtain a manifest either from a top-level document or by fetching it directly from a [[!URL]] (independently of a top-level document).

A user agent is said to have obtained a manifest from a top-level document when the manifest is associated with a document through either the manifest link type or through the well-known manifest.

Conversely, a user agent is said to have obtained a manifest directly when the user agent fetches the manifest independently of any top-level document. For example, a user agent fetches a manifest from a URL without first navigating to a document or the user agent makes use of the well-know manifest without first navigating to the web application.

Fetching a manifest

The steps for fetching a manifest are given by the following algorithm. It takes a URL url as an argument. This algorithm will return either a response or an error.

  1. Let response be the result of fetching the manifest from url.
  2. Return response.

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"
              /* ... */
            }

Processing the manifest

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.

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 member or value caused the condition was absent from the manifest document.

The 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. This is to avoid issues related to monkey patching.

  1. Let manifest be the result of parsing text. If parsing throws an error:
    1. Issue a developer warning.
    2. Set manifest to be the result of parsing the string "{}".
  2. Extension point: process any proprietary and/or other supported members at this point in the algorithm. Issue a developer warning for any unsupported members.
  3. Let start URL be the result of running the steps for processing the start_url member, with either the document's URL or an application-specific URL (e.g., "app://") as the base URL.
  4. Let display mode be the result of running the steps for processing the display member with manifest as the argument.
  5. Let orientation be the result of running the steps for processing the orientation member with manifest and display mode as arguments.
  6. If orientation is not the empty string, let it serves as the default orientation for all top-level browsing contexts of the web application.
  7. Let name be the result of running the steps for processing the name member.
  8. If name is undefined or the empty string:
    1. If the user agent obtained a manifest from a top-level document, attempt to derive the name of the Web application from the top-level document and set name to be the result (i.e., use [[!HTML]]'s application-name or title element).
    2. If no suitable name is found in the top-level document, or the user agent obtained a manifest directly, then set name to be an implementation specific string that can serve as a suitable name for the web application.
  9. Let icons be the result of running the steps for processing the icons member.
  10. If icons contains no items:
    1. If the user agent obtained a manifest from a top-level document, attempt to derive the icons for the Web application from the top-level document. For example, an icon link type or a favicon.ico can serve as suitable fallbacks.
    2. If no suitable icons are found in the top-level document, or the user agent obtained a manifest directly, then provide implementation specific icon that can serve as suitable icon for the web application.
  11. Otherwise, treat icons as the default icons for the web application.
  12. Let set of directives be the result of running the steps for processing the csp member.
  13. If set of directives is undefined, then skip this substep:
    1. For any subsequent fetch of a resource that is associated with a manifest manifest, append a header named "Content-Security-Policy" with value set of directives to its response headers.

Updating the manifest

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 updating or discarding the name, icons, or whatever other members have 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.

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

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.

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.

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 the user agent obtained a manifest from a top-level document, the icons in the manifest override any icons listed in the [[!HTML]] document. However, if no icons are listed in the manifest (or none of them are found to be suitable during processing), the user agent will fall back to trying to use any found in the HTML document. This fall back behavior is enforced during the steps for processing a manifest instead of in this section.

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 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. Let type be the result of running the steps for processing the type member of an icon passing potential icon.
    4. If type is an error, move onto the next item in orientations (if any are left).
    5. Let sizes be the list that result from running the steps for processing a sizes member of an icon passing potential icon.
    6. Let icon be an object with properties src, type, sizes, whose values are src, type and sizes respectively.
    7. Append icon to icons.
  4. Otherwise, if unprocessed icons is not an array:
    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.

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. 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 mode and rerun this step.
  5. Return value.

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.

Note: Once the web application is running, other means can change the orientation of of a top-level browser ontext (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 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.

start_url member

The start_url member is a string that represents the 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 and a URL base URL. This algorithm returns a valid URL.

  1. Let value be the result of calling the [[\GetOwnProperty]] internal method of the manifest with argument "url".
  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 base URL.
  4. Let potential URL be the result of parsing value using base URL as the base URL.
  5. If potential URL is failure, return base URL.
  6. Otherwise, return potential URL.

csp member

The csp member is a string that represents a supplemental security policy. The string is a valid supplemental security policy if it matches the policy production defined in [[!CSP11]].

The csp member supplements the policy delivery mechanisms defined in [[!CSP11]], and allows the author to indicate that the user agent is to enforce a supplemental security policy (according to the rules of enforcing multiple policies [[!CSP11]]) for a resource associated with a manifest.

The steps for processing the csp member is given by the following algorithm. The algorithm takes a manifest manifest as an argument, and returns a valid supplemental security policy or undefined.

  1. Let value be the result of calling the [[\GetOwnProperty]] internal method of manifest with argument "csp".
  2. Let type be Type(value).
  3. If type is not "string", and is not undefined, then issue a developer warning that the type of the policy is invalid, and return undefined.
  4. Let set of directives be a set returned by the parse a policy [[!CSP11]] algorithm, that takes value as argument.
  5. If set of directives matches the policy production [[!CSP11]], return set of directives, otherwise, issue a developer warning that the policy is invalid and return undefined.

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.

In cases where more than one link element with a manifest link type appears in a document, the user agent MUST use the first inserted link element and ignore all subsequent link elements with a manifest link type (even if the first element was erroneous).

The appropriate time to fetch the manifest is when the external resource link is created or when its element is inserted into a document, whichever happens last. However, 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).

To process a fetched manifest, the user agent MUST run the steps for processing a manifest.

Extending the manifest

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

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.

Proprietary extensions to the manifest

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

The following is an example of two hypothetical vendor extensions.

{
  ...
  "webkit_fancy_feature": "some/url/img",
  "moz_awesome_thing": { ... }
  ...
}

Icon object and its members

Each icon object represents an icon for an application, suitable to use in various contexts (e.g., an application menu).

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

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 key 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. For each resulting keyword:
    1. Convert keyword to ASCII lowercase.
    2. If sizes doesn't already contain keyword, then add the resulting keyword to sizes.
  6. Return sizes.

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", then:
    1. If type is not "undefined", issue a developer warning that the type is unsupported.
    2. Return undefined.
  4. Parse value using manifest URL as the base URL and return the result.

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.

IANA considerations

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

The "manifest.json" well-known URI

The well-known manifest is a manifest that a user agent fetches in the following manner. If a user agent attempts to obtain a manifest from a top-level document, but no manifest link type is declared, the user agent MUST attempt to fetch a manifest from the absolute URL obtained by resolving the URL "/.well-known/manifest.json" against the document's address. The user agent can then use the resulting manifest as if the page had declared that manifest using the manifest keyword.

This specification registers the "manifest.json" well-known URI in the Well-Known URI Registry as required by [[!RFC5785]].

URI suffix:
manifest.json
Change controller:
Web Applications (WebApps) Working Group
Specification document(s):
This document is the relevant specification.

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 considerations:

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, 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 [[!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]].

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.

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

Acknowledgments

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