Metadata Loader

Metadata Manager Configuration

How the runtime MetadataManager is wired: which datasource backs sys_metadata, what to fall back to when that datasource is unreachable, cache / watch / validation settings, and the persistence write gates.

The loader and watch envelope types (MetadataFormat, MetadataStats, MetadataLoadOptions, MetadataWatchEvent, MetadataLoaderContract, …) are NOT here — they live in @objectstack/spec/system (system/metadata-persistence.zod), which is their single source.

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

TypeScript Usage

import { MetadataFallbackStrategySchema, MetadataManagerConfigSchema } from '@objectstack/spec/kernel';
import type { MetadataFallbackStrategy, MetadataManagerConfig } from '@objectstack/spec/kernel';

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

MetadataFallbackStrategy

Allowed Values

filesystem
memory
none

MetadataManagerConfig

Properties

Property	Type	Required	Description
datasource	`string`	optional	Datasource name reference for database persistence
tableName	`string`	optional (default: `"sys_metadata"`)	Database table name for metadata storage
fallback	`Enum<'filesystem' \| 'memory' \| 'none'>`	optional (default: `"none"`)	Fallback strategy when datasource is unavailable
rootDir	`string`	optional	Root directory path
formats	`Enum<'yaml' \| 'json' \| 'typescript' \| 'javascript'>[]`	optional (default: `["typescript","json","yaml"]`)	Enabled formats
cache	`{ enabled: boolean; ttl: integer; maxSize?: integer; databaseLoader?: object }`	optional	Cache settings
watch	`boolean`	optional (default: `false`)	Enable file watching
watchOptions	`{ ignored?: string[]; persistent: boolean; ignoreInitial: boolean }`	optional	File watcher options
validation	`{ strict: boolean; throwOnError: boolean }`	optional	Validation settings
loaderOptions	`Record<string, any>`	optional	Loader-specific configuration
persistence	`{ writable: boolean }`	optional	Persistence write gates

Nested Shape: `MetadataManagerConfig.cache`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `true`)	Enable caching
ttl	`integer`	optional (default: `3600`)	Cache TTL in seconds
maxSize	`integer`	optional	Max cache size in bytes
databaseLoader	`{ enabled: boolean; maxSize: integer; ttl: integer }`	optional	DatabaseLoader read-through cache

Nested Shape: `MetadataManagerConfig.watchOptions`

Property	Type	Required	Description
ignored	`string[]`	optional	Patterns to ignore
persistent	`boolean`	optional (default: `true`)	Keep process running
ignoreInitial	`boolean`	optional (default: `true`)	Ignore initial add events

Nested Shape: `MetadataManagerConfig.validation`

Property	Type	Required	Description
strict	`boolean`	optional (default: `true`)	Strict validation
throwOnError	`boolean`	optional (default: `true`)	Throw on validation error

Nested Shape: `MetadataManagerConfig.persistence`

Property	Type	Required	Description
writable	`boolean`	optional (default: `true`)	Allow base metadata writes via register()
overlayWritable	`never`	optional	[REMOVED] `persistence.overlayWritable` was removed from `MetadataManagerConfig` in @objectstack/spec 17 (ADR-0049 enforce-or-remove) — the only thing it gated was `MetadataManager.saveOverlay()`, a paper-protocol method no route or UI ever called, removed with the metadata-customization protocol (ADR-0126 supersedes it on the record). Delete the key. The base write gate that remains is `persistence.writable`; the real org-overlay writes (ADR-0005) ride the REST meta write doors' `manage_metadata` permission gate, not this flag.

Metadata Loader

On this page