Labs/Apps/Manifest

Note: This is an old page. For the latest version of the Open Web App manifest, see App manifest.

Apps/Manifest

Manifests

This page describes the Application Manifest format for the Open Web Applications proposal.

Why develop a new proprietary format when there are open standards available with almost identical functionality? (See the discussion tab)

The Application Manifest is a JSON-encoded data structure that describes an application to a user-agent.

The fields of the manifest are:

• name: A human-readable name for the application, for the default locale.

• description: A plain-text human-readable description of the application, for the default locale.

• base_url: The URL that is used as a base for relative URLs which follow. The base_url must belong to the application (see app_urls below for a definition of "belong").

• launch_path: The path that is appended to base_url to create the "launch URL" for the application, which is the page that is loaded when the application starts. An empty string is allowed, but the field is required. The string should be sanitized by libraries, e.g. ".." should be forbidden.

• app_urls: A list of URL prefixes, which must contain at least a scheme and hostname, but may optionally have a path portion. Any URL that begins with one these URL prefixes, with a full match on the scheme, hostname, and port of the manifest URL, is said to "belong" to the application, and should be consolidated into a single browsing experience by an application-aware browser. Incomplete hostnames, e.g. "http://www", will fail to match any application and are invalid. base_url must be included in the set defined by app_urls, and the manifest is invalid if it is not.

• capabilities: a list of string tokens describing advanced web browser capabilities that the application requests. Browser-native application repositories should prompt the user for permission to use these capabilities at installation time; the user is free to deny access to any or all of these permission requests, but this may cause the application to behave incorrectly.

• icons: a map of icon sizes to URLs, which are interpreted relative to the base_url, which should contain square images suitable for use as application icons. data URLs are legal in this field. The string should be sanitized by libraries, e.g. ".." should be forbidden in http URLs.

• developer: information about the developer of the application, suitable for use in repository and dashboard UIs
  • name: the name of the developer
  • url: the URL of an information site for the developer; the developer is free to place a URL that provides more detailed information about this app in this field

• defaultLocale: The locale identifier that was used for the root-level "name" and "description" fields. If not present, the value "en-US" is the default.

• locales: a map of local-specific overrides on the data contained in the manifest, which UIs should use to provide localized views. Each locale entry is keyed on a local code, and contains a sparse representation of the manifest; any field that is present in the locale value should override the matching field in the manifest. Locales are not allowed to override the capabilities field; a manifest that does so is invalid.

• release: A timestamp in ISO 8601 format representing when this version of the manifest came into effect.

Proposed Enhancements

Allowed External URLs

The Google "hosted applications" manifest proposal includes the notion of a "browseURL" list. These are URLs that the application is allowed to visit without causing the browser to treat the page load as "leaving" the application (and presumably opening a new window or tab).

If a browse_urls list were added to the manifest, user agents that implement app pinning would be required to implement this behavior.

Capabilities

Agreement on the syntax of the capabilities (or permissions, in some proposals) array will benefit cross-browser adoption of rich applications.

The W3C has a Permissions working group that has a first approximation of the list.

Proposed identifiers include:

• geolocation
• mediacapture
• file.read
• file.write
• contacts.read
• deviceinfo
• networkinfo
• sensorinfo

Auto-updating

Manifests do not normally need to be updated, since the application logic and resources are delivered using normal web caching rules.

However, to support automatic delivery of changes to the manifest (e.g. for new hostnames, icons, capabilities, or locales), an update URL could be saved with the manifest into the repository.

The update URL should not be part of the manifest, because the manifest could be installed by a curated source, such as a directory or store. The proposed feature is to accept an optional update URL as an arugment to the install() method. The domain of the update URL must match the base_url of the manifest.

Signed Manifests

To allow for detection of tampering with manifests, the installing page could optionally include a signature with the manifest. The signature would have to involve secrets that are unknown to the client, e.g. a private key known only to the installer.

It's important to be clear about the threat model against which a signature would try to protect, however -- if the attacker has full control of the user's file system, and can change a manifest, they could also change the browser, and replace the public keys stored in, or cached by, the browser, with different keys.

A signature could be part of a defense-in-depth strategy, however. To verify the signature, the browser would retrieve a public key for the installing site (over SSL), and verify that the manifest matched the signature that was stored with it. Any change to the manifest would cause the signature to fail, and the application could be silently discarded.

An Example Manifest

   {
     "name": "MozillaBall",
     "description": "Exciting Open Web development action!",

     "base_url": "https://mozillaball.mozillalabs.com",
     "launch_path": "",
     "update_path": "manifest/manifest.json",

     "app_urls": [
       "https://mozillaball.mozillalabs.com/"
     ],

     "capabilities": [
       "geolocation"
     ],
     "icons": {
       "16": "icon-16.png",
       "48": "icon-48.png",
       "128": "icon-128.png"
     },
     "developer": {
       "name": "Mozilla Labs",
       "url": "http://mozillalabs.com"
     }
     "locales": {
       "es": {
         "description": "¡Acción abierta emocionante del desarrollo del Web!",
         "developer": {
           "url": "http://es.mozillalabs.com/",
         }
       },
       "it": {
         "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
         "developer": {
           "url": "http://it.mozillalabs.com/"
         }
       }
     },
     "release": "2010-10-05T09:12:51Z"
   }