====== Gnome - Extensions - metadata.json ======

**metadata.json** is a mandatory file of every extension.

  * It contains basic information about the extension such as its UUID, name and description.
  * Some fields are mandatory, but there are a number of other optional fields too that metadata.json may contain.

----

===== A minimal example, with only mandatory fields =====

<file json metadata.json>
{
    "uuid": "example@blah",
    "name": "Example",
    "description": "This is an example extension.",
    "shell-version": [ "3.38", "40" ],
    "url": "https://sharewiz.net/gnome/extensions/example",
    "version": 1
}
</file>

----

===== A comprehensive example, including optional fields =====

<file json metadata.json>
{
    "uuid": "example@blah",
    "name": "Example",
    "description": "This is an example extension.",
    "shell-version": [ "3.38", "40" ],
    "url": "https://sharewiz.net/gnome/extensions/example",
    "version": 1
    "session-modes": ["user", "unlock-dialog"],
    "settings-schema": "org.gnome.shell.extensions.example",
    "gettext-domain": "example@blah",
}
</file>

----

===== Mandatory Fields =====

==== uuid ====

A globally-unique identifier for your extension, made of two parts separated by **@**.

  * Each part must only container letters, numbers, period (.), underscore (_) and hyphen (-).
    * The first part should be a short string like "click-to-focus".
    * The second part must be some namespace under your control, such as username.github.io.
    * Common examples are click-to-focus@username.github.io and adblock@account.gmail.com.

<WRAP info>
**NOTE:**  An extension must be installed to a directory with the same name as **uuid+** to be recognized by GNOME Shell.

<code bash>
~/.local/share/gnome-shell/extensions/example@blah/
</code>

</WRAP>

----

==== name ====

A short, descriptive name for the extension.

----

==== description ====

A relatively short description of the extension.

<WRAP info>
**NOTE:**  Line breaks and tabs can be inserted by using **\n** and **\t** escape sequences.
</WRAP>


----

==== shell-version ====

An array of strings describing the GNOME Shell versions that an extension supports.

<WRAP info>
**NOTE:**  It must include at least one entry or the extension will be uninstallable.

  * For versions up to and including GNOME 3.38, this should have a major and minor component such as "3.38".
  * Starting with GNOME 40, it should simply be the major version, such as "40" or "41".

  * GNOME Shell has a configuration setting, **disable-extension-version-validation**, which controls whether unsupported extensions can be loaded.
    * Before GNOME 40 this was __true__ by default (users could install extensions regardless of the shell-version), but because of the major changes it is now __false__ by default.

</WRAP>

----

==== url ====

A URL for an extension, where the code can be found and issues can be reported.

<WRAP info>
**NOTE:**  It is required for extensions submitted to https://extensions.gnome.org/ to have a valid URL.
</WRAP>

----

==== version ====

The version of the extension.

<WRAP info>
**NOTE:**  As known to the GNOME Extensions website, and MUST be a whole number like 1.

  * It is not a semantic version like 1.1 or a string like "1".

  * This version is automatically incremented by the GNOME Extensions website with each submission.

</WRAP>

----


===== Optional Fields =====

==== gettext-domain ====

A Gettext translation domain, used by the **ExtensionUtils.initTranslations()** convenience method to create a object with methods for marking and retrieving string translations in an extension.


<WRAP info>
**NOTE:**  The domain should be unique to your extension and the easiest choice is to use the UUID from your extension, such as example@blah.

  * See the Translations page.

</WRAP>

----

==== settings-schema ====

A **Gio.SettingsSchema** ID, used by the **ExtensionUtils.getSettings()** convenience method to create a Gio.Settings object for an extension.

<WRAP info>
**NOTE:**  By convention, the schema ID for extensions all start with the string **org.gnome.shell.extensions** with the extension ID as a unique identifier, such as **org.gnome.shell.extensions.example**.

  * See the Preferences page.

</WRAP>

----

==== session-modes ====

An array of strings describing the GNOME Shell session modes that the extension supports.

<WRAP info>
**NOTE:**  Almost all extensions will only use the user session mode, which is the default if this field is not present.
</WRAP>


<WRAP important>
**WARNING:** This field was added in GNOME 42.
</WRAP>


The current possible session modes are:

  * **user**: Extensions that specify this key run during active user sessions.
    * If no other session modes are specified, the extension will be enabled when the session is unlocked and disabled when it locks.
  * **unlock-dialog**:  Extensions that specify this key are allowed to run, or keep running, on the lock screen.
  * **gdm**:  Extensions that specify this key are allowed to run, or keep running, on the login screen.
    * This session mode is only available for system extensions that are enabled for the **gdm** user.

<WRAP info>
**NOTE:**  Extensions that want to support other session modes must provide a justification to be approved during review for distribution from the GNOME Extensions website.
</WRAP>