THE SYSAPPS WG IS NOT LONGER MAINTAINING THIS DOCUMENT. The document is now maintained by the WebApps Working group. An updated draft of the Manifest specification available on GitHub.

An application manifest is a JSON document that describes various aspects of a web application. Some of these aspects are presentational, while others aspects have security implications.

Introduction

An application manifest consists of a top-level object (the manifest root) and one or more members, some of which can themselves contain objects.

Example manifest

The following shows a typical application manifest.

{
  "name": "The Example App",
  "description": "Exciting Open Web development action!",
  "launch_path": "/",
  "version": "1.0",
  "icons": {
    "16": "/img/icon_16.png",
    "48": "/img/icon_48.png",
    "128": "/img/icon_128.png"
  },
  "developer": {
    "name": "Foo Corp.",
    "url": "http://example.org/dev"
  },
  "appcache_path": "/cache.manifest",
  "locales": {
    "es": {
      "description": "¡Acción abierta emocionante del desarrollo del Web!",
      "developer": {
        "url": "https://example.org/dev/es-ES"
      }
    }
  },
  "default_locale": "en",
  "screen_size": {
    "min_width": "600",
    "min_height": "300"
  },
  "required_features": ["touch", "geolocation", "webgl"],
  "permissions": {
    "contacts": {
      "description": "Required for auto-completion in the share screen",
      "access": "read"
    }
  },
  "fullscreen": "true",
  "release_notes": {
    "1.0": "Bugs fixed. New exciting effects. Ready for an official release!",
    "0.5": "First alpha version with still some bugs but already fun!"
  }
}

THE SYSAPPS WG IS NOT LONGER MAINTAINING THIS DOCUMENT. The document is now maintained by the WebApps Working group. An updated draft of the Manifest specification available on GitHub.

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

Processing the manifest

Algorithms in this section use the conventions described in ECMA-262 section 5.2, such as the use of steps and substeps, and so on. The ToBoolean, ToNumber, ToUint16, ToInt32, ToUint32, ToString, and ToObject abstract operations and the Type(x) notation referenced in this section are defined in [[!ECMA-262-51]]. In the algorithms, to ignore means that the user agent MUST act as if the author had not declared the particular member in the application manifest document.

Certain error conditions can result in an application manifest being treated as an invalid manifest. An invalid manifest is an application manifest that is deemed to be non-conforming in such a way that it would not be possible for the user agent to continue processing (e.g., it can't be parsed by the JSON parser because of a syntax error). In such a case, the user agent MAY report the error to the user in a user-agent-specific manner, MAY navigate to an error page to report the error, or MAY ignore the error and do nothing. In either case, when a step results in an invalid manifest the user agent MUST abort whatever steps caused the condition.

The steps for fetching an application manifest are given by the following algorithm. This algorithm can be applied equally to manifests fetched from HTTP/S or those derived over the app URI scheme.

  1. Let url be a URL with character encoding [[!UTF-8]] that represents the application manifest.
  2. Let origin be ??.
  3. Resolve url relative to origin. If resolving the URL fails, then treat this as an invalid manifest.
  4. Let response body be the response entity body resulting from of asynchronously fetching url, with origin as the origin, and with the force same-origin flag set.
  5. Let text be the result of running utf-8 decode on the byte stream response body.
  6. return text.

The steps for processing an application manifest are given by the following algorithm.

  1. Let text be the text to be processed.
  2. Let manifest result of invoking the parse function of the JSON object defined in [[!ECMA-262-51]] with text as its only argument. If parsing throws an exception, then treat this application manifest as an invalid manifest.
  3. Let present be the result of calling [[\HasOwnProperty]] internal method of manifest with argument key.
  4. If present is false, then treat this application manifest as an invalid manifest.
  5. Let default locale be the result of running the steps for processing the default_locale member.
    1. If default locale is not undefined:
      1. from default locale.
      2. If there is no occurance of default locale in the application locales list, then insert default locale immediately before the last item of the application locale list.

        For example, given default locale "jp", and an application locale list containing "en-US,*", then the application locale list would become ["en-US", "jp", "*"].

  6. Let name be the result of running the steps for processing the name member.
  7. Let launch path be the result of running the steps for processing the launch_path member:
    1. If launch path resulted in an error, then treat this as an invalid manifest.
  8. Let description be the result of running the steps for processing the description member.
  9. Let fullscreen be the result of running the steps for processing the fullscreen member.
  10. ...
  11. Optionally, ignore all other members.

Types and bindings

As the manifest format is a [[!JSON]] document, this doucment relies on the types defined in [[!JSON]] specification: namely object, array, number, and string. Strict type checking is not enforced by this specification. Instead, each member's definition specifies the steps to required to process a particular member.

In additon, for the purpose of validity checking, this specification relies on the the following types:

Relative URL
The concept of a relative URL is defined in the [[!URL]] specification.
Absolute URL
The concept of an absolute URL is defined in the [[!URL]] specification.

Internationalization and localization

The user agent's locales is an ordered list of language tags that are used to represent the end-user's language(s) and localization preference for experiencing content; these are essentially equivalent to the language tags sent by the user agent through the Accept-Language [[HTTP11]] header, but without the quality values.

The case sensitivity and case mapping for language tags is the same as that defined in section 6.1 of the ECMAScript Internationalization API Specification [[!ECMASCRIPT-I18N]].

As there are numerous ways a user agent can derive the end-user's preferred languages and regional settings (e.g., the end user might have set them in the user agent's preferences), the means by which those values are derived are left up to the implementation. The first item of the user agent's locales represents the user's most preferred language range (i.e., the language/region combination the user agent assumes the end-user most prefers), followed by the next most preferred language range, and so forth.

A language tag is a string that matches the production of a Language-Tag defined in the [[!BCP47]] specifications (see the IANA Language Subtag Registry for an authoritative list of possible values, see also the Maintenance Agency for ISO 3166 country codes). That is, a language range is composed of one or more subtags that are delimited by a U+002D HYPHEN-MINUS ("-"). For example, the 'en-AU' language range represents English as spoken in Australia, and 'fr-CA' represents French as spoken in Canada. Language tags that meet the validity criteria of [[!RFC5646]] section 2.2.9 that can be verified without reference to the IANA Language Subtag Registry are considered structurally valid.

The CanonicalizeLocaleList, BestAvailableLocale LookupMatcher, BestFitMatcher, ResolveLocale, LookupSupportedLocales BestFitSupportedLocales SupportedLocales.

Localizable members

A localizable member is member of the application manifest that can appear in the locales member.

The steps for retrieving a localizable member from the manifest are given by the following algorithm. The algorithm prioritizes returning the localized version of a member over one where the locale is unknown. The algorithm returns either a value from the namifest or undefined.

  1. Let manifest be the JSON-parsed object representation of the application manifest.
  2. Let default app locale be the string that represents the default locale for the application manifest.
  3. Let identifier be a string that represents the name of the member being sought.
  4. Let locales list be a copy of the user agent's locales.
  5. If default app locale is not undefined, append default app locale to locales list.
  6. If the manifest has a property whose name is "locales", then for each range in the locales list in order:
    1. If the "locales" property has a property whose identifier matches range, then:
      1. if return the value of the matching property and terminate this algorithm.
    2. Otherwise, if the "locales" property has a property whose identifier matches the default app locale, then return the value of the matching property and terminate this algorithm.
  7. If the manifest root has its own property named prop, return the value of the property.
  8. Return undefined.

name member

The name localizable member is a string that represents the name of the hosted web application or packaged application, that is used, for example, in an application menu or in other contexts.

Note: The name member needs to be present in the application manifest for the user agent to treat an application manifest as valid.

The steps for processing the name member is given by the following algorithm. The algorithm takes an application manifest as an argument and returns either an error or a string:

  1. Let key be the string "name".
  2. Let value be the result of running the steps for retrieving a localizable member from the manifest, with key as the member being sought.
  3. Let result be the result of calling ToString(value).
  4. Return the result.

description member

The description localizable member is a string that describes to the end-user the author's intended purpose for the application (i.e., what the function and utility of the application is, etc.).

The steps for processing the description member are given by the following algorithm. The algorithm takes an application manifest as an argument and returns a string or undefined:

  1. Let key be the string "description".
  2. Let result be undefined.
  3. Let value be the result of running the steps for retrieving a localizable member from the manifest, with key as the member being sought.
  4. If value is not undefined, let result be ToString(value).
  5. Return result.

default_locale member

The default_locale member is a language tag that represents:

When the default_locale member is missing or in error, the content at the root of the manifest is said to have an unknown locale.

The steps for processing the default_locale member are given by the following algorithm. The algorithm takes the JSON-parsed application manifest as an argument. The algorithm returns a string, which is either a language tag or the string "*" (which is used to represent an unknown locale).

  1. Let result be "*".
  2. Let key be "default_locale".
  3. Let present be the result of calling [[\HasOwnProperty]] internal method of manifest with argument key.
  4. If present is true:
    1. Let value be the result of calling the [[\GetOwnProperty]] internal method of manifest passing key as the argument.
    2. Let tag be ToString(value).
    3. Let valid tag the result of calling the abstract operation IsStructurallyValidLanguageTag with tag as the argument.
    4. If valid tag is true, then:
      1. Let result be the result of calling the abstract operation CanonicalizeLanguageTag, passing tag as the argument.
  5. Return result.

launch_path member

The launch_path localizable member is a relative URL that represents a resource within the origin of the application that is loaded when the application is launched.

The steps for processing the launch_path member are given by the following algorithm. The algorithm returns either a string, and error, or undefined.

  1. Let result be undefined.
  2. Let key be the string "launch_path".
  3. Let present be the result of calling [[\HasOwnProperty]] internal method of manifest with argument key.
  4. If present is true:
    1. Let path be ToString(value).
    2. Let url be the result of parsing path.
    3. If url is not a relative URL, then return an error and terminate this algorithm.
    4. Set result to be the value of url.
  5. Return result.

icons member

The icons localizable member is a icons object that represents a set of icons that the application can make use.

developer member

The developer localizable member is a developer object that represents the person, persons, or entity that created the application.

locales member

The locales member is a localized-data object represents the localized data of the manifest.

appcache_path member

The appcache_path localizable member is an relative URL that represents a resource to be used as the application's cache manifest [[!OFFLINE-WEBAPPS]].

The steps for processing the appcache_path member are given by the following algorithm. The algorithm returns either a string, and error, or undefined.

  1. Let result be undefined.
  2. Let key be the string "appcache_path".
  3. Let present be the result of calling [[\HasOwnProperty]] internal method of manifest with argument key.
  4. if present is true:
    1. Let path be ToString(value).
    2. Let url be the result of parsing path.
    3. If url is not a absolute URL, then return an error and terminate this algorithm.
    4. Set result to be the value of url.
  5. Return result.

version member

The version localizable member is a string represents the version of the application as designated by the author. The version has no specific meaning in the context of this specification; it's utility is solely for informative purposes.

The steps for processing the version member is given by the following algorithm. The algorithm returns either undefined or a string:

  1. Let result be undefined.
  2. Let key be the string "version".
  3. Let present be the result of calling [[\HasOwnProperty]] internal method of manifest with argument key.
  4. If present is true:
    1. Let value be the result of running the steps for retrieving a localizable member from the manifest, with key as the member being sought.
    2. Let result be the result of calling ToString(value).
  5. Return the result.

screen_size member

The screen_size member is a screen sizes object that represents the minimum visual dimensions (in CSS pixels [[!CSS21]]) the application needs to render correctly.

ISSUE: This should probably be dropped. If a user zooms in, or even if the screen is too small, then this won't really help. This is also meaningless when the application is full screen. Also, this needs to play with @viewport and meta viewport.

required_features member

The required_features member is an array that represents the feature set the application needs in order to run correctly.

Standard features of the Web platform should not be on this list (e.g., geolocation, webgl, etc.).

fullscreen member

The fullscreen localizable member is a boolean that represents a hint to the user agent that indicates that the application provides the best user experience when shown in fullscreen (i.e., the application is presented without any use interface components of the underlying system). When the value is missing, it defaults to false.

The steps for processing the fullscreen member are given by the following algorithm:

  1. Let value be the value of the fullscreen member or false if the value is missing.
  2. Let result of calling ToBoolean(value).
  3. return result.

release_notes member

The release_notes localizable member is a release notes object that represents a change history for the application from one version to another.

permissions member

The permissions localizable member is a permissions object that represents a list of permissions that the application requires to function.

Release notes object and its members

A Release notes object ...

Permissions object and its members

The permissions object...An application SHOULD list every API that is considered to require user permission in this field. Usage of an API without a corresponding entry in the manifest SHOULD fail. The field is an object, with each property name specifying a single permission, and object containing the following fields:

Description member

The description member represents a human readable string specifying the intent behind requesting use of this API.

ISSUE: This seems unhelpful. The developer can just lie.

access member

The access is a string describing the type of access required for this permission. This field can be mandatory for a certain subset of permissions. Its value is one of:

read:
...
readwrite:
...
readcreate:
...
createonly:
...

icons object and its members

The icons object is an object that represents the icons suitable for various dimensions.

Paths beginning with "/" are treated as relative to the origin of the app.

Screen size object and its members

The screen size object . The screen sizes object values are only hint for the user agent

Localized-data object and its members

The localized-data object contains specific overrides of data contained in the application manifest.

Members

Each locale key is a langauge tag, and contains a sparse representation of localized parts of the manifest. The data of the locales members override the corresponding member in a localized user interface.

The user agent MAY ignore some values if localizing the property doesn't appear to be legit.

It is RECOMMENDED that the locales keys match the actual content localization to give a hint to the user that the application will be available in their language or not. Failing to provide a perfect matching between the content localization and the locales keys will not create any technical problems but will have bad consequences with regard to the user experience and developer reputation.

Note: if the locales property is set, the default_locale needs to also be set.

Developer object and its members

name member

The name member of the developer object represents the name of the developer.

The steps for processing the name member of the developer object is given by the following algorithm. The algorithm returns undefined or a string:

  1. Let O be the result of running the steps for retrieving a localizable member from the manifest, with "developer" as the member being sought.
  2. Let result be undefined.
  3. If Type(O) is "Object"
  4. Set result be the result of calling ToString(value).
  5. Return the result.

url member

The url an URL pointing to the developer's website.

Media Type

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

The media type for an application manifests is application/webapp-manifest+json.

If the protocol over which the manifest is transferred supports the [[!MIME]] specification (e.g. [[!HTTP11]]), it is RECOMMENDED that the application manifest be labeled with the media type for an application manifests.

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

As the application manifest format is JSON and will commonly be encoded using [[!Unicode]], the security considerations described in [[!JSON]] and [[!UTR36]] apply. In addition, implementers 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.

The manifest document allows authors, through the permissions and required_features, to request permission to enable security sensitive APIs. As these APIs are outside the scope of this specification, significant caution needs to be taken when granting an application the capability to use a feature. Features themselves define their own security considerations.

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

As web applications can contain content that is able to simultaneously interact with the local device and a remote host, implementers 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, implementers 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 IRIs within certain members of a the application manifest, implementers need to consider the security considerations discussed in the [IRI] specification. Implementations intending to display IRIs and IDNA addresses found in the application manifest are strongly encouraged to follow the security advice given in [[!UTR36]].

Applications that use this media type:
Web browsers
Additional information:
Magic number(s):
N/A
File extension(s):
.webapp
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.

Acknowledgments

TBW