Skip to content

Plugin manifest field reference

manifest.json is a strict JSON object that Phials validates before importing plugin JavaScript. It accepts only the fields in this page.

Complete field table

Field Type Required Default when omitted Validation and meaning
id string Yes None Permanent community plugin identity. Must match ^[a-z][a-z0-9]*\.[a-z][a-z0-9-]*[a-z0-9]$, must not use phials., and must not conflict with a built-in identity.
name string Yes None Non-empty trimmed display name. Must equal the default-exported PhialsPlugin.name.
version SemVer string Yes None Exact plugin version without a leading v or range. Must equal package metadata, the exported plugin version, normalized release tag, and release assets.
minAppVersion SemVer string Yes None Inclusive oldest supported Phials version. Runtime requires current Phials >= minAppVersion.
pluginApiVersion SemVer string Yes None Public SDK contract targeted by the release. The declared major must match the Host and its version must not exceed the supported version; the current contract is "2.0.0".
author string Yes None Non-empty trimmed person, team, or organization responsible for the release.
description string Yes None Non-empty trimmed sentence describing the user-visible plugin outcome.
authorUrl HTTPS URL string No Absent Absolute https:// website or profile URL for the author.
repository HTTPS URL string No Absent Absolute https:// URL for the public source and release repository. In a community release, use the GitHub repository named by the registry entry.
icons string[] No [] Unique Iconify identifiers in collection:name form. Each value names an icon to preload; URLs and local paths are invalid.
permissions PluginPermission[] No [] Unique names from the permission catalog. Write permissions imply the corresponding read permission, so redundant pairs are invalid.

| thumbnailProviders | { id: string; rendererVersion: string }[] | No | Absent | API 2 optional complete renderer catalog: exact unique IDs and versions of dedicated Thumbnail contributions. |

No field accepts null. Optional fields are either present with the declared type or omitted.

Complete manifest shape

{
"id": "acme.review-tools",
"name": "Review Tools",
"version": "1.3.0",
"minAppVersion": "1.4.0",
"pluginApiVersion": "2.0.0",
"author": "Acme",
"description": "Adds review commands and file annotations.",
"authorUrl": "https://acme.example",
"repository": "https://github.com/acme/review-tools",
"icons": ["phoundry-mono:check", "phoundry-mono:circle-info"],
"permissions": ["filesystem.write"]
}

The order of object fields has no runtime meaning. Keep arrays sorted for stable release diffs.

id

The ID contains one vendor segment, one period, and one plugin segment:

vendor.plugin-name

Valid:

acme.review-tools
papertrail.pdf-review
studio7.contact-sheet

Invalid:

ReviewTools
acme
acme.review_tools
acme.-review
acme.review-
phials.review-tools

The vendor segment begins with a lowercase letter and then contains lowercase letters or digits. The plugin segment begins with a lowercase letter, ends with a lowercase letter or digit, and may contain lowercase letters, digits, or hyphens between them.

The ID owns installation identity, enablement, permission approval, settings, storage, database namespacing, and update continuity. Changing it creates a new plugin rather than renaming an existing one.

Version fields

version, minAppVersion, and pluginApiVersion each contain one exact semantic version:

MAJOR.MINOR.PATCH
MAJOR.MINOR.PATCH-prerelease
MAJOR.MINOR.PATCH+build
MAJOR.MINOR.PATCH-prerelease+build

Examples: 1.4.0, 2.0.0-beta.3, and 2.0.0-beta.3+build.17.

Invalid values include v1.4.0, 1.4, ^1.4.0, >=1.4.0, and latest. SemVer precedence, including prerelease ordering and ignored build metadata, is defined in Version and compatibility reference.

Runtime compatibility is the conjunction:

current Phials version >= minAppVersion
and
major(supported Plugin API version) = major(pluginApiVersion)
and
pluginApiVersion <= supported Plugin API version

version orders plugin releases; it is not part of this compatibility comparison.

Public metadata and URLs

name, author, and description reject empty or whitespace-only strings. They are public metadata, not release notes.

authorUrl and repository must be absolute HTTPS URLs. The registry’s repo field has a different shape: it uses owner/repo, while the manifest uses a complete URL.

URL fragments, query strings, credentials, file: URLs, local paths, email addresses, and bare owner/repo values are invalid manifest links.

Icons

Every icons value must be a complete Iconify identifier:

collection:name

Values are case-sensitive identifiers and must be unique. The source manifest is the only community-plugin icon preload declaration; the exported PhialsPlugin does not repeat it. The list preloads known icons and does not download arbitrary assets.

An empty array and an omitted field have the same runtime meaning.

Permissions

Every permissions value must be one of:

filesystem.read
filesystem.write
clipboard.read
clipboard.write
network.fetch
workspace-folders.read
workspace-folders.write

Values must be unique. filesystem.write satisfies supported read and write file operations, so a manifest containing both filesystem permissions is invalid as redundant.

workspace-folders.write likewise implies workspace-folders.read; declaring both Workspace Folder permissions is invalid.

An empty array and an omitted field mean the plugin requests no gated Plugin API operations. Any change to the complete permission set can require permission review.

Unknown fields

The manifest rejects every field not listed above. Common invalid fields include:

providers
settings
database
themes
releaseNotes
homepage
downloadUrl
schemaVersion

Capabilities, settings, database tables, and lifecycle hooks belong to the default-exported PhialsPlugin. Registry discovery metadata belongs to the community registry entry.

Cross-file relationships

Schema validation checks the manifest in isolation. Release validation also enforces these relationships:

Relationship Required result
src/plugin.manifest.ts and package.json Equal version
Generated manifest.json and default-exported PhialsPlugin Equal generated id, name, and version
Source and release manifest Release manifest is an exact data-only projection
Install directory and manifest Directory name equals id
Community registry and manifest Registry id equals manifest id; registry repo identifies the repository URL
Git tag and manifest Tag normalized by removing one leading v equals version
GitHub release and checksummed candidate Attached and installed bytes match the verified artifact inventory and checksum
Manifest permissions and runtime operations Every gated operation is declared; no unused permission is requested
Compatibility fields and SDK use Bounds include every public contract and Phials behavior required by the release

For the authoring workflow, see Configure the plugin manifest.

Thumbnail renderer catalog

A release may declare thumbnailProviders: [{ id, rendererVersion }] matching every shipped dedicated Thumbnail provider. The Host validates the declared catalog against the loaded contributions. IDs and renderer versions must be nonblank strings of at most 256 characters; the list is bounded at 128 unique IDs. Change rendererVersion when encoded behavior changes.

Automatic caching works without a catalog. A successfully validated catalog additionally lets the Host prove that an older renderer is obsolete for proactive cleanup; absent or unavailable authority is retained conservatively. Cache destinations and publication paths are never manifest fields.

This article includes AI-assisted content.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.