> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitzli.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin manifest reference

> Choose the correct protocol and validate exact runtime release descriptors.

Native extensions use JSON with `kind: "extension"` and top-level runtime fields. Their source file is `manifest.json`; release tooling emits identical `tabularium.json` and `<name>-universal.json` assets after resolving the actual image digest.

## Choose the validator

| Contract | Validator and source |
| - | - |
| Native extension v2 | Rust `webdock_plugin_protocol::Manifest::parse` in [cloud-plugin-sdk](https://github.com/spitzli/cloud-plugin-sdk) |
| Established TypeScript extension v1 | `parsePluginManifest` in the [retained TypeScript SDK](https://github.com/spitzli/cloud/tree/main/packages/plugin-sdk) |
| Repository or Mail provider | The dedicated provider repository and protocol |

V2 requires `protocolVersion`, `sdkVersion` and `dataProtocolVersion` all set to `2`. V1 keeps all three at `1`. Never migrate by editing version numbers alone. Use [Echo's manifest](https://github.com/spitzli/cloud-plugin-echo-demo/blob/main/manifest.json) as a complete native example and replace any authoring image placeholder through the release workflow.

## Runtime fields

| Field | Meaning |
| - | - |
| `name`, `version` | Stable lowercase slug and exact SemVer release identity |
| `coreVersion` | Supported Core SemVer range |
| `image` | Actual immutable OCI image reference with a SHA-256 digest |
| `dependencies` | Explicit dependency identities and versions |
| `capabilities` | Requested host capabilities, never automatic grants |
| `schemaVersion`, `readableSchema` | Plugin data schema version and compatible reading range |
| `tables`, `migrations` | Bounded declarative data definitions; availability depends on host support |
| `services` | Explicit required and optional host service versions |
| `configuration` | Bounded JSON Schema without external references |
| `actions` | Named read/write actions with input/output schemas and capability requirements |
| `jobs` | Declared background handlers; declaration alone does not enable scheduling |
| `api`, `mcp` | Interfaces referencing declared actions |
| `secrets`, `httpBindings` | Binding names, never credentials or arbitrary host destinations |
| `offerings`, `selfService`, `areas` | Native resource offerings, feature policy and UI contributions |

Keep the `services` object even when no host service is needed: use `"services": { "required": [], "optional": [] }`. Other unused array declarations can use `[]`. The parser rejects unknown or privileged fields, duplicate keys, unsupported schema constructs, mutable images and invalid action/capability relationships. Runtime admission additionally checks installation state, project access, current grants, configuration and available host services.

## Release verification

Validate with the parser that matches your pinned SDK revision. Registry authoring validation is useful but cannot substitute for semantic validation or host compatibility checks. The hosted registry now admits the complete v1 and v2 contracts. A self-hosted registry still needs the matching admission policy; source support alone does not configure it.

The host bounds manifest and descriptor input to 256 KiB. Registry authoring/publication can impose a smaller 64 KiB bound. Publish final assets only after image resolution and preserve their exact bytes: JSON reformatting changes the signed hash.

See [independent releases](https://docs.spitzli.cloud/developers/plugin-releases.md) for pinned-key verification, preserved v1 signatures and special provider bindings. Source contracts: [native parser](https://github.com/spitzli/cloud-plugin-sdk/blob/8ed57d89c3263b050f126e4c2ba7f6cdebb0daa6/crates/plugin-protocol/src/manifest.rs) and [release verification](https://github.com/spitzli/cloud-plugin-sdk/blob/8ed57d89c3263b050f126e4c2ba7f6cdebb0daa6/crates/plugin-protocol/src/release.rs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.