SDK Manifest Schema
2026-11-15
Field-level reference for the biglazycat manifest; for the project-setup workflow see Plugin Development Process.
Manifest fields (biglazycat in package.json)
The manifest is the biglazycat object in package.json; unknown fields are rejected. Top-level fields:
| Field | Type | Required | Notes |
|---|---|---|---|
| apiVersion | 1 | yes | SDK major version, currently fixed at 1; mismatch reports API_MISMATCH |
| minimumApiRevision | integer | no | Minimum API revision required; the host refuses to install when lower |
| displayName | string | yes | Display name, 1–200 characters |
| description | string | no | Plugin description |
| main | string | no | Backend entry relative path; must not start with /, contain .., \ or :; page-only plugins may omit it |
| mainView | string | no | Main view id, matching ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$ |
| settingsView | string | no | Settings view id |
| platforms | string[] | yes | Targets from windows/amd64, windows/arm64, darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, 1–256 items |
| activation | string[] | no | Auto-activation events: startup, workspace.opened, document.committed |
| dependencies | object[] | no | Runtime plugin-service dependencies, each with plugin, service, version, optional; 0–256 items |
| contributes | object | yes | Contribution points, see below |
Beyond the schema the host also validates platforms, engines, path existence, references and duplicate ids.
contributes
| Key | Fields (bold = required) | Notes |
|---|---|---|
| commands | id, title, description, contexts, aiCallable, externalEffect, visibility, inputSchema | Commands. contexts: workspace, editor.document, editor.selection, resource — where the command applies; aiCallable exposes it to external AI; externalEffect marks outside side effects; visibility: "internal" (revision 2) hides the command from the palette, shortcuts and toolbar while pages can still call it — independent of aiCallable; inputSchema is a restricted JSON Schema supporting type, description, properties, required, additionalProperties, items, enum, minimum, maximum, minLength, maxLength, minItems, maxItems |
| views | id, title, entry, defaultLocation, route, multiple, commandPalette | Pages. entry points to an HTML file in the build output; defaultLocation: tab, panel, window; multiple allows several instances; commandPalette: false (revision 2) avoids duplicating the page with its open command; route starts with / |
| menus | location, command | Menu entries. location: editor.selection, editor.document, resource, toolbar; command references a declared command id |
| services | id, version, methods | Services offered to other plugins; methods holds 1–256 method names |
| providers | id, contract, version, service | Export providers; contract is currently export.text, version fixed at 1, service references a declared service |
| editors | id, title, extensions, view | Custom file editors; extensions like .catnote, 1–256 items; view references a declared page |
| schedules | id, command, intervalSeconds, catchUp | Scheduled tasks; intervalSeconds 10–31536000; catchUp: skip, once |
Service dependencies
dependencies is unrelated to npm dependencies; it declares other plugins' services you call at runtime:
"dependencies": [
{ "plugin": "@scope/text-tools", "service": "text", "version": "^1.0.0", "optional": true }
]
Missing required dependencies, version mismatches or dependency cycles are rejected at enable/startup; optional dependencies never auto-start incompatible versions — callers handle unavailability.