Core API Proposal

Because browsers supported different add-on models, extension authors wound up creating divergent codebases and delivering different browser-specific add-ons. This Community Group's goal is to make browser extension code much more interoperable across browsers by specifying common extension interfaces and well-defined browser behavior. This will allow extension authors to greatly reduce or eliminate the rework necessary to create extensions that target different browsers.

Here's a possible roadmap for this work:
1. Identify the core objects and manifest keys
2. Define interop behavior and specific APIs (functions, events and associated types)
3. Clarify CSP security, browser-specific API syntax and packaging
4. Iterate

We would like to suggest our Community Group start by 1) identifying a set of core interoperable objects and associated manifest keys. We think this core should provide the necessary functionality that extension authors will need for: page modification, browser UI augmentation and network request modification. Below is a proposed set of core objects that we think meets this criteria.

Next, our Community Group can 2) document and discuss the browser behavior (to ensure interoperability) and specific functions/events for each object (e.g. browserAction.setIcon(), pageAction.onClicked(), tabs.sendMessage(), etc.). Then we can move on to specify 3) the security model, the method for browsers to provide unique API that aren't in the standard and the packaging format.

For all stages, we can use GitHub to store the documents and update them. Florian has offered to grant write permission to Community Group members to allow drafts to be submitted.

What do other members think? Is this the right approach? Regarding the objects below, what is missing? Or unnecessary?

Sincerely,
Mike Pietraszak & John Hazen, Microsoft
Kris Maglione & Andy McKay, Mozilla
Shwetank Dixit & Bruce Lawson, Opera

Proposed core APIs:
  browserAction
  contextMenu
  extension
  i18n
  pageAction
  runtime
  tabs
  webNavigation
  webRequest
  windows

Proposed manifest format:
// Before parsing the manifest, standards-compliant browsers are expected to pre-scan
// and remove "//" comments. After this step the manifest.json file format for browser
// extensions is expected to be fully JSON compliant. Malformed JSON files are not supported.
//
// Other manifest keys that are well-formed JSON but are not listed here must be ignored.
//
// Note that some fields marked as Optional here are required by vendor-specific distribution Stores.

{
  "name": "The Name of Your Extension",             // Required
  "version": "Your Extension Verison",              // Required
  "default_locale": "en",                           // Required if locales are used. Otherwise, not allowed

  "description": "Description for Your Extensions",
  "icons": {...},
  "developer": {
       "name": "Your Name or Company",
       "url": "Company Website"
  }

  // Note: Some browsers may support either browser_action or page_action, but not both
  "browser_action": {
      "default_icon": {...},                        // Same format as "icons"
      "default_popup": "Page URL",
      "default_title": "Title string"
  },
  "page_action": {...},                             // Same format as "browser_action"

  "browser_specific_settings": {
       "<browser_name>": {                          // Examples "gecko","opera","edge"
            "<key>": "<value>"                      // Examples "strict_min_version": "42.0", "id": "addon@example.com"
       }
  },

  "background": {
      "page": "Page URL",                           // Only one of "page" or "scripts" may be specified, but not both
      "scripts": [],                                // Only one of "page" or "scripts" may be specified, but not both
      "persistent": false                           // Required if "background" is specified
  },

  "content_scripts": {
      "all_frames": false,
      "css": [],
      "exclude_matches": [],
      "js": [],
      "matches": [],
      "run_at" : "document_start"                   // Also "document_end", "document_idle"
  }

  "content_security_policy": "<policy-string>",

  "manifest_version": 2,                            // Not used

  "required_keys": [],                              // If a browser does not recognize a key in the list, it must
                                                    // reject the manifest (e.g. "sidebar_action")
                                                    // Future keys may be required to be in the list if used.

  "permissions": {
       "activeTab",
       "contextMenus",
       "storage",
       "tabs",
       "webNavigation",
       "webRequest",
       "webRequestBlocking",
       "<url-pattern>"                              // Examples "http://*/*", ""
  },

  "web_accessible_resources": [...]
}