Skip to content

Manifest Format

The plugin manifest (formae-plugin.pkl) declares your plugin's identity, version, and requirements. The formae agent reads this file when discovering and loading plugins.

Location

The manifest must be named formae-plugin.pkl and placed in the root of your plugin directory:

my-plugin/
├── formae-plugin.pkl    # Manifest (required)
├── main.go
├── plugin.go
└── schema/pkl/

Format

The manifest is a PKL file with the following structure:

// Plugin identifier (required)
name = "mycloud"

// Semantic version (required)
version = "1.0.0"

// Resource type namespace (required)
namespace = "MYCLOUD"

// Human-readable description (required)
description = "MyCloud provider plugin for Formae"

// SPDX license identifier (required)
license = "Apache-2.0"

// Minimum <span class="product-name">formae</span> version required (required)
minFormaeVersion = "0.80.0"

// Output configuration (required)
output {
  renderer = new JsonRenderer {}
}

Fields

name

Type: String Required: Yes

Plugin identifier used in file names and references. Must be:

  • Lowercase
  • Start with a letter
  • Contain only letters, numbers, and hyphens

Examples:

name = "aws"
name = "my-cloud"
name = "openstack-v2"

version

Type: String Required: Yes

Semantic version following SemVer format.

Examples:

version = "1.0.0"
version = "0.1.0-beta"
version = "2.3.1+build.123"

namespace

Type: String Required: Yes

Prefix for all resource types managed by this plugin. Must be:

  • Uppercase
  • Start with a letter
  • Contain only letters and numbers

Resource types follow the pattern NAMESPACE::SERVICE::RESOURCE.

Examples:

namespace = "AWS"       // Resources: AWS::EC2::Instance, AWS::S3::Bucket
namespace = "AZURE"     // Resources: AZURE::Compute::VM
namespace = "MYCLOUD"   // Resources: MYCLOUD::Storage::Item

description

Type: String Required: Yes

Human-readable description of what the plugin does.

Example:

description = "Amazon Web Services (AWS) provider plugin for Formae"

license

Type: String Required: Yes

SPDX license identifier for your plugin.

Common values:

License SPDX ID
Apache License 2.0 Apache-2.0
MIT License MIT
Mozilla Public License 2.0 MPL-2.0
Functional Source License FSL-1.1-ALv2

Example:

license = "Apache-2.0"

minFormaeVersion

Type: String Required: Yes

Minimum formae version required to run this plugin. The agent will refuse to load plugins that require a newer version.

Example:

minFormaeVersion = "0.80.0"

output

Type: Object Required: Yes

Output configuration for PKL evaluation.

Example:

output {
  renderer = new JsonRenderer {}
}

Complete Example

/*
 * Formae Plugin Manifest
 *
 * MyCloud provider plugin for managing cloud resources.
 */

name = "mycloud"
version = "1.2.0"
namespace = "MYCLOUD"
description = "MyCloud infrastructure provider for Formae"
license = "Apache-2.0"
minFormaeVersion = "0.80.0"

output {
  renderer = new JsonRenderer {}
}

Validation

The manifest is validated when:

  1. Plugin init - formae plugin init validates input before scaffolding
  2. Build - make build reads the manifest to determine output names
  3. Install - make install copies the manifest to the installation directory
  4. Agent startup - The agent validates manifests when discovering plugins

Validation Rules

Field Rule
name Matches pattern ^[a-z][a-z0-9-]*$
version Valid semantic version
namespace Matches pattern ^[A-Z][A-Za-z0-9]*$
minFormaeVersion Valid semantic version

See Also