Skip to Content
OrbixDocs
Block SDK · Reference

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:

manifest.json
{
  "$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

FieldTypeRequiredDefault (normalizeManifest)Description
idstringYes'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.
versionstringYes'1.0.0'Exact SemVer release string (MAJOR.MINOR.PATCH, optional pre-release/build suffix).
namestringYes (or displayName)Derived from idHuman-readable title (1–80 chars) shown in the / slash menu and Marketplace.
displayNamestringAlias for nameDerived from idDisplay title alias.
sdkstringNoundefinedCompatible @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.
descriptionstringNo''Short summary (<= 500 chars) shown in listings and slash search.
authorstringNo'Orbix Author'Author name, handle, or organization.
licensestringNo'MIT'SPDX license identifier.
categorystringNo'Custom'Grouping label in the / slash menu and Marketplace (non-empty string when present).
iconstringNo'Layers'Lucide icon identifier or emoji character.
entrystringNoundefinedInformational 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).
slashShortcutstringNoundefinedEditor slash command trigger matching ^/[a-zA-Z0-9][a-zA-Z0-9-_]*$ (must begin with '/').
schemaVersionnumberNo1Positive integer (>= 1) tracking persisted state schema version for migrations.
scopeMode'team' | 'personal' | 'hybrid'NoundefinedDefault scope mode hint.
capabilitiesBlockCapabilitiesManifestNo{} (inherits tier defaults)Requested runtime capabilities (see table below).
inputsRecord<string, Port> | Port[]No{}Reactive input ports accepted from other blocks.
outputsRecord<string, Port> | Port[]No{}Reactive output ports published to other blocks.
envRecord<string, EnvVarDef>NoundefinedUser-supplied environment variables and API keys read via useOrbixEnv.
keywordsstring[]No[]Search keywords for / slash menu discovery.
documentationstringNo''URL to block documentation or repository.

capabilities fields

Remember that declaring any key under capabilities replaces the community default for that key ({ ...tierDefaults, ...declared }).

KeyCanonical typeAllowed values / properties
documentDocumentCapability[] | boolean'read', 'write', 'navigate'
workspaceWorkspaceCapability[] | boolean'read:all_pages', 'read:graph', 'read:subpages', 'read:headings', 'write:pages'
blocksBlockGraphCapability[] | boolean'read', 'write', 'events', 'connections'
storageStorageCapability[] | boolean'local', 'persistent', 'cache', 'session'
aiAICapability[] | boolean'generate', 'context:document', 'context:selection', 'vision'
workersWorkerCapability[] | boolean'compute', 'wasm'
clipboard('read' | 'write')[] | boolean'read', 'write'
databaseDatabaseCapability{ read?: string[], write?: string[], create?: boolean, workspace?: boolean }
networkNetworkCapability | boolean{ domains: string[], methods?: ('GET'|'POST'|'PUT'|'DELETE'|'PATCH'|'HEAD')[], websocket?: boolean }
audio, camera, microphone, geolocation, notification, crossBlockDatabooleantrue 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:

PropertyTypeDescription
labelstringHuman-readable field label shown in Environment Secrets and EnvSetupCard.
descriptionstringExplanation of how the key is used and where to obtain one.
requiredbooleanWhether the block requires this key before running external requests.
secretbooleanMasks input characters (type="password").
defaultstringNon-sensitive default value (never place real credentials here).
placeholderstringInput placeholder such as 'sk-...'.

Block properties schemas

Pass properties alongside manifest on defineBlock to declare typed inspector properties, default values, and custom runtime validators:

src/property-schema.ts
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:

scripts/check-manifest.ts
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}`);
  }
}

On this page