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 — Storage backend protocol
kernel/metadata-customization.zod.ts — Overlay/merge protocol
system/metadata-persistence.zod.ts — Database record format
contracts/metadata-service.ts — Service interface

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

TypeScript Usage

import { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
import type { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';

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

MetadataBulkRegisterRequest

Properties

Property	Type	Required	Description
items	`Object[]`	✅	Items to register
continueOnError	`boolean`	✅	Continue if individual item fails
validate	`boolean`	✅	Validate before register

MetadataBulkResult

Properties

Property	Type	Required	Description
total	`integer`	✅	Total items processed
succeeded	`integer`	✅	Successfully processed
failed	`integer`	✅	Failed items
errors	`Object[]`	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

MetadataEvent

Properties

Property	Type	Required	Description
event	`Enum<'metadata.registered' \| 'metadata.updated' \| 'metadata.unregistered' \| 'metadata.validated' \| 'metadata.deployed' \| 'metadata.overlay.applied' \| 'metadata.overlay.removed' \| 'metadata.imported' \| 'metadata.exported'>`	✅	Event type
metadataType	`Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'flow' \| 'workflow' \| 'approval' \| 'datasource' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| 'agent' \| 'tool' \| 'skill'>`	✅	Metadata type
name	`string`	✅	Metadata item name
namespace	`string`	optional	Namespace
packageId	`string`	optional	Owning package ID
timestamp	`string`	✅	Event timestamp
actor	`string`	optional	User or system that triggered the event
payload	`Record<string, any>`	optional	Event-specific payload

MetadataPluginConfig

Properties

Property	Type	Required	Description
storage	`Object`	✅	Storage backend configuration
customizationPolicies	`Object[]`	optional	Default customization policies per type
mergeStrategy	`Object`	optional	Merge strategy for package upgrades
additionalTypes	`Object[]`	optional	Additional custom metadata types
enableEvents	`boolean`	✅	Emit metadata change events
validateOnWrite	`boolean`	✅	Validate metadata on write
enableVersioning	`boolean`	✅	Track metadata version history
cacheMaxItems	`integer`	✅	Max items in memory cache
bootstrap	`Enum<'eager' \| 'lazy' \| 'artifact-only'>`	✅	How metadata is primed at plugin start (eager / lazy / artifact-only)

MetadataPluginManifest

Properties

Property	Type	Required	Description
id	`string`	✅	Metadata plugin ID
name	`string`	✅	Plugin name
version	`string`	✅	Plugin version
type	`string`	✅	Plugin type
description	`string`	✅	Plugin description
capabilities	`Object`	✅	Plugin capabilities
config	`Object`	optional	Plugin configuration

MetadataQuery

Properties

Property	Type	Required	Description
types	`Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'flow' \| 'workflow' \| 'approval' \| 'datasource' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| '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	`Object[]`	✅	Matched metadata items
total	`integer`	✅	Total matching items
page	`integer`	✅	Current page
pageSize	`integer`	✅	Page size

MetadataType

Allowed Values

object
field
trigger
validation
hook
view
page
dashboard
app
action
report
flow
workflow
approval
datasource
translation
router
function
service
email_template
permission
profile
role
agent
tool
skill

MetadataTypeRegistryEntry

Properties

Property	Type	Required	Description
type	`Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'flow' \| 'workflow' \| 'approval' \| 'datasource' \| 'translation' \| 'router' \| 'function' \| 'service' \| 'email_template' \| 'permission' \| 'profile' \| 'role' \| '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`	✅	Whether overlay customization is supported
allowOrgOverride	`boolean`	✅	Allow per-org overlay writes via runtime metadata API
allowRuntimeCreate	`boolean`	✅	Allow runtime creation via API
supportsVersioning	`boolean`	✅	Whether version history is tracked
executionPinned	`boolean`	✅	Transaction rows reference a specific version_hash; history GC is disabled and getByHash() MUST resolve old hashes (ADR-0009)
loadOrder	`integer`	✅	Loading priority (lower = earlier)
domain	`Enum<'data' \| 'ui' \| 'automation' \| 'system' \| 'security' \| 'ai'>`	✅	Protocol domain

MetadataValidationResult

Properties

Property	Type	Required	Description
valid	`boolean`	✅	Whether the metadata is valid
errors	`Object[]`	optional	Validation errors
warnings	`Object[]`	optional	Validation warnings

Metadata Plugin

On this page