Manifest
Complete field and capability specification for manifest.json and defineBlock({ manifest }).
Every block declares metadata, surfaces, ports, environment variables, and security capabilities in manifest.json (or inline on defineBlock({ manifest })).
For editor autocomplete and validation in local projects, point $schema at the JSON Schema shipped in @orbixdocs/sdk:
{
"$schema": "./node_modules/@orbixdocs/sdk/manifest.schema.json",
"id": "com.acme.sprint-tracker",
"name": "Sprint Tracker",
"version": "1.2.0",
"sdk": "^3.0.0",
"description": "Track sprint goals and velocity inside any document.",
"author": "Acme Tools",
"license": "MIT",
"category": "Productivity",
"icon": "CheckSquare",
"surfaces": ["block", "fullpage", "sidebar_panel"],
"slashShortcut": "/sprint-tracker",
"schemaVersion": 1,
"capabilities": {
"storage": ["local", "persistent"],
"document": ["read"],
"blocks": ["events", "connections"]
},
"inputs": {
"filterTag": { "type": "string", "label": "Filter Tag" }
},
"outputs": {
"completedCount": { "type": "number", "label": "Completed Count" }
}
}Top-level fields
| Field | Type | Required | Default (normalizeManifest) | Description |
|---|---|---|---|---|
id | string | Yes | 'custom-block' (inline fallback) | Lowercase identifier (2–128 chars in schema) matching ^(@[a-z0-9-]+/)?[a-z0-9]+([._-][a-z0-9]+)*$. com.orbix.* is reserved for built-in Orbix blocks and is rejected by validateManifest, publishing, and Marketplace installation. |
version | string | Yes | '1.0.0' | Exact SemVer release string (MAJOR.MINOR.PATCH, optional pre-release/build suffix). |
name | string | Yes (or displayName) | Derived from id | Human-readable title (1–80 chars) shown in the / slash menu and Marketplace. |
displayName | string | Alias for name | Derived from id | Display title alias. |
sdk | string | No | undefined | Compatible @orbixdocs/sdk SemVer range (for example '^3.0.0', '~3.0.0', '>=3.0.0 <4.0.0', or '3.x'). Checked by defineBlock and blockStudioRegistry.register; incompatible ranges throw SDK_VERSION_MISMATCH. Omitting sdk is accepted. |
description | string | No | '' | Short summary (<= 500 chars) shown in listings and slash search. |
author | string | No | 'Orbix Author' | Author name, handle, or organization. |
license | string | No | 'MIT' | SPDX license identifier. |
category | string | No | 'Custom' | Grouping label in the / slash menu and Marketplace (non-empty string when present). |
icon | string | No | 'Layers' | Lucide icon identifier or emoji character. |
entry | string | No | undefined | Informational relative entry path ("src/index.tsx") for CLI and editor tooling. Not read at runtime in Block Studio. |
type | 'block' | 'app' | 'hybrid' | No | 'block' | Architectural classification. |
surfaces | ('block' | 'fullpage' | 'sidebar_panel')[] | No | ['block'] | Rendering surfaces supported by the block (must be a non-empty array when specified). |
slashShortcut | string | No | undefined | Editor slash command trigger matching ^/[a-zA-Z0-9][a-zA-Z0-9-_]*$ (must begin with '/'). |
schemaVersion | number | No | 1 | Positive integer (>= 1) tracking persisted state schema version for migrations. |
scopeMode | 'team' | 'personal' | 'hybrid' | No | undefined | Default scope mode hint. |
capabilities | BlockCapabilitiesManifest | No | {} (inherits tier defaults) | Requested runtime capabilities (see table below). |
inputs | Record<string, Port> | Port[] | No | {} | Reactive input ports accepted from other blocks. |
outputs | Record<string, Port> | Port[] | No | {} | Reactive output ports published to other blocks. |
env | Record<string, EnvVarDef> | No | undefined | User-supplied environment variables and API keys read via useOrbixEnv. |
keywords | string[] | No | [] | Search keywords for / slash menu discovery. |
documentation | string | No | '' | URL to block documentation or repository. |
capabilities fields
Remember that declaring any key under capabilities replaces the community default for that key ({ ...tierDefaults, ...declared }).
| Key | Canonical type | Allowed values / properties |
|---|---|---|
document | DocumentCapability[] | boolean | 'read', 'write', 'navigate' |
workspace | WorkspaceCapability[] | boolean | 'read:all_pages', 'read:graph', 'read:subpages', 'read:headings', 'write:pages' |
blocks | BlockGraphCapability[] | boolean | 'read', 'write', 'events', 'connections' |
storage | StorageCapability[] | boolean | 'local', 'persistent', 'cache', 'session' |
ai | AICapability[] | boolean | 'generate', 'context:document', 'context:selection', 'vision' |
workers | WorkerCapability[] | boolean | 'compute', 'wasm' |
clipboard | ('read' | 'write')[] | boolean | 'read', 'write' |
database | DatabaseCapability | { read?: string[], write?: string[], create?: boolean, workspace?: boolean } |
network | NetworkCapability | boolean | { domains: string[], methods?: ('GET'|'POST'|'PUT'|'DELETE'|'PATCH'|'HEAD')[], websocket?: boolean } |
audio, camera, microphone, geolocation, notification, crossBlockData | boolean | true or false |
inputs and outputs port definitions
normalizePortList accepts ports as an object map or an array:
{
"inputs": {
"taxRate": "number",
"lineItems": {
"type": "array",
"label": "Line Items",
"description": "Items to sum",
"required": false
}
}
}Supported port type values: 'string', 'number', 'boolean', 'array', 'object', 'record', 'any'.
env variable definitions
Each entry in manifest.env accepts:
| Property | Type | Description |
|---|---|---|
label | string | Human-readable field label shown in Environment Secrets and EnvSetupCard. |
description | string | Explanation of how the key is used and where to obtain one. |
required | boolean | Whether the block requires this key before running external requests. |
secret | boolean | Masks input characters (type="password"). |
default | string | Non-sensitive default value (never place real credentials here). |
placeholder | string | Input placeholder such as 'sk-...'. |
Block properties schemas
Pass properties alongside manifest on defineBlock to declare typed inspector properties, default values, and custom runtime validators:
import {
createPropertySchema,
resolvePropertyDefaults,
validateBlockProperties,
type PropertySchemaMap,
} from '@orbixdocs/sdk';
export const chartProperties: PropertySchemaMap = {
title: createPropertySchema({
type: 'string',
default: 'Weekly Velocity',
label: 'Chart Title',
}),
maxBars: createPropertySchema({
type: 'number',
default: 12,
min: 1,
max: 52,
validate: (val) =>
val >= 1 && val <= 52 ? true : 'maxBars must be between 1 and 52',
}),
layout: createPropertySchema({
type: 'enum',
options: ['stacked', 'grouped'],
default: 'stacked',
}),
};
const resolved = resolvePropertyDefaults(chartProperties, { maxBars: 8 });
const errors = validateBlockProperties('acme.velocity-chart', resolved, chartProperties);
console.log(resolved, errors);Programmatic validation (validateManifest)
Call validateManifest(raw) in CI scripts or tests to enforce strict field validation. Unlike normalizeManifest (which fills defaults permissively), validateManifest throws OrbixSDKError (code: 'INVALID_MANIFEST' or 'SDK_VERSION_MISMATCH') with .field, .hint, and .docsUrl when a rule fails:
import { validateManifest, OrbixSDKError } from '@orbixdocs/sdk';
try {
const manifest = validateManifest({
id: 'com.acme.sprint-tracker',
name: 'Sprint Tracker',
version: '1.2.0',
sdk: '^3.0.0',
surfaces: ['block'],
slashShortcut: '/sprint-tracker',
capabilities: {
storage: ['local', 'persistent'],
},
});
console.log('Validated block ID:', manifest.id);
} catch (err) {
if (err instanceof OrbixSDKError) {
console.error(`Invalid field "${err.field}": ${err.message}`);
}
}