# App Manifest

Each app package must include a `manifest.json` file at the root of the package directory. The manifest file provides general information about the app, such as the name, description, and the list of modules contained in the app.

## Sample Manifest

Here is sample manifest for an app:

```JSON
{
  "$schema": "https://json.schemastore.org/youtrack-app.json",
  "name" : "sample-app",
  "title" : "Sample App",
  "description" : "App description",
  "version": "1.0.0",
  "url": "https://github.com/example/youtrack-app",
  "icon": "icon.svg",
  "iconDark": "icon.svg",
  "minYouTrackVersion": "2022.2.0",
  "maxYouTrackVersion": "2024.2.0",
  "changeNotes": "Version 0.0.1: Feature 1",
  "vendor": {
    "name": "JetBrains",
    "url": "jetbrains.com",
    "email": "support@jetbrains.com"
  },
  "widgets": [
    {
      "key": "fields-first",
      "name": "Sample Widget",
      "description": "Optional description for the issue view widget",
      "guard": "({entity}) => entity.fields.State?.value === 'Open'",
      "extensionPoint": "ISSUE_FIELD_PANEL_FIRST",
      "indexPath": "index.html",
      "iconPath": "icon.png",
      "settingsSchemaPath": "sample-widget-settings.json",
      "permissions": ["READ_USER"],
      "defaultDimensions": {
        "height": "40px",
        "width": "80%"
      },
      "expectedDimensions": {
        "height": "200",
        "width": "1000"
      }
    }
  ]
}
```

## Manifest Schema

The schema used to validate the manifest for a YouTrack app is hosted in the [SchemaStore](https://json.schemastore.org/youtrack-app.json). Its web address is included in the sample manifest provided on this page.

Editors that support JSON schemas will provide auto-completion and contextual help based on the schema, so be sure to load the schema in your development environment.

A `manifest.json` has the following fields:

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `$schema` | String | The web address of the schema used to validate the manifest for a YouTrack app. This schema is hosted in the SchemaStore at https://json.schemastore.org/youtrack-app.json     Editors that support JSON schemas will provide auto-completion and contextual help based on the schema. This can speed up the process of creating and editing the manifest, so be sure to include this reference in your file.   |
| `name` | String | The name of the app. This is used as a unique identifier in YouTrack. If you upload two apps with the same name to your YouTrack site, the existing version of the app with the same name is overwritten. It is also used as a unique id of the app in the JetBrains Marketplace.     This field can only contain lowercase alphanumeric characters, hyphens, underscores, and tildes.   | ✓ |
| `title` | String | The title of the app. This is a user-friendly name that is shown in the JetBrains Marketplace and the YouTrack UI.     This field is optional. When empty, the name of the app is shown in its place.   |   |
| `description` | String | The description of the app. You can see this description in the app details on the Apps administration page. This is also used as the description of the app in the JetBrains Marketplace. |   |
| `version` | String | The version number assigned to the app package in `major.minor.bugfix` format. The default value is `0.0.0`. |   |
| `url` | String | The website for the app. For example, a GitHub page or landing page for your company or product.     This value is shown as the Plugin Site in the JetBrains Marketplace.   |   |
| `icon` | String | The name of the file with the app icon. Store this file at the root level of the app package. |   |
| `iconDark` | String | The name of the file with the app icon for the dark theme. Store this file at the root level of the app package. If you don't include a separate icon for the dark theme, YouTrack will use the `icon` image for both dark and light themes. |   |
| `minYouTrackVersion` | String | The minimum YouTrack version with which the app is compatible. If you attempt to upload or install an app in a YouTrack installation that runs a version lower than the value specified in the manifest, the operation fails.     The JetBrains Marketplace uses this value to help users find apps that are compatible with their YouTrack Server installations.     This field is backward-compatible with the `workflow-scripting-api` from the dependencies field in older versions of the manifest schema.   |   |
| `maxYouTrackVersion` | String | The maximum YouTrack version with which the app is compatible. If you attempt to upload or install an app in a YouTrack installation that runs a version higher than the value specified in the manifest, the operation fails.   |   |
| `changeNotes` | String | A description of changes available in a specific version of the app. This information is only displayed in the JetBrains Marketplace.     Change notes can also be added and updated directly in the marketplace.   |   |
| `vendor` | [Vendor](#app-manifest-vendor) | An object that contains the description of the app vendor.     This information is only used for apps that have been uploaded to your YouTrack site directly. Apps that are installed from the JetBrains Marketplace take the name, URL, and email from the vendor profile in the marketplace.   |   |
| `aiToolPrefix` | String | The prefix for a custom MCP tool name.     This value is only needed when the app package contains a script for a [custom MCP tool](custom-ai-tools.html). For details, see [Tool Prefix](custom-ai-tools.html#custom-ai-tool-prefix).   |   |
| `widgets` | Array<[Widget](#app-manifest-widgets)> | An array of widget objects included in the app. Each widget represents a frontend extension. |   |

### Widgets

Each widget object represents a particular frontend extension. Each widget is a custom inline frame (iFrame) object you embed into the native YouTrack UI.

A widget has the following fields:

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `key` | String | The unique identifier of the widget.     This is a mandatory field that must be unique within the app.     This field can only contain lowercase alphanumeric characters, hyphens, underscores, periods, and tildes.   | ✓ |
| `name` | String | The user-friendly name of the widget shown in the app settings in YouTrack. Widget names must be unique within one app. |   |
| `description` | String | The description of the widget.     Required for widgets embedded in the `HELPDESK_CHANNEL` extension point.     Optional for other extension points.    |   |
| `guard` | String |    A condition for the widget to be shown.     Use a JavaScript function that returns `true` or `false` to define the condition.     The guard function always receives the current user as `me`. For entity-related extension points, the function also receives the current YouTrack entity as `entity`. For more details and examples, see [Conditional Widgets](apps-widget-guards.html).    |   |
| `extensionPoint` | String |    The location in the YouTrack UI where the widget will be embedded.     For the full list of available extension points, see [Extension Points for Widgets](apps-reference-extension-points.html).    | ✓ |
| `showHeader` | Boolean |    Defines whether YouTrack shows the default page header above the widget.     This field is supported for widgets embedded in the `ADMINISTRATION_MENU_ITEM` and `MAIN_MENU_ITEM` extension points. Set it to `false` to hide the page header. When this field is omitted, the page header is shown.     When hiding the page header, make sure the widget provides its own header or breadcrumbs where appropriate.    |   |
| `indexPath` | String | The path to the index.html file that defines the content and structure of the widget. The path is relative to the widgets folder inside the app package.     Store the source code in an HTML file named `index.html`. Place this file directly in the `widgets` folder or in a dedicated subfolder.   | ✓ |
| `iconPath` | String | The relative path to the file with the icon for the widget inside the app package.       * Required for widgets embedded in the `HELPDESK_CHANNEL` extension point.    * Optional for widgets embedded in the `ARTICLE_OPTIONS_MENU_ITEM` and `ISSUE_OPTIONS_MENU_ITEM` extension points.    |   |
| `settingsSchemaPath` | String | The path to the JSON file that stores the settings scheme for Markdown widgets. It should be the path to a file somewhere inside the folder that stores the code for this particular widget.   |   |
| `permissions` | Array<String> |    The set of permissions required to view and use the widget. Depending on the app scope, these permissions can be required at the global or project level.     For widget extension points with project scopes, project-category permissions are checked on a per-project basis. For example, if you require the project-category `LINK_ISSUE` permission to view a widget that uses the project-scoped `ISSUE_BELOW_SUMMARY` extension point, users will only see this widget when working with projects where they have been granted the `LINK_ISSUE` permission.     To refer to a permission, use its unique identifier.     |   |
| `expectedDimensions` | Object |    The expected dimensions of the widget in pixels. YouTrack will try to display the widget according to these dimensions if the monitor settings allow.     Supported attributes are `width` (integer) and `height` (integer).     This field is supported by all extension points except `MARKDOWN` and `DASHBOARD_WIDGET`. If a value is provided for a widget that uses either of these two extension points, it is rejected by YouTrack.    |   |
| `defaultDimensions` | Object |    The default width and height of the widget.     Supported attributes are `width` (integer) and `height` (integer).     This field is only supported by widgets that use the `MARKDOWN` and `DASHBOARD_WIDGET` extension points. If a value is provided for a widget that uses any other extension point, it is rejected by YouTrack.       * For a `MARKDOWN` widget, you can specify the dimensions in pixels or as a percentage. For example, `"width": "100px"` or `"height": "40%"`.    * Dimensions for a `DASHBOARD_WIDGET` are specified in fractional units. A fraction is equivalent to one cell in the dashboard grid. For example, `"width": "8fr"`)    |   |

### Vendor

This object stores basic information about the vendor of the app.

A vendor object has the following fields:

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `name` | String | The name of the vendor. | ✓ |
| `url` | String | The URL of the vendor website. |   |