Source code
Revision control
Copy as Markdown
Other Tools
API Schemas
===========
Anything that a WebExtension API exposes to extensions via Javascript
is described by the API's schema. The format of API schemas uses some
JSON Schema provides a way to specify constraints on JSON documents and
the same method is used by WebExtensions to specify constraints on,
for example, parameters passed to an API function. But the syntax for
describing functions, namespaces, etc. is all ad hoc. This section
describes that syntax.
An individual API schema consists of structured descriptions of
items in one or more *namespaces* using a structure like this:
.. code-block:: js
[
{
"namespace": "namespace1",
// declarations for namespace 1...
},
{
"namespace": "namespace2",
// declarations for namespace 2...
},
// other namespaces...
]
Most of the namespaces correspond to objects available to extensions
Javascript code under the ``browser`` global. For example, entries in the
namespace ``example`` are accessible to extension Javascript code as
properties on ``browser.example``.
The namespace ``"manifest"`` is handled specially, it describes the
structure of WebExtension manifests (i.e., ``manifest.json`` files).
Manifest schemas are explained in detail below.
Declarations within a namespace look like:
.. code-block:: js
{
"namespace": "namespace1",
"types": [
{ /* type definition */ },
...
],
"properties": {
"NAME": { /* property definition */ },
...
},
"functions": [
{ /* function definition */ },
...
],
"events": [
{ /* event definition */ },
...
]
}
The four types of objects that can be defined inside a namespace are:
- **types**: A type is a reusable schema fragment. A common use of types
is to define in one place an object with a particular set of typed fields
that is used in multiple places in an API.
- **properties**: A property is a fixed Javascript value available to
extensions via Javascript. Note that the format for defining
properties in a schema is different from the format for types, functions,
and events. The next subsection describes creating properties in detail.
- **functions** and **events**:
These entries create functions and events respectively, which are
usable from Javascript by extensions. Details on how to implement
them are later in this section.
Implementing a fixed Javascript property
----------------------------------------
A static property is made available to extensions via Javascript
entirely from the schema, using a fragment like this one:
.. code-block:: js
[
"namespace": "myapi",
"properties": {
"SOME_PROPERTY": {
"value": 24,
"description": "Description of my property here."
}
}
]
If a WebExtension API with this fragment in its schema is loaded for
a particular extension context, that extension will be able to access
``browser.myapi.SOME_PROPERTY`` and read the fixed value 24.
The contents of ``value`` can be any JSON serializable object.
Schema Items
------------
Most definitions of individual items in a schema have a common format:
.. code-block:: js
{
"type": "SOME TYPE",
/* type-specific parameters... */
}
Type-specific parameters will be described in subsequent sections,
but there are some optional properties that can appear in many
different types of items in an API schema:
- ``description``: This string-valued property serves as documentation
for anybody reading or editing the schema.
- ``permissions``: This property is an array of strings.
If present, the item in which this property appears is only made
available to extensions that have all the permissions listed in the array.
- ``unsupported``: This property must be a boolean.
If it is true, the item in which it appears is ignored.
By using this property, a schema can define how a particular API
is intended to work, before it is implemented.
- ``deprecated``: This property must be a boolean. If it is true,
any uses of the item in which it appears will cause a warning to
be logged to the browser console, to indicate to extension authors
that they are using a feature that is deprecated or otherwise
not fully supported.
Describing constrained values
-----------------------------
There are many places where API schemas specify constraints on the type
and possibly contents of some JSON value (e.g., the manifest property
``name`` must be a string) or Javascript value (e.g., the first argument
to ``browser.tabs.get()`` must be a non-negative integer).
Specifically, these items are specified by using one of the following
values for the ``type`` property: ``boolean``, ``integer``, ``number``,
``string``, ``array``, ``object``, or ``any``.
Refer to the documentation and examples at the
items are defined in a schema.