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.

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.

Usage Examples

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

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.

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.

Installability signals

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:

contains a manifest with at least a name member and
a suitable icon.

is served over a secure network connection.

has a sensible content security policy.

is able to responsibly adapt to display on a variety of screen
sizes, catering for both mobile and desktop.

is able to function without a network connection.

is repeatedly used by the end-user over some extended period of
time.

has been explicitly marked by the user as one that they value and
trust (e.g., by bookmarking or "starring" it).

And so on...

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

A string targetURL is said the be within scope of
navigation scope scopeURL if the following algorithm returns
true:

If scopeURL is undefined (i.e., it is
unbounded because of an error or it was not declared in the
manifest), return true.

Let target be a new URL using targetURL as
input. If target is failure, return false.

If target is same origin as scope and
target's pathname starts with
scope's pathname, return true.

Otherwise, return false.

Enforcing the navigation scope depends on [[!HTML]]'s navigate
algorithm. As such, the following algorithm monkey patches [[!HTML]].
Bug
27653 has been filed to address this.

The user agent MUST navigate the application context as per [[!HTML]]'s
navigate algorithm with exceptions enabled. If the URL being navigated
to is not within scope of the navigation scope, then the user
agent MUST behave as if the application context is not allowed to
navigate: this provides the ability for the user agent to perform
the navigation in a different browsing context - or in a different user
agent entirely. If during the handle redirects step of HTML's navigate algorithm, if the redirect URL is not
within scope, abort HTML's navigation algorithm with a
SecurityError.

A developer specifies the navigation scope via the
scope member. In the case where the
scope member is missing or in error, the navigation
scope is treated as unbounded (represented as the value
undefined). In such a case, the manifest is applied to all
URLs the application context is navigated to (see related
security considerations).

Security considerations

When the navigation scope is unbounded and a display
mode other than browser is being applied, it is
RECOMMENDED that user agents signal to the end-user when security
and/or privacy sensitive navigations occur. The manner of signaling
is left up to implementers, but can include things like showing the
URL of the application context, dropping out of fullscreen to the
browser display mode. Examples of security and/or privacy sensitive
navigations include, but are not limited to:

the application context being navigated from a secure
connection to an insecure connection (or vice versa).

This specification distinguishes between behavior in first-party and
third-party contexts. In particular, if a scope member
is declared in the manifest, it is not possible to navigate the
top-level browsing context to somewhere outside the scope while the
manifest is being applied. That's not to say that the web application
cannot be navigated: just that the set of URLs to which the manifest
applies is restricted by the navigation scope.

Deep links

The concept of a deep link is useful in that it allows
hyperlinking from one installed application to another. This can be
from a native application to an installed web application
(and possibly vice versa!). Theoretically, this can provide
seamless context switching between native and web applications
through standard hyperlinks. And in the case where a particular web
application is not installed, then the OS can just open the
link in the user's preferred web browser.

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.

When the display member is missing, or if there is no
valid display member, the user agent uses the
browserdisplay mode as the default display
mode. As such, the user agent is REQUIRED to support the
browserdisplay 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.

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.

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 fullscreendisplay mode is orthogonal to, and works
independently of, the [[WHATWG-FULLSCREEN]] API. The
fullscreendisplay 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.

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.

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.

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.

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

Manifest life-cycle

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.

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:

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

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.

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.

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 URLmanifest URL, which represents the location of the
manifest, and a URLdocument URL. The output from
inputting an JSON document into this algorithm is a processed
manifest.

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.

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.

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

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.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of manifest
with argument "short_name".

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
manifestmanifest, a URLmanifest
URL, a URLdocument URL, and a URL start
URL. This algorithm returns a URL or
undefined.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of the manifest
with argument "scope".

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.

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

Let icons be an empty list.

Let unprocessed icons be the result of calling the
[[\GetOwnProperty]] internal method of manifest with
argument "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.

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 browserdisplay mode.

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 manifestmanifest and display modedisplay mode as an argument, and returns a string.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of manifest
with argument "orientation".

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
manifestmanifest, a URLmanifest
URL, and a URLdocument URL. This algorithm
returns a URL.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of the manifest
with argument "start_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.

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:

The developer has included two icons at the same size, but in
different formats. One is explicitly marked as WebP through the
type member. If the user agent doesn't support WebP, it
falls back to the second icon of the same size (and density). The
media type of this icon can then be either determined via a HTTP
header, or can be sniffed by the user agent once the first few bytes
of the icon are received.

The developer wants to use an SVG icon for devices with at least
2dppx as the display density and only when the available dimensions
are at least 72px. She has found that the SVG file looks too blurry
at small sizes, even on high-density screens. To deal with this
problem, she's included an SVG icon that is only used when the
dimensions are at least 72px and the pixel density is at least 2dppx.
Otherwise, the user agent uses the ICO file (hd_hi.ico), which
includes a gamut of icons individually tailored for small display
sizes.

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.

If [[\HasOwnProperty]] internal method of icon passing
density as the argument returns false:

Return 1.0.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of icon passing
"density" as the argument.

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 objecticon. This algorithm will return a
set.

Let sizes be an empty set.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of icon passing
"sizes" as the argument.

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 objecticon, and a URLmanifest
URL, which is the URL from which the manifest
was fetched. This algorithm will return a URL or
undefined.

Let value be the result of calling the
[[\GetOwnProperty]] internal method of icon passing
"src" as the argument.

Common conventions and dependencies

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.

IANA considerations

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

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" (particularly 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.

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

Extensibility

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.

Proprietary manifest members

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.

Relationship to HTML's link and meta elements

An extensive discussion of why we chose to use JSON instead of HTML
meta/link tags for this specification is
available on GitHub and on the
www-tag
list. Below is a short summary of the key points raised in those
discussions.

The document format defined in this specification provides a unified
means of encapsulating metadata about a Web application in a way that
we hope will avoid existing pitfalls with both proprietary and
[[!HTML]]'s meta/link tags. Those pitfalls
include:

Developers have to duplicate the icons and application name in each
page of a web site, leading to significant redundancy across pages.
This is compounded if that information never gets used by the user
agent (e.g., the user never bookmarks the web application).

Spreading metadata across multiple documents can cause data to fall
out of sync.

If the metadata for a web application lives in a HTML document,
that significantly increases the cost to user agents (and users) of
checking for updates to the metadata of a site. Since the HTML file is
likely to change often, it means that a user agent will often have to
download the whole HTML file in order to check if any of the relevant
meta tags have changed. If this resource contains inlined resources
like JavaScript, images, or stylesheets, this could be a non-trivial
download.

Although it would be unrealistic to think that this specification won't
bring its own set of problems, externalizing this data in the form of a
manifest solves the problems described above. These problems are solved
by:

Making the manifest externally linkable: External manifest files
can be cached as external resources, saving both bytes and redundancy
in the markup.

Flexible value types: unlike HTML attributes, members of the
manifest can represent data using complex types, such as objects and
arrays, rather than just strings. This solves the problem of the
awkward and highly inconsistent formats the values of proprietary
meta tags are currently using, especially when a tag's
value contains several sub-values.

In addition, standardizing the functionality currently provided by the
various meta tag-based solutions within the manifest
solves the problem of having to declare large number of proprietary and
standard [[!HTML]] tags that all achieve the same thing. Of course,
this hinges on the standard actually getting implemented by browsers
and those browsers getting widely deployed to users: if this happens,
the Web community might be able to retire many of the proprietary
meta tags plaguing the Web at the time of writing. More
information about the proprietary tags can be found in the
Use
Cases and Requirements for Installable Web Apps.

Lastly, this specification does not make the standardized solutions
found in [[!HTML]] redundant. When members like the name
or icons is missing from the manifest, user agents can
search in a manifest's owner [[!HTML]] document for things like icons
and the application name (or a user agent might even fallback to
proprietary tags/metadata, if they are present in a document).