# PI-Desktop Plugin Manifest Structure: Complete JSON Schema and Validation Guide

> Understand the PI-Desktop plugin manifest structure with our complete JSON schema and validation guide. Learn how to define your plugin's metadata, UI, and security policies.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: api-reference
- Published: 2026-09-11

---

**PI-Desktop uses a rigorously versioned JSON schema—formalized in [`docs/spec/07-plugins/02-plugin-manifest-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/02-plugin-manifest-schema.md) and enforced at load time by the `validateManifest` function in [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts)—to strictly define every plugin's metadata, UI assets, contributions, and security policies.**

The **plugin manifest structure** in PI-Desktop serves as the single source of truth for the host application to discover, validate, and execute third-party extensions. Defined primarily through TypeScript interfaces in [`packages/plugin-sdk/src/types.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/types.ts) and validated against a frozen specification, the manifest ensures that plugins declare their capabilities explicitly before execution. This declarative approach enables static analysis, secure sandboxing, and predictable lifecycle management across the PI-Desktop ecosystem.

## Mandatory Root Fields

Every PI-Desktop plugin manifest must begin with four required fields that establish identity and compatibility.

- **`schemaVersion`**: Must be the integer `1`. This ensures the host interprets the manifest using the correct validation rules.
- **`id`**: A unique reverse-domain identifier matching the pattern `^[a-z0-9]+(\.[a-z0-9_-]+)+$` (e.g., `demo.hello` or `com.example.plugin`).
- **`name`**: Human-readable plugin name displayed in the UI.
- **`version`**: Semantic version string (e.g., `1.2.3`) used for dependency resolution and update checks.

The TypeScript type `PluginManifestV1` in [`packages/plugin-sdk/src/types.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/types.ts) defines these root properties, ensuring compile-time safety for developers and runtime validation for the host.

## Optional Configuration Sections

Beyond the mandatory metadata, the plugin manifest structure supports extensive optional blocks that define UI behavior, feature contributions, and resource access.

### UI Configuration (`PluginUiConfig`)

The **`ui`** object declares panel dimensions and entry points:
- **`panel`**: Relative path to the HTML renderer entry (e.g., [`renderer/index.html`](https://github.com/vastsa/PI-Desktop/blob/main/renderer/index.html)).
- **`width`** and **`height`**: Default panel dimensions in pixels.
- **`title`**: Localized string map (e.g., `{ "en": "Sample", "zh-CN": "示例" }`).

### Contribution Points (`PluginContributes`)

The **`contributes`** field uses the `PluginContributes` type to register extensions:
- **`commands`**: Palette commands with `id` and `title`.
- **`views`**: Sidebar or panel views with `icon`, `entry`, and `order`.
- **`agentTools`**, **`skills`**, **`services`**, **`themes`**, **`mcpServers`**, **`busTopics`**, **`settings`**, and **`sessionSources`**: Specialized integration points for the PI-Desktop agent system and event bus.

### Security Policies

PI-Desktop implements a capability-based security model where permissions must be explicitly declared:

- **`permissions`**: Array of `PluginPermission` enum values (e.g., `ui.panel`, `fs.read`, `net.fetch`).
- **`fs`**: File-system policy using `PluginFsPolicy`/`PluginFsRule` to define `read`, `write`, and `delete` scopes relative to `workspace` or `global` roots. Rules must use relative globs; the `own` modifier is restricted to `delete` operations.
- **`net`**: Network egress policy listing allowed domains under **`domains`**. Entries must be bare hostnames with optional `*.` wildcards (e.g., `api.example.com`, `*.cdn.org`).

## Manifest Validation Pipeline

At load time, PI-Desktop invokes **`validateManifest`** (located at line 803 in [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts)) to enforce schema compliance. According to the source code, this routine performs the following checks:

1. **Schema Version Verification**: Confirms `schemaVersion` equals `1`.
2. **Identity Validation**: Ensures `id` conforms to the reverse-domain regex and `version` follows semantic versioning.
3. **Path Sanitization**: Rejects absolute paths or paths containing `..` sequences in any file reference.
4. **Permission Consistency**: Validates that declared contributions have matching permissions (e.g., a `views` contribution requires `ui.view` permission).
5. **Policy Syntax**: Verifies `fs` rules contain only relative globs and `net.domains` entries lack protocol prefixes or path components.

If validation fails, the manifest is rejected and the plugin is not loaded, preventing insecure or malformed code from executing in the PI-Desktop environment.

## Complete Manifest Examples

### Minimal Valid Manifest

The simplest valid PI-Desktop plugin defines only the required fields and a single command contribution:

```json
{
  "schemaVersion": 1,
  "id": "demo.hello",
  "name": "Hello",
  "version": "0.1.0",
  "main": "main.js",
  "ui": { "panel": "renderer/index.html" },
  "contributes": {
    "commands": [
      { "id": "hello.open", "title": "Open Hello Panel" }
    ]
  },
  "permissions": ["ui.panel"]
}

```

### Manifest with Localization and Views

This example demonstrates localized UI strings and a view contribution:

```json
{
  "schemaVersion": 1,
  "id": "demo.sample",
  "name": "Sample Plugin",
  "version": "1.2.3",
  "main": "main.js",
  "ui": {
    "panel": "renderer/panel.html",
    "width": 400,
    "height": 300,
    "title": { "en": "Sample", "zh-CN": "示例" }
  },
  "contributes": {
    "views": [
      {
        "id": "sampleView",
        "title": { "en": "Sample View", "zh-CN": "示例视图" },
        "icon": "sparkles",
        "entry": "views/sample.html",
        "order": 5
      }
    ]
  },
  "permissions": ["ui.panel", "ui.view"]
}

```

### Manifest with Security Policies

This advanced example configures restricted file-system and network access:

```json
{
  "schemaVersion": 1,
  "id": "demo.security",
  "name": "Secure Plugin",
  "version": "0.0.1",
  "main": "main.js",
  "permissions": ["fs.read", "net.fetch"],
  "fs": {
    "read": { "root": "workspace", "scope": ["docs/**", "*.md"] }
  },
  "net": {
    "domains": ["api.example.com", "*.example.org"]
  }
}

```

## Reference Implementation Files

The PI-Desktop repository contains several critical files that define and implement the plugin manifest structure:

- **[`docs/spec/07-plugins/02-plugin-manifest-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/02-plugin-manifest-schema.md)**: The authoritative specification document describing the JSON schema, TypeScript types, and validation rules.
- **[`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts)**: Contains the `validateManifest` function (line 803) used for runtime schema enforcement.
- **[`packages/plugin-sdk/src/types.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/types.ts)**: Central TypeScript definitions for `PluginManifest`, `PluginPermission`, `PluginFsPolicy`, and related interfaces.
- **[`examples/plugins/hello/manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/examples/plugins/hello/manifest.json)**: Real-world example demonstrating UI configuration, commands, agent tools, skills, themes, and permissions.
- **[`packages/plugin-devkit/src/templates.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-devkit/src/templates.ts)**: Devkit helper that generates valid [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) files when scaffolding new plugins.

## Summary

- PI-Desktop's **plugin manifest structure** requires a `schemaVersion` of `1` along with mandatory fields `id`, `name`, and `version` formatted according to strict patterns defined in [`packages/plugin-sdk/src/types.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/types.ts).
- The **`validateManifest`** function at line 803 of [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts) enforces schema compliance, path sanitization, and permission consistency at load time.
- Optional sections include **`ui`** for panel configuration, **`contributes`** for feature registration (commands, views, agent tools), and security policies for **`fs`** and **`net`** access.
- All file paths must be relative; absolute paths and `..` traversal sequences are explicitly rejected during validation.
- The complete specification is documented in [`docs/spec/07-plugins/02-plugin-manifest-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/02-plugin-manifest-schema.md).

## Frequently Asked Questions

### What is the minimum required schema for a PI-Desktop plugin manifest?

Every manifest must include `schemaVersion` (set to `1`), a unique `id` matching the reverse-domain pattern `^[a-z0-9]+(\.[a-z0-9_-]+)+$`, a `name`, and a `version`. As implemented in [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts), the `validateManifest` function rejects any manifest missing these fields or using an unsupported schema version.

### How does PI-Desktop validate plugin permissions against contributions?

The validation routine checks that every contribution type declared in the `contributes` object has a corresponding entry in the `permissions` array. For example, if you declare a `views` contribution, the manifest must include the `ui.view` permission. This enforcement occurs in [`packages/plugin-sdk/src/index.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-sdk/src/index.ts) to ensure plugins cannot access host capabilities without explicit authorization.

### Can a PI-Desktop plugin access the file system or network by default?

No. Access to `fs.*` and `net.fetch` capabilities is deny-by-default. Developers must explicitly request these permissions and define restrictive policies: `fs` rules must specify relative glob patterns under a `workspace` or `global` root, while `net.domains` must list specific bare hostnames. Absolute paths and protocol-prefixed URLs are rejected during validation.

### Where is the plugin manifest schema formally documented?

The canonical specification resides in [`docs/spec/07-plugins/02-plugin-manifest-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/07-plugins/02-plugin-manifest-schema.md) within the PI-Desktop repository. This document defines the JSON structure, TypeScript interfaces, and validation rules. Developers can also reference [`examples/plugins/hello/manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/examples/plugins/hello/manifest.json) for a comprehensive real-world implementation and use [`packages/plugin-devkit/src/templates.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/plugin-devkit/src/templates.ts) to generate compliant manifests during plugin scaffolding.