Obtaining a manifest

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

A user agent is said to have obtained a manifest from a top-level document when a user navigates to a web application and she or he explicitly makes a request to bookmark the top-level document. For example, the user uses the browser's user interface to either bookmark or add the web app to the home screen. The manifest is associated with a document through either the manifest link relationship or through the well-known manifest - this includes via successful requests to bookmark a web application through the requestBookmark() method.

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

Processing the manifest

The steps for processing a manifest are given by the following algorithm. The algorithm takes a text string as 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.

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. 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.
3. Let display modes be the result of running steps for processing the display member with manifest as the argument.
4. Let default display mode be the first item of display modes.
5. Let orientations be the result of running the steps for processing the default_orientation member with manifest and default display mode as arguments.
6. From orientations, select a suitable orientation for the application and let that serve as the default orientation for as long as the application exists.
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. For example, if bookmarking was initiated from a [[!HTML]] document, and the document has any meta elements whose name attribute matches application-name, then process those elements as per [[!HTML]] and return the application name found. Using the value of the document's title is also suitable.
   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, if bookmarking was initiated from a [[!HTML]] document, icon link relationships, 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 or icons that can serve as suitable icons for the web application.
11. Otherwise, treat icons as the default icons for the web application.

Updating the manifest

A user agent MAY periodically check if the contents of a manifest has changed (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 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 bookmark details corresponding to the web application (e.g., by updating the name, icons, or whatever other members have been changed). For security reasons, 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 document.

The steps for processing the name member is given by the following algorithm. The algorithm takes a manifest as 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 not supported), 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 an array of strings, whose items are one or more display modes values. The items represent a developer's preferred display modes for the web application. Order in the array is significant, with the first item being the developer's most preferred, followed by the next most preferred and so forth. When the member is missing or erroneous, the user agent uses 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 set.

1. Let result be a set.
2. Let display values be the result of calling the [[\GetOwnProperty]] internal method of manifest passing "display" as the argument.
3. If display values is not an instance of Array:
   1. If Type(display value) is not "undefined", issue a developer warning that the type is not supported.
4. Otherwise, for each item in display values in order from first to last:
   1. If Type(item) is not "string", ignore this item and move onto the next item in display values (if any are left).
   2. Trim(item) and set item to be the resulting string.
   3. If item is not a display mode that the user agent supports, or result already contains item, ignore this item and proceed to the next.
   4. Otherwise, append item to result.
5. If result contains no items, add the fallback display mode to result.
6. Return result.

default_orientation member

The default_orientation member is an array of strings that serve as hints for the user agent as to the preferred screen orientations in which to display the web application. The possible values are any of the allowed orientations as defined in [[!SCREEN-ORIENTATION]]. Order within the array is significant, with the first item being the developer's most preferred, followed by the next most preferred and so forth. When the default_orientation member is missing, or all the declared items are unsupported, the user agent provides an implementation-specific default orientation for the web application.

Although the specification relies on the allowed orientations from the [[!SCREEN-ORIENTATION]] specification, it is OPTIONAL for a user agent to implement the [[!SCREEN-ORIENTATION]] API. Supporting the [[!SCREEN-ORIENTATION]] API is, of course, RECOMMENDED.

If the user agent chooses to use one of the allowed orientations in the orientations member, then that becomes the default orientation for the web application for as long as the application is running (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.

Note: Once the web application is running, other means can change the orientation of a document of the web application (such as via [[!SCREEN-ORIENTATION]] API).

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

1. Let result be a set.
2. Let orientations be the result of calling the [[\GetOwnProperty]] internal method of manifest passing "default_orientations" as the argument.
3. If orientations is not an instance of Array:
   1. If Type(orientations) is not "undefined", issue a developer warning.
4. Otherwise, for each item in orientations in order from first to last:
   1. If Type(item) is not "string", issue a developer warning, ignore this item and proceed to the next.
   2. Trim(item) and set item to be the resulting string.
   3. If item is not an orientation that the user agent supports, or result already contains item, or the item cannot be used together with mode ignore this item and proceed to the next.
   4. Otherwise, append item to result.
5. Return result.

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 activates a bookmark (e.g., when the user clicks on the icon of the web application from a device's application menu or homescreen). When the developer omits the start_url member from the manifest, the user agent can use either the URL of the document from which the web application was bookmarked or some other application-specific URL.

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 the bookmark is being created 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 not supported.
   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.

Linking to a manifest

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

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.

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 not supported.
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 not supported.
   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 not supported.
   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.

isHosted attribute

The isHosted attribute indicates if the web application was launched from a bookmark.

On getting the isHosted attribute, the user agent MUST return true if the web application was launched from a bookmark, or false otherwise.

requestBookmark() method

The requestBookmark() method provides a way for scripts to ask the user if they would like to bookmark the web application.

When the requestBookmark() method is invoked, the user agent MUST run the steps to request a bookmark.

The steps to request a bookmark are given by the following algorithm. The algorithm returns a promise.

1. Let promise be a newly-created promise.
2. If this method was not invoked as a result of explicit user action, then:
   1. Reject promise with new DOMException whose name is "SecurityError" and return.
3. If this method was not invoked from a top-level document of the browsing context, then:
   1. Reject promise with new DOMException whose name is "WrongDocumentError" and return.
4. Continue the following steps asynchronously.
5. If not already acquired, asynchronously attempt to fetch the manifest in the manner specified in the linking section of this document.
6. In a user-agent specific manner, allow the end user to make a choice as to whether they want to add the bookmark:
   1. If the end-user aborts the request to add the bookmark (e.g., they hit escape, or press a "cancel" button), then Reject promise with a new DOMException whose name is "AbortError" and return.
   2. Otherwise, resolve promise with undefined.
7. Return promise.

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