Metadata Plugin Protocol

Defines the specification for the Metadata Plugin — the central authority

responsible for managing ALL metadata across the ObjectStack platform.

Architecture

The Metadata Plugin consolidates all scattered metadata operations into a single,

cohesive plugin that "takes over" the entire platform's metadata management:


┌──────────────────────────────────────────────────────────────────┐

│                     Metadata Plugin                             │

│                                                                  │

│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │

│  │ Type Registry │  │  Loader      │  │ Customization Layer  │  │

│  │ (all types)   │  │  (file/db/s3)│  │ (overlay / merge)    │  │

│  └──────────────┘  └──────────────┘  └──────────────────────┘  │

│                                                                  │

│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │

│  │ Persistence  │  │  Query       │  │ Lifecycle            │  │

│  │ (db records) │  │  (search)    │  │ (validate/deploy)    │  │

│  └──────────────┘  └──────────────┘  └──────────────────────┘  │

└──────────────────────────────────────────────────────────────────┘

Alignment

Salesforce: Metadata API (deploy, retrieve, describe)
ServiceNow: System Dictionary + Metadata API
Kubernetes: API Server + CRD Registry

References

kernel/metadata-loader.zod.ts — MetadataManager wiring (datasource, cache, write gates)
kernel/metadata-customization.zod.ts — Overlay/merge protocol
system/metadata-persistence.zod.ts — Database record format + loader/watch envelope types
contracts/metadata-service.ts — Service interface

Source: packages/spec/src/kernel/metadata-plugin.zod.ts

TypeScript Usage

import { MetadataBulkResultSchema, MetadataDependencySchema, MetadataPluginConfigSchema, MetadataPluginManifestSchema, MetadataQuerySchema, MetadataQueryResultSchema, MetadataTypeSchema, MetadataTypeRegistryEntrySchema, MetadataValidationResultSchema } from '@objectstack/spec/kernel';
import type { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';

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

MetadataBulkResult

Properties

Property	Type	Required	Description
total	`integer`	✅	Total items processed
succeeded	`integer`	✅	Successfully processed
failed	`integer`	✅	Failed items
errors	`{ type: string; name: string; error: string }[]`	optional	Per-item errors

MetadataDependency

Properties

Property	Type	Required	Description
sourceType	`string`	✅	Dependent metadata type
sourceName	`string`	✅	Dependent metadata name
targetType	`string`	✅	Referenced metadata type
targetName	`string`	✅	Referenced metadata name
kind	`Enum<'reference' \| 'extends' \| 'includes' \| 'triggers'>`	✅	How the dependency is formed

MetadataPluginConfig

Properties

Property	Type	Required	Description
storage	`{ datasource?: string; tableName?: string; fallback?: Enum<'filesystem' \| 'memory' \| 'none'>; rootDir?: string; … }`	✅	Storage backend configuration
customizationPolicies	`{ metadataType: string; allowCustomization?: boolean; lockedFields?: string[]; customizableFields?: string[]; … }[]`	optional	Default customization policies per type
mergeStrategy	`{ defaultStrategy?: Enum<'keep-custom' \| 'accept-incoming' \| 'three-way-merge'>; alwaysAcceptIncoming?: string[]; alwaysKeepCustom?: string[]; autoResolveNonConflicting?: boolean }`	optional	Merge strategy for package upgrades
additionalTypes	`{ label: string; description?: string; filePatterns: string[]; supportsOverlay?: boolean; … }[]`	optional	Additional custom metadata types
enableEvents	`boolean`	optional	Emit metadata change events
validateOnWrite	`boolean`	optional	Validate metadata on write
enableVersioning	`boolean`	optional	Track metadata version history
cacheMaxItems	`integer`	optional	Max items in memory cache
bootstrap	`Enum<'eager' \| 'lazy' \| 'artifact-only'>`	optional	How metadata is primed at plugin start (eager / lazy / artifact-only)

MetadataPluginManifest

Properties

Property	Type	Required	Description
id	`'com.objectstack.metadata'`	✅	Metadata plugin ID
name	`'ObjectStack Metadata Service'`	✅	Plugin name
version	`string`	✅	Plugin version
type	`'standard'`	✅	Plugin type
description	`string`	optional	Plugin description
capabilities	`{ crud?: boolean; query?: boolean; overlay?: boolean; watch?: boolean; … }`	✅	Plugin capabilities
config	`{ storage: object; customizationPolicies?: { metadataType: string; allowCustomization?: boolean; lockedFields?: string[]; customizableFields?: string[]; … }[]; mergeStrategy?: object; additionalTypes?: { label: string; description?: string; filePatterns: string[]; supportsOverlay?: boolean; … }[]; … }`	optional	Plugin configuration

MetadataQuery

Properties

Property	Type	Required	Description
types	`Enum<'object' \| 'field' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'position' \| 'agent' \| 'tool' \| 'skill'>[]`	optional	Filter by metadata types
namespaces	`string[]`	optional	Filter by namespaces
packageId	`string`	optional	Filter by owning package
search	`string`	optional	Full-text search query
scope	`Enum<'system' \| 'platform' \| 'user'>`	optional	Filter by scope
state	`Enum<'draft' \| 'active' \| 'archived' \| 'deprecated'>`	optional	Filter by lifecycle state
tags	`string[]`	optional	Filter by tags
sortBy	`Enum<'name' \| 'type' \| 'updatedAt' \| 'createdAt'>`	✅	Sort field
sortOrder	`Enum<'asc' \| 'desc'>`	✅	Sort direction
page	`integer`	✅	Page number
pageSize	`integer`	✅	Items per page

MetadataQueryResult

Properties

Property	Type	Required	Description
items	`{ type: string; name: string; namespace?: string; label?: string; … }[]`	✅	Matched metadata items
total	`integer`	✅	Total matching items
page	`integer`	✅	Current page
pageSize	`integer`	✅	Page size

MetadataType

Allowed Values

object
field
hook
seed
mapping
view
page
dashboard
app
action
report
dataset
flow
job
datasource
external_catalog
translation
email_template
doc
book
permission
position
agent
tool
skill

MetadataTypeRegistryEntry

Properties

Property	Type	Required	Description
type	`Enum<'object' \| 'field' \| 'hook' \| 'seed' \| 'mapping' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| 'translation' \| 'email_template' \| 'doc' \| 'book' \| 'permission' \| 'position' \| 'agent' \| 'tool' \| 'skill'>`	✅	Metadata type identifier
label	`string`	✅	Display label for the metadata type
description	`string`	optional	Description of the metadata type
filePatterns	`string[]`	✅	Glob patterns to discover files of this type
supportsOverlay	`boolean`	optional	Whether overlay customization is supported
allowOrgOverride	`boolean`	optional	Allow per-org overlay writes via runtime metadata API
allowRuntimeCreate	`boolean`	optional	Allow runtime creation via API
supportsVersioning	`boolean`	optional	Whether version history is tracked
executionPinned	`boolean`	optional	Transaction rows reference a specific version_hash; history GC is disabled and getByHash() MUST resolve old hashes (ADR-0009)
loadOrder	`integer`	optional	Loading priority (lower = earlier)
domain	`Enum<'data' \| 'ui' \| 'automation' \| 'system' \| 'security' \| 'ai'>`	✅	Protocol domain
actions	`{ name: string; label: string; objectName?: string; icon?: string; … }[]`	optional	Declarative type-level actions (e.g. datasource "Test connection"), reusing ActionSchema; merged with plugin-registered actions when emitted

MetadataValidationResult

Properties

Property	Type	Required	Description
valid	`boolean`	✅	Whether the metadata is valid
errors	`{ path: string; message: string; code?: string }[]`	optional	Validation errors
warnings	`{ path: string; message: string }[]`	optional	Validation warnings

Metadata Plugin

On this page