Package Api schema — API Protocol reference

Package API Protocol — REST API endpoint schemas for package lifecycle management.

Package API Protocol

REST API endpoint schemas for package lifecycle management.

Base path: /api/v1/packages

Endpoints

POST   /api/v1/packages                      — Install a package
GET    /api/v1/packages                      — List installed packages
GET    /api/v1/packages/:packageId           — Get package details
POST   /api/v1/packages/:packageId/rollback  — Rollback a package
DELETE /api/v1/packages/:packageId           — Uninstall a package

Five declarations of this API live one file over, on purpose

The two READ responses (ListInstalledPackagesResponseSchema, GetInstalledPackageResponseSchema), the installed-row stages they are bound to (AssembledInstalledPackageSchema, InstalledPackageAtEitherStageSchema) and the PackageApiContracts map that names both responses are declared in ./package-api-assembled.zod.ts and published from @objectstack/spec/api-assembled, not from @objectstack/spec/api.

The reason is weight, not meaning. Four of them carry the ASSEMBLED package body (the fifth, the route map, names two of those four), which is the whole metadata vocabulary (../stack.zod) plus the datasource and driver-config validators behind it. While they sat in this file, every @objectstack/spec/api bundle linked that tree, and a browser consumer that imported two string constants from ./sortability.zod paid for all of it: measured at about twice the gzipped bundle of the same import before the stage declarations arrived. The maintainer ruling on #18576 (letter B) split the entry so the browser-facing half does not carry them.

⛔ Nothing in this file may import ../stack.zod or anything that reaches ../data/datasource.zod: that edge is exactly what the split removed from @objectstack/spec/api, and ./api-entry-graph.pin.test.ts refuses it. A declaration that needs the assembled body goes in the sibling file.

Source: packages/spec/src/api/package-api.zod.ts

TypeScript Usage

import { GetInstalledPackageRequestSchema, ListInstalledPackagesRequestSchema, PackageApiErrorCode, PackageInstallBodySchema, PackageInstallRequestSchema, PackageInstallResponseSchema, PackagePathParamsSchema, PackageRollbackRequestSchema, PackageUpgradeRequestSchema, PackageUpgradeResponseSchema, ResolveDependenciesRequestSchema, ResolveDependenciesResponseSchema, UninstallPackageApiRequestSchema, UninstallPackageApiResponseSchema, UploadArtifactRequestSchema, UploadArtifactResponseSchema } from '@objectstack/spec/api';
import type { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackageInstallBody, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';

// Validate data
const result = GetInstalledPackageRequestSchema.parse(data);

GetInstalledPackageRequest

Get installed package request

Property	Type	Required	Description
packageId	`string`	✅	Package identifier
version	`string`	optional	Scope the read to this exact installed version; `latest` or omitted reads the installed row

Property	Type	Required	Description
status	`Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>`	optional	Filter by package status
enabled	`boolean`	optional	Filter by enabled state
type	`string`	optional	Filter by the installed manifest's `type` — exact match, unmatched values select nothing
limit	`never`	optional	[REMOVED] `limit` / `cursor` were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on `status` / `type` / `enabled` and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. `limit` also declared `.default(50)`, so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and `hasMore` on the response is a constant `false` that is now true by construction. Filter with `status`, `type` and `enabled` instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key.
cursor	`never`	optional	[REMOVED] `limit` / `cursor` were removed from GET /api/v1/packages in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — both were declared here and read by nothing: the serving door filters on `status` / `type` / `enabled` and then returns every remaining row, so no page was ever withheld and no continuation token was ever minted. `limit` also declared `.default(50)`, so a reader of the published schema was entitled to believe an unparameterised list is capped at 50 rows; it has never been capped at all, and nothing parses a query string through this schema, so that default has never been stamped onto anything. Delete the key. This route is NOT paginated — it answers the whole installed set, which is a bounded table of tens of rows, and `hasMore` on the response is a constant `false` that is now true by construction. Filter with `status`, `type` and `enabled` instead of asking for a window. A first-class package cursor, if one is ever designed, will be a response-minted opaque token, not this key.

Property	Type	Required	Description
manifest	`{ id: string; namespace?: string; defaultDatasource?: string; version: string; … }`	✅	Package manifest to install (AUTHORING stage: `objects` are glob patterns)
settings	`Record<string, any>`	optional	User-provided settings at install time
enableOnInstall	`boolean`	optional	Whether to enable immediately after install — honoured at POST /api/v1/packages: `true` enables the installed row, `false` disables it, and ABSENT keeps the row's current lifecycle state (a fresh install lands enabled)
overwrite	`boolean`	optional	Overwrite an already-installed package id instead of answering 409 Conflict
platformVersion	`string`	optional	Current platform version for compatibility verification
artifactRef	`{ url: string; sha256: string; size: integer; format?: Enum<'tgz' \| 'zip'>; … }`	optional	Artifact reference for marketplace installation

Property	Type	Required	Description
id	`string`	✅	Unique package identifier — must match reverse-domain notation (e.g. com.acme.crm)
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: `"default"`)	Default datasource for all objects in this package
version	`string`	✅	Package version (SemVer 2.0.0 — e.g. 1.2.3, 2.0.0-beta.1, 1.0.0+20230101)
type	`Enum<'plugin' \| 'ui' \| 'driver' \| 'server' \| 'app' \| 'theme' \| 'agent' \| 'objectql' \| …>`	✅	Type of package
scope	`Enum<'cloud' \| 'system' \| 'project'>`	optional (default: `"project"`)	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 at the AUTHORING stage: legacy string[] or structured plugin block (ADR-0025 §3.2) — at the assembled stage the same key is the ADR-0090 `PermissionSet[]` collection instead (`AssembledPackageBodySchema`)
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	`never`	optional	[REMOVED] `manifest.configuration` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — nothing ever read the block: no settings UI rendered it and no loader resolved a setting from it, so authoring it configured nothing. Worse, `properties.*.secret` promised "value is encrypted/masked (e.g. API Keys)" while nothing encrypted, masked or even parsed the flag — a false assurance about credential handling. Delete the key. A plugin is configured by the host that composes it: pass options to its constructor in `defineStack({ plugins: [new MyPlugin({ … })] })`, which is the enforced channel. A declarative settings surface must be designed with an enforcing reader first, not revived here.
contributes	`{ kinds?: 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	`never`	optional	[REMOVED] `manifest.capabilities` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — no discovery path ever consulted the block: nothing read `implements`, `provides`, `requires`, `extensionPoints` or `extensions`, so the declared "interoperability and automatic discovery" never happened. Delete the key. Real dependency resolution runs off top-level `manifest.dependencies`, which stays. Capability-based discovery must be designed with an enforcing reader first, not revived here.
extensions	`never`	optional	[REMOVED] `manifest.extensions` was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — an untyped map with zero readers: whatever was parked here was stored and never consulted. Delete the key. Extend the platform through the enforced channels instead: `contributes.kinds` registers metadata kinds, `navigationContributions` injects navigation into other packages' apps, and code-level extension happens in the plugin itself (`init`/`start`).
navigationContributions	`{ app: string; group?: string; priority?: integer; items: (object \| … +9 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 (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 — and the plugin trust tier (`manifest.runtime`) does not give it back: that tier is enforced at the cloud marketplace PUBLISH gate only (an unverified publisher requesting the `node` tier is rejected with HTTP 422 and forced to manual review), while load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares. ⛔ Nor do the permission declarations give it back: the install-time granted set is REGISTERED on the PluginPermissionEnforcer at load and queried by nothing, so it refuses no operation. Neither surface confines a plugin today — do not author either one expecting isolation.
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 the plugin declares (ADR-0025 §3.6) — enforced at the cloud marketplace publish gate (unverified publisher requesting `node` → HTTP 422 + manual review); load-side enforcement is NOT implemented, so a locally installed plugin is not isolated by the tier it declares
packaging	`Enum<'bundled' \| 'manifest-deps'>`	optional	Dependency packaging strategy (ADR-0025 §3.3)
main	`string`	optional	Entry module of a code-bearing plugin, relative to the plugin root; `os plugin build` bundles it and writes `dist/index.mjs` here in the compiled manifest (ADR-0025 §3.4)
integrity	`Record<string, string>`	optional	Per-file content digests of the plugin artifact (ADR-0025 §3.2)

Package Api schema — API Protocol reference

On this page