Google is committed to advancing racial equity for Black communities. See how.

Manifest structure

This page describes the top-level of an Apps Script project's manifest file JSON data structure.

Each component sub-object of the JSON structure is described in a different section. For easier reference, some of the larger substructures of the manifest are defined in separate pages:

Manifest

The top-level of the manifest configuration.

JSON representation
{
  "addOns": {
    object (AddOns)
  },
  "dependencies": {
    object (Dependencies)
  },
  "exceptionLogging": string,
  "executionApi": {
    object (ExecutionApi)
  },
  "oauthScopes": [
    string
  ],
  "runtimeVersion": string,
  "sheets": {
    object (Sheets)
  },
  "timeZone": string,
  "urlFetchWhitelist": [
    string
  ],
  "webapp": {
    object (Webapp)
  }
}
Fields
addOns

object (AddOns)

The resource configuration of the project if deployed as a Google Workspace add-on.

dependencies

object (Dependencies)

The configuration of advanced services and libraries enabled for use by the script project.

exceptionLogging

string

The location where exceptions are logged. The valid settings are the following:

  • NONE indicates exceptions are not logged.
  • STACKDRIVER indicates that exceptions are logged in Stackdriver.
executionApi

object (ExecutionApi)

The script project's API executable configuration. This is only used if the project is deployed for API execution.

oauthScopes[]

string

The definition of authorization scopes used by the script project.

runtimeVersion

string

The runtime version the script is using. If this field is not present in the manifest, the script uses the default runtime (STABLE). Valid options for this field are the following:

  • STABLE indicates the default runtime (currently Rhino).
  • V8 indicates the V8 powered runtime.
  • DEPRECATED_ES5 indicates the Rhino runtime. Setting this value also prevents automatic migration to V8.
sheets

object (Sheets)

The resource configuration that defines Sheets macros.

timeZone

string

The script time zone in one of the available ZoneId values such as "America/Denver".

urlFetchWhitelist[]

string

A list of HTTPS URL prefixes. If present, any URL endpoint fetched must match one of the prefixes in this list. This can help to protect user data. See Whitelisting URLs for more details.

webapp

object (Webapp)

The script project's web app configuration, which is only used if the project is deployed as a web app.

ExecutionApi

The script project's API executable configuration. This is only used if the project is deployed for API execution.

JSON representation
{
  "access": string
}
Fields
access

string

Determines who has permission to run the script from the API. The valid settings are the following:

  • MYSELF indicates only the user who deployed the script can run it.
  • DOMAIN indicates only users in the same domain as the deploying user can run it.
  • ANYONE indicates any user who is logged in.
  • ANYONE_ANONYMOUS indicates any user, even if not logged in.

Webapp

The script project's web app configuration, which is only used if the project is deployed as a web app.

JSON representation
{
  "access": string,
  "executeAs": string
}
Fields
access

string

The levels of permission for running the web app. The valid settings are the following:

  • MYSELF indicates only the user who deployed the app can run it.
  • DOMAIN indicates only users in the same domain as the deploying user can run it.
  • ANYONE indicates any user who is logged in.
  • ANYONE_ANONYMOUS indicates any user, even if not logged in.
executeAs

string

The identity under which the web app executes. The valid settings are the following:

  • USER_ACCESSING indicates the web app runs as the user accessing it.
  • USER_DEPLOYING indicates the web app runs as the user who deployed it.

Whitelisting URLs

Sometimes you may want your script or add-on to open a URL in response to a user action. Other times you may want your script or add-on to retrieve information from an external location using the Apps Script UrlFetch service. In both cases you must whitelist the URLs you open or fetch from in the project manifest.

Whitelisting is the process where you designate specific URLs that are pre-approved for access by your script or add-on. This requirement helps protect user data; if you define a whitelist, script projects can't access URLs that have not been whitelisted. Google Workspace add-ons require URLs to be whitelisted before they can be fetched or opened.

You can whitelist a URL for fetching by adding it or a matching prefix to the urlFetchWhitelist manifest field. For Google Workspace add-on projects, you can whitelist a URL for opening by adding it or a matching prefix to the addOns.common.openLinkUrlPrefixes manifest field.

The prefixes you add to the manifest must satisfy the following requirements:

  • Each prefix must be a valid URL.
  • Each prefix must use https://, not http://.
  • Each prefix must have a full domain.
  • Each prefix must have a non-empty path. For example, https://www.google.com/ is valid but https://www.google.com is not.
  • You can use wildcards to match URL subdomain prefixes.
  • A single * wildcard can be used in the addOns.common.openLinkUrlPrefixes field to match all links, but this is not recommended as it can expose a user's data to risk and can prolong the add-on review process. Only use a wildcard if your add-on functionality requires it.

When determining if a URL matches a whitelisted prefix, the following rules apply:

  • Path matching is case-sensitive.
  • If the prefix is identical to the URL, it is a match.
  • If the URL is the same or a child of the prefix, it is a match.

For example, the prefix https://example.com/foo matches the following URLs:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

Using wildcards

You can use a single wildcard character (*) to match a subdomain for both the urlFetchWhitelist and addOns.common.openLinkUrlPrefixes fields. You can't use more than one wildcard to match multiple subdomains, and the wildcard must represent the leading prefix of the URL.

For example, the prefix https://*.example.com/foo matches the following URLs:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

The prefix https://*.example.com/foo doesn't match the following URLs:

  • https://subdomain.example.com/bar (suffix mismatch)
  • https://example.com/foo (at least one subdomain must be present)

Some of the prefix rules are enforced when you try to save your manifest. For example, the following prefixes cause an error if they are present in your manifest when you attempt to save:

  • https://*.*.example.com/foo (multiple wildcards are forbidden)
  • https://subdomain.*.example.com/foo (wildcards must be used as a leading prefix)