---
title: Metadata Plugin
description: Metadata Plugin protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# 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

<Callout type="info">
**Source:** `packages/spec/src/kernel/metadata-plugin.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataQuery, MetadataQueryResult, MetadataType, MetadataValidationResult } from '@objectstack/spec/kernel';
import type { MetadataBulkRegisterRequest, MetadataBulkResult, MetadataDependency, MetadataEvent, MetadataQuery, MetadataQueryResult, MetadataType, 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' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| '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 |


---

## MetadataQuery

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **types** | `Enum<'object' \| 'field' \| 'trigger' \| 'validation' \| 'hook' \| 'seed' \| 'view' \| 'page' \| 'dashboard' \| 'app' \| 'action' \| 'report' \| 'dataset' \| 'flow' \| 'job' \| 'datasource' \| 'external_catalog' \| '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`
* `seed`
* `view`
* `page`
* `dashboard`
* `app`
* `action`
* `report`
* `dataset`
* `flow`
* `job`
* `datasource`
* `external_catalog`
* `translation`
* `router`
* `function`
* `service`
* `email_template`
* `permission`
* `profile`
* `role`
* `agent`
* `tool`
* `skill`


---

## MetadataValidationResult

### Properties

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


---

