Plugin schema — Studio Protocol reference

Defines the specification for Studio plugins — a VS Code-like extension model that allows each metadata type to contribute custom viewers, designers.

Studio Plugin Protocol

Defines the specification for Studio plugins — a VS Code-like extension model that allows each metadata type to contribute custom viewers, designers, sidebar groups, actions, and commands.

Architecture

Like VS Code extensions, Studio plugins have two layers:

Manifest (Declarative) — JSON-serializable contribution points
Activation (Imperative) — Runtime registration of React components & handlers

┌─────────────────────────────────────────────────────────┐
│                    Studio Host                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │              Plugin Registry                      │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐         │  │
│  │  │ Object   │ │  Flow    │ │  Agent   │  ...     │  │
│  │  │ Plugin   │ │  Plugin  │ │  Plugin  │         │  │
│  │  └──────────┘ └──────────┘ └──────────┘         │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  ┌─── Sidebar ───┐  ┌──── Main Panel ────────────────┐ │
│  │ [plugin icons] │  │  PluginHost renders viewer     │ │
│  │ [plugin groups]│  │  from highest-priority plugin  │ │
│  └────────────────┘  └────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

import { StudioPluginManifestSchema } from '@objectstack/spec/studio';

const manifest = StudioPluginManifestSchema.parse({
  id: 'objectstack.object-designer',
  name: 'Object Designer',
  version: '1.0.0',
  contributes: {
    metadataViewers: [{
      id: 'object-explorer',
      metadataTypes: ['object', 'objects'],
      label: 'Object Explorer',
      priority: 100,
      modes: ['preview', 'design', 'data'],
    }],
  },
});

Source: packages/spec/src/studio/plugin.zod.ts

TypeScript Usage

import { ActionContributionSchema, ActionContributionLocationSchema, CommandContributionSchema, MetadataIconContributionSchema, MetadataViewerContributionSchema, PanelContributionSchema, PanelLocationSchema, SidebarGroupContributionSchema, StudioPluginContributionsSchema, StudioPluginManifestSchema, ViewModeSchema } from '@objectstack/spec/studio';
import type { ActionContribution, ActionContributionLocation, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, PanelLocation, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio';

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

ActionContribution

Properties

Property	Type	Required	Description
id	`string`	✅	Unique action identifier
label	`string`	✅	Action display label
icon	`string`	optional	Lucide icon name
location	`Enum<'toolbar' \| 'contextMenu' \| 'commandPalette'>`	✅	UI location
metadataTypes	`string[]`	optional (default: `[]`)	Applicable metadata types

ActionContributionLocation

Allowed Values

toolbar
contextMenu
commandPalette

CommandContribution

Properties

Property	Type	Required	Description
id	`string`	✅	Unique command identifier
label	`string`	✅	Command display label
shortcut	`string`	optional	Keyboard shortcut
icon	`string`	optional	Lucide icon name

MetadataIconContribution

Properties

Property	Type	Required	Description
metadataType	`string`	✅	Metadata type
label	`string`	✅	Display label
icon	`string`	✅	Lucide icon name

MetadataViewerContribution

Properties

Property	Type	Required	Description
id	`string`	✅	Unique viewer identifier
metadataTypes	`string[]`	✅	Metadata types this viewer can handle
label	`string`	✅	Viewer display label
priority	`number`	optional (default: `0`)	Viewer priority (higher wins)
modes	`Enum<'preview' \| 'design' \| 'code' \| 'data' \| 'history'>[]`	optional (default: `["preview"]`)	Supported view modes

PanelContribution

Properties

Property	Type	Required	Description
id	`string`	✅	Unique panel identifier
label	`string`	✅	Panel display label
icon	`string`	optional	Lucide icon name
location	`Enum<'bottom' \| 'right' \| 'modal'>`	optional (default: `"bottom"`)	Panel location

PanelLocation

Allowed Values

bottom
right
modal

SidebarGroupContribution

Properties

Property	Type	Required	Description
key	`string`	✅	Unique group key
label	`string`	✅	Group display label
icon	`string`	optional	Lucide icon name
metadataTypes	`string[]`	✅	Metadata types in this group
order	`number`	optional (default: `100`)	Sort order (lower = higher)

StudioPluginContributions

Properties

Property	Type	Required
metadataViewers	`{ id: string; metadataTypes: string[]; label: string; priority?: number; … }[]`	optional (default: `[]`)
sidebarGroups	`{ key: string; label: string; icon?: string; metadataTypes: string[]; … }[]`	optional (default: `[]`)
actions	`{ id: string; label: string; icon?: string; location: Enum<'toolbar' \| 'contextMenu' \| 'commandPalette'>; … }[]`	optional (default: `[]`)
metadataIcons	`{ metadataType: string; label: string; icon: string }[]`	optional (default: `[]`)
panels	`{ id: string; label: string; icon?: string; location?: Enum<'bottom' \| 'right' \| 'modal'> }[]`	optional (default: `[]`)
commands	`{ id: string; label: string; shortcut?: string; icon?: string }[]`	optional (default: `[]`)

Nested Shape: `StudioPluginContributions.metadataViewers[number]`

Property	Type	Required	Description
id	`string`	✅	Unique viewer identifier
metadataTypes	`string[]`	✅	Metadata types this viewer can handle
label	`string`	✅	Viewer display label
priority	`number`	optional (default: `0`)	Viewer priority (higher wins)
modes	`Enum<'preview' \| 'design' \| 'code' \| 'data' \| 'history'>[]`	optional (default: `["preview"]`)	Supported view modes

Nested Shape: `StudioPluginContributions.sidebarGroups[number]`

Property	Type	Required	Description
key	`string`	✅	Unique group key
label	`string`	✅	Group display label
icon	`string`	optional	Lucide icon name
metadataTypes	`string[]`	✅	Metadata types in this group
order	`number`	optional (default: `100`)	Sort order (lower = higher)

Nested Shape: `StudioPluginContributions.actions[number]`

Property	Type	Required	Description
id	`string`	✅	Unique action identifier
label	`string`	✅	Action display label
icon	`string`	optional	Lucide icon name
location	`Enum<'toolbar' \| 'contextMenu' \| 'commandPalette'>`	✅	UI location
metadataTypes	`string[]`	optional (default: `[]`)	Applicable metadata types

Nested Shape: `StudioPluginContributions.metadataIcons[number]`

Property	Type	Required	Description
metadataType	`string`	✅	Metadata type
label	`string`	✅	Display label
icon	`string`	✅	Lucide icon name

Nested Shape: `StudioPluginContributions.panels[number]`

Property	Type	Required	Description
id	`string`	✅	Unique panel identifier
label	`string`	✅	Panel display label
icon	`string`	optional	Lucide icon name
location	`Enum<'bottom' \| 'right' \| 'modal'>`	optional (default: `"bottom"`)	Panel location

Nested Shape: `StudioPluginContributions.commands[number]`

Property	Type	Required	Description
id	`string`	✅	Unique command identifier
label	`string`	✅	Command display label
shortcut	`string`	optional	Keyboard shortcut
icon	`string`	optional	Lucide icon name

StudioPluginManifest

Properties

Property	Type	Required	Description
id	`string`	✅	Plugin ID (dot-separated lowercase)
name	`string`	✅	Plugin display name
version	`string`	optional (default: `"0.0.1"`)	Plugin version
description	`string`	optional	Plugin description
author	`string`	optional	Author
contributes	`{ metadataViewers?: object[]; sidebarGroups?: object[]; actions?: object[]; metadataIcons?: object[]; … }`	optional (has default)

ViewMode

Allowed Values

preview
design
code
data
history

Plugin schema — Studio Protocol reference

On this page