ObjectStackManifest
Manifest protocol schemas
Source: packages/spec/src/kernel/manifest.zod.ts
TypeScript Usage
import { ManifestSchema, ManifestPermissionsSchema, PluginEnginesSchema, PluginIntegritySchema, PluginPackagingSchema, PluginPermissionsSchema, PluginRuntimeSchema } from '@objectstack/spec/kernel';
import type { ManifestPermissions, PluginEngines, PluginIntegrity, PluginPackaging, PluginPermissions, PluginRuntime } from '@objectstack/spec/kernel';
// Validate data
const result = ManifestSchema.parse(data);Manifest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Unique package identifier (reverse domain style) |
| namespace | string | optional | Short namespace identifier; also the mandatory prefix of every object name (e.g. "todo" → object names "todo_task", "todo_project") |
| defaultDatasource | string | optional | Default datasource for all objects in this package |
| version | string | ✅ | Package version (semantic versioning) |
| type | Enum<'plugin' | 'ui' | 'driver' | 'server' | 'app' | 'theme' | 'agent' | 'objectql' | 'module' | 'gateway' | 'adapter'> | ✅ | Type of package |
| scope | Enum<'cloud' | 'system' | 'project'> | optional | Deployment scope: cloud | system | project |
| name | string | ✅ | Human-readable package name |
| description | string | optional | Package description |
| permissions | string[] | { services?: string[]; hooks?: string[]; network?: string[]; fs?: string[] } | optional | Required permissions: legacy string[] or structured plugin block (ADR-0025 §3.2) |
| objects | string[] | optional | Glob patterns for ObjectQL schemas files |
| datasources | string[] | optional | Glob patterns for Datasource definitions |
| dependencies | Record<string, string> | optional | Package dependencies |
| configuration | { title?: string; properties: Record<string, object> } | optional | Plugin configuration settings |
| contributes | { kinds?: object[]; events?: string[]; menus?: Record<string, object[]>; themes?: object[]; … } | optional | Platform contributions |
| data | { object: string; externalId?: string | string[]; mode?: Enum<'insert' | 'update' | 'upsert' | 'replace' | 'ignore'>; env?: Enum<'prod' | 'dev' | 'test'>[]; … }[] | optional | Initial seed data (prefer top-level data field) |
| capabilities | { implements?: object[]; provides?: object[]; requires?: object[]; extensionPoints?: object[]; … } | optional | Plugin capability declarations for interoperability |
| extensions | Record<string, any> | optional | Extension points and contributions |
| navigationContributions | { app: string; group?: string; priority?: integer; items: (object | … +8 more)[] }[] | optional | Navigation items this package contributes into apps owned by other packages |
| loading | never | optional | [REMOVED] manifest.loading was removed in @objectstack/spec 17.0.0 (#4914, ADR-0049 enforce-or-remove) — the entire block (strategy, preload, codeSplitting, dynamicImport, initialization, dependencyResolution, hotReload, caching, sandboxing, monitoring) had no runtime reader in any repo, so authoring it configured nothing. Delete the key. Plugins are composed at boot — defineStack registers them and the kernel runs init then start in an order topologically resolved from each composed plugin's own dependencies / optionalDependencies (resolvePluginOrder); the set is fixed until the process restarts. ⚠️ loading.sandboxing in particular never isolated anything: it did not run plugins in a process, vm, iframe or web-worker, and allowedServices gated no call. If you were relying on it for isolation, you had none — use the plugin trust tier (manifest.runtime) and the permission declarations, which are enforced. |
| engine | { objectstack: string } | optional | Platform compatibility requirements (legacy; superseded by engines) |
| engines | { platform?: string; protocol?: string } | optional | Plugin compatibility ranges (ADR-0025 §3.2; supersedes engine) |
| runtime | Enum<'node' | 'sandbox' | 'worker'> | optional | Plugin trust tier (ADR-0025 §3.6) |
| packaging | Enum<'bundled' | 'manifest-deps'> | optional | Dependency packaging strategy (ADR-0025 §3.3) |
| integrity | Record<string, string> | optional | Per-file content digests of the plugin artifact (ADR-0025 §3.2) |
ManifestPermissions
Union Options
This schema accepts one of the following structures:
Option 1
Type: string[]
Option 2
Structured plugin permission grants (ADR-0025 §3.2)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| services | string[] | optional | Platform services the plugin may resolve (e.g. "object", "http") |
| hooks | string[] | optional | Lifecycle hooks the plugin may register (e.g. "record.beforeInsert") |
| network | string[] | optional | Network hosts the plugin may reach (e.g. "api.acme.com") |
| fs | string[] | optional | Filesystem paths the plugin may access |
PluginEngines
Plugin compatibility ranges (ADR-0025 §3.2)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| platform | string | optional | ObjectStack platform release range (SemVer, e.g. ">=4.0 <5") |
| protocol | string | optional | Runtime/metadata protocol range, checked first (ADR §3.10 #3) |
PluginIntegrity
Per-file content digests of the plugin artifact (ADR-0025 §3.2)
Type: Record<string, string>
PluginPackaging
Dependency packaging strategy (ADR-0025 §3.3)
Allowed Values
bundledmanifest-deps
PluginPermissions
Structured plugin permission grants (ADR-0025 §3.2)
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| services | string[] | optional | Platform services the plugin may resolve (e.g. "object", "http") |
| hooks | string[] | optional | Lifecycle hooks the plugin may register (e.g. "record.beforeInsert") |
| network | string[] | optional | Network hosts the plugin may reach (e.g. "api.acme.com") |
| fs | string[] | optional | Filesystem paths the plugin may access |
PluginRuntime
Plugin trust tier (ADR-0025 §3.6)
Allowed Values
nodesandboxworker