Your extension's specification file (`extension.yaml`) contains your extension's
metadata, declares the resources created by the extension and the APIs and
access required by the extension, and defines any user-configured parameters
provided by the extension.

The tables on this page describe the fields available for an `extension.yaml`
file.

## Basic and identifying information

```yaml
name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
```
**Basic fields** `name`  
string  
*(required)* Identifier for the extension.

Can only contain lowercase letters, numbers, and dashes; 40 character
limit.

**Note:** This value is used to generate the extension's
instance ID (which is then used to generate the names of the
extension's service account and the extension-specific resources).
`version`  
string  
*(required)* Version of the extension.

Must follow semver versioning (for example, 1.2.0).
`specVersion`  
string  
*(required)* Version of the Firebase Extensions specification.

Current value: `v1beta`
`license`  
string  
*(optional)* License for the extension.

Your extension must be licensed using `Apache-2.0`.
`billingRequired`  
boolean  
*(optional)* Whether the services used by the extension require a paid-tier
Firebase billing account.

Always set to `true`.
`displayName`  
string  
*(optional)* Friendly display name for the extension (3-5 words).

40 character limit.
`description`  
string  
*(optional)* Brief description of the task your extension performs (\~1 sentence). `icon`  
string  
*(optional)* File to use as your extension's icon on
[`extensions.dev`](https://extensions.dev/) and
the Firebase console.

This file must be a square PNG between 512x512 and 1024x1024 pixels.
Put the file in the same directory as `extension.yaml`; you
cannot specify a subdirectory.

Keep the following guidelines in mind when designing an icon for your
extension:

- Select background and artwork colors that are appropriate for your brand.
- Keep your icon colors simple, using only 2 colors. Multiple colors can make your icon visually overwhelming.
- For the same reason, don't use gradients in your icon. Gradients are hard to discern at small sizes and make the icon visually complex.
- Use simple, unique imagery that communicates your extension's functionality.
- If your company builds multiple extensions, don't use your logo as the icon. Users will have difficulty distinguishing between your extensions.
- Make the artwork graphic and bold. Don't use delicate or elaborate art, which will not render well at smaller sizes.
- Don't include words that explain what your extension does. Text is often illegible at smaller sizes.
`tags`  
list of strings  
*(optional)* Tags to help users discover your extension. The following tags map to categories on Extensions Hub: `marketing`, `messaging`, `payments`, `search`, `shipping`, `social`, `utilities`, `ai` `sourceUrl`  
string  
*(optional)* Public URL where the extension directory can be accessed. `releaseNotesUrl`  
string  
*(optional)* Public URL where the release notes for the extension can be accessed. `author`  
one author object  
*(optional)* Primary author and point of contact for the extension.

```yaml
author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
```
**Author fields** `authorName`  
string  
*(required)* Name of the author.

Can be a person, company, organization, etc.
`email`  
string  
*(optional)* Email address of the author. `url`  
string  
*(optional)* Public URL where information about the author can be accessed. `contributors`  
list of author objects  
*(optional)* Any additional contributing authors for the extension.

```yaml
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
```
**Author fields** `authorName`  
string  
*(required)* Name of the author.

Can be a person, company, organization, etc.
`email`  
string  
*(optional)* Email address of the author. `url`  
string  
*(optional)* Public URL where information about the author can be accessed.

## Firebase and Google Cloud APIs

These fields specify the Firebase and Google APIs the extension uses. When users
install the extension, they can elect to automatically enable these APIs in
their project.

```yaml
apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
```

| **API fields** ||
|---|---|
| `apiName` string *(required)* | Name of the Google API Must correspond to the *Service name* field as listed on each API's overview page ([example](https://console.cloud.google.com/apis/api/bigquery.googleapis.com/overview)) in the [Google Cloud API Library](https://console.cloud.google.com/apis/library) |
| `reason` string *(required)* | Brief description of why the extension needs to use this API |

## IAM roles

These fields specify the Cloud IAM roles the extension requires. The service
account provisioned for the extension is granted these roles.

You can only specify one of the
[supported roles](https://firebase.google.com/docs/extensions/publishers/access.md.txt#supported-roles).

```yaml
roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
```

| **Role fields** ||
|---|---|
| `role` string *(required)* | Name of the IAM role needed for the extension to operate Must be one of the [supported roles](https://firebase.google.com/docs/extensions/publishers/access.md.txt#supported-roles) |
| `reason` string *(required)* | Brief description of why the extension needs the access granted by this role |
| `resource` string *(optional)* | Limit the scope of the role to this resource. If omitted, defaults to `projects/${project_id}`. See [Reduce the scope of roles](https://firebase.google.com/docs/extensions/publishers/access.md.txt#role-resource). |

## External services

These fields specify the non-Firebase and non-Google services the extension uses
(typically REST APIs). The Firebase Extensions platform does not provide any
means of automatically enabling or performing authorization for these services.

```yaml
externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
```

| **External services fields** ||
|---|---|
| `name` string *(required)* | Name of the external service needed for the extension to operate |
| `pricingUri` string *(required)* | URI to pricing information for the service |

## User-configurable parameters

These fields define the parameters that the extension makes available for users
to configure.

```yaml
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
```

| **Parameter fields** ||
|---|---|
| `param` string *(required)* | Name of the parameter. You use this name to reference the parameter value in code. |
| `label` string *(required)* | Short description for the parameter. Displayed to the user when they're prompted for the parameter's value. |
| `description` string *(optional)* | Detailed description for the parameter. Displayed to the user when they're prompted for the parameter's value. Supports Markdown. |
| `example` string *(optional)* | Example value for the parameter. |
| `default` string *(optional)* | Default value for the parameter if the user leaves the parameter's value blank. |
| `validationRegex` string *(optional)* | Regular expression for validation of the parameter's user-configured value. [Google RE2 syntax](https://github.com/google/re2/wiki/Syntax). |
| `validationErrorMessage` string *(optional)* | Error message to display if regex validation fails. |
| `required` boolean *(optional)* | Defines whether the user can submit an empty string when they're prompted for the parameter's value. Defaults to `true`. |
| `immutable` boolean *(optional)* | Defines whether the user can change the parameter's value after installation (such as if they reconfigure the extension). Defaults to `false`. **Note:** If you define a "location" parameter for the deployed functions of your extension, set this field to `true`. |
| `type` string *(optional)* | The parameter type. Special parameter types might have additional requirements or different UI presentation. See the following sections. |

### Selectable and multi-selectable parameters

Selectable and multi-selectable parameters prompt users to choose from a list of
predefined options.

```yaml
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiSelect
    options:
      - value: red
      - value: green
      - value: blue
```
**Multiple-choice parameter fields** `type`  
string `select` or `multiSelect`

Specifies that the parameter can be one value (`select`)
or several values (`multiSelect`) selected from a set of
predefined choices
`options`  
list of options  
*(required)* The options from which the user can choose
**Option fields** `value`  
string  
*(required)* One of the values the user can choose. This is the value you get when you read the parameter value in code. `label`  
string  
*(optional)* Short description of the selectable option. If omitted, defaults to `value`.

### Selectable resource parameters

Selectable resource parameters prompt users to select a resource (database
instance, storage bucket, etc.) from their project.

```yaml
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
```

| **Resource parameter fields** ||
|---|---|
| `type` string | `selectresource` Specifies that the parameter represents a project resource |
| `resourceType` string *(required)* | The type of resource to prompt the user to select. Valid values: - `storage.googleapis.com/Bucket` - `firestore.googleapis.com/Database` - `firebasedatabase.googleapis.com/DatabaseInstance` However, only Cloud Storage buckets currently have a selection UI (other resource types are presented as free-form text input fields). |

### Secret parameters

User-provided secret values (such as API keys) are handled differently:

- Secret values are stored using Cloud Secret Manager. Only authorized clients (such as an installed instance of an extension) can access these values.
- When users are prompted to provide these values, their input is not displayed.

```yaml
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
```

| **Secret parameter fields** ||
|---|---|
| `type` string | `secret` Specifies that the parameter is a secret value |

## Cloud Function resources

These fields declare the Cloud Functions included in an extension. The resource
declaration syntax looks a little different between 1st-gen and 2nd-gen
functions, which can coexist in an extension.

### 1st-gen Cloud Functions

```yaml
resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
```
**Resource fields** `name`  
string  
*(required)* User-friendly name for the exported function.

If you don't specify the `entryPoint` property (see
below), this value must match the name of the function in your
functions source code.

The final name of the *deployed* function will be in the
following format:
`ext-extension-instance-id-name`.
`type`  
string  
*(required)* For a 1st-gen function resource: `firebaseextensions.v1beta.function` `description`  
string  
*(required)* Brief description of what task the function performs for the
extension.
`properties`  
*(required)* 1st-gen Cloud Functions properties. The most important properties
are listed below, but you can find the complete list in the
[Cloud
Functions reference](https://cloud.google.com/functions/docs/reference/rest/v1/projects.locations.functions).
**Properties** `location`  
*(optional)* Location to which to deploy the function. Defaults to
`us-central1`
`entryPoint`  
*(optional)* Name of the exported function within your functions source code that the extension should look for. Defaults to the value of `name`, above. `sourceDirectory`  
*(optional)* Directory that contains your `package.json` at its
root. The file for your functions source code must be in this
directory. Defaults to `functions`

**Note:** The `main` field of
`package.json` specifies the file for your
functions source code (like `index.js`).
`timeout`  
*(optional)*   
The function's maximum execution time.

- Default: `60s`
- Max value: `540s`
`availableMemoryMb`  
*(optional)* Amount of memory in MB available for the function.

- Default: `256`
- Valid values: `128`, `256`, `512`, `1024`, and `2048`
`runtime`  
*(recommended)* Runtime environment for the function.

- Defaults to the most recent of the [Node.js
  versions currently supported by Cloud Functions](https://firebase.google.com/docs/functions/manage-functions#set_nodejs_version).
- Valid values: `nodejs14`, `nodejs16`, `nodejs18`
`httpsTrigger`  
or  
`eventTrigger`  
or  
`scheduleTrigger`  
or  
`taskQueueTrigger`  
*(one of these function trigger types is required)* See [Write
Cloud Functions for an extension](https://firebase.google.com/docs/extensions/publishers/functions) for specific information about each trigger type.

### 2nd-gen Cloud Functions

```yaml
resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue

```
**Resource fields** `name`  
string  
*(required)* User-friendly name for the exported function.

If you don't specify the `entryPoint` property (see
below), this value must match the name of the function in your
functions source code.

The final name of the *deployed* function will be in the
following format:
`ext-extension-instance-id-name`.
`type`  
string  
*(required)* For a 2nd-gen function resource: `firebaseextensions.v1beta.v2function` `description`  
string  
*(required)* Brief description of what task the function performs for the
extension.
`properties`  
*(required)* 2nd-gen Cloud Functions properties. The most important properties
are listed below, but you can find the complete list in the
[Cloud
Functions reference](https://cloud.google.com/functions/docs/reference/rest/v2/projects.locations.functions).
**Properties** `location`  
*(optional)* Location to which to deploy the function. Defaults to
`us-central1`
`sourceDirectory`  
*(optional)* Directory that contains your `package.json` at its
root. The file for your functions source code must be in this
directory. Defaults to `functions`

**Note:** The `main` field of
`package.json` specifies the file for your
functions source code (like `index.js`).


There are also three object-type fields with their own properties:
**buildConfig properties** `buildConfig.runtime`  
*(recommended)* Runtime environment for the function.

- Defaults to the most recent of the [Node.js
  versions currently supported by Cloud Functions](https://firebase.google.com/docs/functions/manage-functions#set_nodejs_version).
- Valid values: `nodejs14`, `nodejs16`, `nodejs18`
`buildConfig.entryPoint`  
*(optional)* Name of the exported function within your functions source code that the extension should look for. Defaults to the value of `name`, above. **serviceConfig properties** `serviceConfig.timeoutSeconds`  
*(optional)* The function's maximum execution time.

- Default: `60`
- Max value: `540`
`serviceConfig.availableMemory`  
*(optional)* The amount of memory available for a function. Defaults to `256M`. Supported units are `k`, `M`, `G`, `Mi`, `Gi`. If no unit is supplied, the value is interpreted as bytes. **eventTrigger properties** `eventTrigger.eventType`  
*(required)* The type of event to listen for. See [Write Cloud
Functions for an extension](https://firebase.google.com/docs/extensions/publishers/functions) for the event types available for each product. `eventTrigger.eventFilters`  
*(optional)* Filters that further limit the events to listen to. For example, you could only listen to events matching a specific resource pattern. See [Write Cloud
Functions for an extension](https://firebase.google.com/docs/extensions/publishers/functions) for information on filtering each type of event. `eventTrigger.channel`  
*(optional)* The name of the channel associated with the trigger in `projects/{project}/locations/{location}/channels/{channel}` format. If you omit this property, the function will listen for events on the project's default channel. `eventTrigger.triggerRegion`  
*(optional)* The trigger will only receive events originating in this region. It can be the same region as the function, a different region or multi-region, or the global region. If not provided, defaults to the same region as the function.

## Lifecycle events

Lifecycle events let you specify functions that will run when a user installs,
updates, or configure an instance of your extension.
See [Handle your extension's lifecycle events](https://firebase.google.com/docs/extensions/publishers/lifecycle-events.md.txt).

```yaml
lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
```
**Lifecycle event fields** `onInstall`  
*(optional)* Specifies a function that runs when a user installs the
extension.
**Function specification** `function`  
string  
*(required)* Name of the task queue-triggered function that will handle
the event.

This function must be declared in the `resources`
section and have taskQueue defined.
`processingMessage`  
string  
*(required)* Message to display in the Firebase console while the task is in progress. `onUpdate`  
*(optional)* Specifies a function that runs when a user updates the
extension.
**Function specification** `function`  
string  
*(required)* Name of the task queue-triggered function that will handle
the event.

This function must be declared in the `resources`
section and have taskQueue defined.
`processingMessage`  
string  
*(required)* Message to display in the Firebase console while the task is in progress. `onConfigure`  
*(optional)* Specifies a function that runs when a user re-configures the
extension.
**Function specification** `function`  
string  
*(required)* Name of the task queue-triggered function that will handle
the event.

This function must be declared in the `resources`
section and have taskQueue defined.
`processingMessage`  
string  
*(required)* Message to display in the Firebase console while the task is in progress.

## Custom events (Eventarc)

Custom events are events that your extension emits to allow users to insert
their own logic into your extension. See the Eventarc section in
[Add user hooks to an extension](https://firebase.google.com/docs/extensions/publishers/user-hooks.md.txt#eventarc).

```yaml
events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
```

| **Custom event fields** ||
|---|---|
| `type` string *(required)* | The type identifier of the event. Construct the identifier out of 3-4 dot-delimited fields: the publisher ID, extension name, and event name fields are required; the version field is recommended. Choose a unique and descriptive event name for each event type you publish. |
| `description` string *(required)* | Description of the event. |