Skip to content

2026

  • 3 min read

Validate Atlassian Forge Manifest in VS Code

The manifest.yml file is the blueprint of any Atlassian Forge app, defining modules, permissions, and app identity. As an app grows, maintaining a valid manifest becomes critical.

Traditionally, developers rely on the @forge/cli tool to check for errors, specifically running commands like forge lint. Under the hood, the CLI uses the @forge/manifest package to validate your file against a strict specification. However, this workflow is reactive: you make a change, switch to the terminal, run a command, and wait for feedback.

A better experience is real-time validation directly inside your editor. This allows you to catch errors as you type and leverages features like autocompletion for complex module definitions.

The Challenge: Connecting VS Code to the Schema

To achieve this in Visual Studio Code, we rely on the Red Hat YAML extension. As the standard for YAML language support in VS Code (powered by the widely adopted yaml-language-server), this extension supports associating JSON schemas with YAML files to provide validation and IntelliSense.

However, there is a small hurdle: while Atlassian publishes the schema within the @forge/manifest npm package, they do not expose a public, stable URL for the schema file itself on their developer documentation.

The Solution: jsDelivr

To bridge this gap, we can use jsDelivr, a public, production-grade CDN that aggregates multiple providers to ensure high availability and performance. It allows us to access files directly from the published @forge/manifest package via a URL. By pointing the YAML extension to this URL, we can inject Atlassian's official validation rules directly into VS Code.

Step-by-Step Guide

1. Install the YAML Extension

First, ensure you have the YAML extension by Red Hat installed. You can find it in the VS Code Marketplace or by searching for "YAML" in the Extensions view.

2. Configure Schema Association

You can associate the remote schema with your manifest.yml file using one of two methods supported by the extension.

This method applies the validation rules globally or per-project without modifying the manifest file itself. It uses the yaml.schemas setting documented in the extension's schema association guide.

  1. Open your settings (.vscode/settings.json for workspace or your user settings.json).
  2. Add the following configuration:
1
2
3
4
5
{
  "yaml.schemas": {
    "https://cdn.jsdelivr.net/npm/@forge/manifest/out/schema/manifest-schema.json": "**/manifest.yml"
  }
}

This configuration tells VS Code to download the schema from jsDelivr and apply it to any file named manifest.yml located in the root or any subdirectory of your workspace (the **/ prefix acts as a recursive wildcard).

Note: Be sure to adjust this pattern to match the actual location of your manifest.yml. Refer to the YAML extension's schema association guide for more examples.

Method 2: In-File Modeline

Alternatively, you can declare the schema inside the file itself. The YAML extension supports a specific comment format called a modeline.

Add this magic comment to the very first line of your manifest.yml:

1
2
3
4
5
# yaml-language-server: $schema=https://cdn.jsdelivr.net/npm/@forge/manifest/out/schema/manifest-schema.json

modules:
  jira:issuePanel:
    ...

This creates a direct link between this specific file and the schema version hosted on the CDN.

Tip: Version Pinning

The URLs used above point to the latest version of the schema. If you need to ensure stability or match a specific version of the CLI, you can pin the version in the jsDelivr URL. For example, to use version 12.0.0:

1
https://cdn.jsdelivr.net/npm/@forge/[email protected]/out/schema/manifest-schema.json

Summary

By connecting the Forge manifest schema to VS Code via jsDelivr, you transform the development experience:

  • Real-time Feedback: You no longer need to rely solely on forge lint. Syntax errors and invalid properties are underlined immediately in red.
  • Autocompletion: VS Code can now suggest valid keys and values (e.g., specific permissions or module types), dramatically reducing the time spent looking up documentation.
  • Documentation on Hover: Explanation for many manifest fields is available right under your cursor (note: not all fields are fully documented in the schema, but coverage is extensive).

This simple one-time setup removes friction from the "write-validate-fix" loop, letting you focus more on building your app features and less on debugging YAML structure.