Metadata Plugin Metadata Plugin protocol schemas
Defines the specification for the Metadata Plugin — the central authority
responsible for managing ALL metadata across the ObjectStack platform.
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) │ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ └──────────────────────────────────────────────────────────────────┘
Salesforce : Metadata API (deploy, retrieve, describe)ServiceNow : System Dictionary + Metadata APIKubernetes : API Server + CRD Registry
Source: packages/spec/src/kernel/metadata-plugin.zod.ts
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); 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
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
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 booleanoptional Emit metadata change events validateOnWrite booleanoptional Validate metadata on write enableVersioning booleanoptional Track metadata version history cacheMaxItems integeroptional Max items in memory cache bootstrap Enum<'eager' | 'lazy' | 'artifact-only'>optional How metadata is primed at plugin start (eager / lazy / artifact-only)
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 stringoptional Plugin description capabilities { crud?: boolean; query?: boolean; overlay?: boolean; watch?: boolean; … }✅ Plugin capabilities config { storage: object; customizationPolicies?: object[]; mergeStrategy?: object; additionalTypes?: object[]; … }optional Plugin configuration
Property Type Required Description types Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | 'view' | 'page' | 'dashboard' | 'app' | 'action' | 'report' | 'dataset' | 'flow' | 'job' | 'datasource' | 'external_catalog' | 'translation' | 'api' | 'email_template' | 'doc' | 'book' | 'permission' | 'position' | 'capability' | 'agent' | 'tool' | 'skill'>[]optional Filter by metadata types namespaces string[]optional Filter by namespaces packageId stringoptional Filter by owning package search stringoptional 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
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
objectfieldhookseedmappingviewpagedashboardappactionreportdatasetflowjobdatasourceexternal_catalogtranslationapiemail_templatedocbookpermissionpositioncapabilityagenttoolskill
Property Type Required Description type Enum<'object' | 'field' | 'hook' | 'seed' | 'mapping' | 'view' | 'page' | 'dashboard' | 'app' | 'action' | 'report' | 'dataset' | 'flow' | 'job' | 'datasource' | … +12 more>✅ Metadata type identifier label string✅ Display label for the metadata type description stringoptional Description of the metadata type filePatterns string[]✅ Glob patterns to discover files of this type supportsOverlay booleanoptional Whether overlay customization is supported allowOrgOverride booleanoptional Allow per-org overlay writes via runtime metadata API allowRuntimeCreate booleanoptional Allow runtime creation via API supportsVersioning booleanoptional Whether version history is tracked executionPinned booleanoptional Transaction rows reference a specific version_hash; history GC is disabled and getByHash() MUST resolve old hashes (ADR-0009) loadOrder integeroptional Loading priority (lower = earlier) domain Enum<'data' | 'ui' | 'automation' | 'system' | 'security' | 'ai'>✅ Protocol domain actions { name: string; label: string | Record<string, string>; description?: string | Record<string, string>; objectName?: string; … }[]optional Declarative type-level actions (e.g. datasource "Test connection"), reusing ActionSchema; merged with plugin-registered actions when emitted
objectfieldhookseedmappingviewpagedashboardappactionreportdatasetflowjobdatasourceexternal_catalogtranslationapiemail_templatedocbookpermissionpositioncapabilityagenttoolskill
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
ObjectStack