Metadata Persistence

Metadata Scope Enum

Defines the lifecycle and mutability of a metadata item.

Source: packages/spec/src/system/metadata-persistence.zod.ts

TypeScript Usage

import { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFallbackStrategy, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataSource, MetadataState, MetadataStats, MetadataWatchEvent, PackagePublishResult } from '@objectstack/spec/system';
import type { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFallbackStrategy, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataSource, MetadataState, MetadataStats, MetadataWatchEvent, PackagePublishResult } from '@objectstack/spec/system';

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

MetadataCollectionInfo

Properties

Property	Type	Required
type	`string`	✅
count	`number`	✅
namespaces	`string[]`	✅

MetadataDiffResult

Properties

Property	Type	Required	Description
type	`string`	✅
name	`string`	✅
version1	`number`	✅
version2	`number`	✅
checksum1	`string`	✅
checksum2	`string`	✅
identical	`boolean`	✅
patch	`any[]`	optional	JSON patch operations
summary	`string`	optional	Human-readable summary of changes

MetadataExportOptions

Properties

Property	Type	Required	Description
types	`string[]`	optional
namespaces	`string[]`	optional
output	`string`	✅	Output directory or file
format	`Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>`	✅

MetadataFallbackStrategy

Allowed Values

filesystem
memory
none

MetadataFormat

Allowed Values

json
yaml
yml
ts
js
typescript
javascript

MetadataHistoryQueryOptions

Properties

Property	Type	Required	Description
limit	`integer`	optional	Maximum number of history records to return
offset	`integer`	optional	Number of records to skip
since	`string`	optional	Only return history after this timestamp
until	`string`	optional	Only return history before this timestamp
operationType	`Enum<'create' \| 'update' \| 'publish' \| 'revert' \| 'delete'>`	optional	Filter by operation type
includeMetadata	`boolean`	✅	Include full metadata payload

MetadataHistoryQueryResult

Properties

Property	Type	Required
records	`Object[]`	✅
total	`integer`	✅
hasMore	`boolean`	✅

MetadataHistoryRecord

Properties

Property	Type	Required	Description
id	`string`	✅
metadataId	`string`	✅	Foreign key to sys_metadata.id
name	`string`	✅
type	`string`	✅
version	`number`	✅	Version number at this snapshot
operationType	`Enum<'create' \| 'update' \| 'publish' \| 'revert' \| 'delete'>`	✅	Type of operation that created this history entry
metadata	`string \| Record<string, any> \| null`	optional	Snapshot of metadata definition at this version (raw JSON string or parsed object)
checksum	`string`	✅	SHA-256 checksum of metadata content
previousChecksum	`string`	optional	Checksum of the previous version
changeNote	`string`	optional	Description of changes made in this version
tenantId	`string`	optional	Tenant identifier for multi-tenant isolation
recordedBy	`string`	optional	User who made this change
recordedAt	`string`	✅	Timestamp when this version was recorded

MetadataHistoryRetentionPolicy

Properties

Property	Type	Required	Description
maxVersions	`integer`	optional	Maximum number of versions to retain
maxAgeDays	`integer`	optional	Maximum age of history records in days
autoCleanup	`boolean`	✅	Enable automatic cleanup of old history
cleanupIntervalHours	`integer`	✅	How often to run cleanup (in hours)

MetadataImportOptions

Properties

Property	Type	Required	Description
source	`string`	✅	Input directory or file
strategy	`Enum<'merge' \| 'replace' \| 'skip'>`	✅
validate	`boolean`	✅

MetadataLoadOptions

Properties

Property	Type	Required	Description
scope	`Enum<'system' \| 'platform' \| 'user'>`	optional
namespace	`string`	optional
raw	`boolean`	optional	Return raw file content instead of parsed JSON
cache	`boolean`	optional
useCache	`boolean`	optional
validate	`boolean`	optional
ifNoneMatch	`string`	optional
recursive	`boolean`	optional
limit	`number`	optional
patterns	`string[]`	optional
loader	`string`	optional	Specific loader to use (e.g. filesystem, database)

MetadataLoadResult

Properties

Property	Type	Required
data	`any`	✅
stats	`Object`	optional
format	`Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>`	optional
source	`string`	optional
fromCache	`boolean`	optional
etag	`string`	optional
notModified	`boolean`	optional
loadTime	`number`	optional

MetadataLoaderContract

Properties

Property	Type	Required	Description
name	`string`	✅
protocol	`Enum<'file:' \| 'http:' \| 's3:' \| 'datasource:' \| 'memory:'>`	✅	Loader protocol identifier
description	`string`	optional
supportedFormats	`string[]`	optional
supportsWatch	`boolean`	optional
supportsWrite	`boolean`	optional
supportsCache	`boolean`	optional
capabilities	`Object`	✅

MetadataManagerConfig

Properties

Property	Type	Required	Description
datasource	`string`	optional	Datasource name reference for database persistence
tableName	`string`	✅	Database table name for metadata storage
fallback	`Enum<'filesystem' \| 'memory' \| 'none'>`	✅	Fallback strategy when datasource is unavailable
rootDir	`string`	optional	Root directory for filesystem-based metadata
formats	`Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>[]`	optional	Enabled metadata formats
watch	`boolean`	optional	Enable file watching for filesystem loaders
cache	`boolean`	optional	Enable metadata caching
watchOptions	`Object`	optional	File watcher options

MetadataRecord

Properties

Property	Type	Required	Description
id	`string`	✅
name	`string`	✅
type	`string`	✅
namespace	`string`	✅
packageId	`string`	optional	Package ID that owns/delivered this metadata
managedBy	`Enum<'package' \| 'platform' \| 'user'>`	optional	Who manages this metadata record lifecycle
scope	`Enum<'system' \| 'platform' \| 'user'>`	✅
metadata	`Record<string, any>`	✅
extends	`string`	optional	Name of the parent metadata to extend/override
strategy	`Enum<'merge' \| 'replace'>`	✅
owner	`string`	optional
state	`Enum<'draft' \| 'active' \| 'archived' \| 'deprecated'>`	✅
tenantId	`string`	optional	Tenant identifier for multi-tenant isolation
version	`number`	✅	Record version for optimistic concurrency control
checksum	`string`	optional	Content checksum for change detection
source	`Enum<'filesystem' \| 'database' \| 'api' \| 'migration'>`	optional	Origin of this metadata record
tags	`string[]`	optional	Classification tags for filtering and grouping
publishedDefinition	`any`	optional	Snapshot of the last published definition
publishedAt	`string`	optional	When this metadata was last published
publishedBy	`string`	optional	Who published this version
createdBy	`string`	optional
createdAt	`string`	optional	Creation timestamp
updatedBy	`string`	optional
updatedAt	`string`	optional	Last update timestamp

MetadataSaveOptions

Properties

Property	Type	Required	Description
format	`Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>`	optional
create	`boolean`	✅
overwrite	`boolean`	✅
path	`string`	optional
prettify	`boolean`	optional
indent	`number`	optional
sortKeys	`boolean`	optional
backup	`boolean`	optional
atomic	`boolean`	optional
loader	`string`	optional	Specific loader to use (e.g. filesystem, database)

MetadataSaveResult

Properties

Property	Type	Required
success	`boolean`	✅
path	`string`	optional
stats	`Object`	optional
etag	`string`	optional
size	`number`	optional
saveTime	`number`	optional
backupPath	`string`	optional

MetadataScope

Allowed Values

system
platform
user

MetadataSource

Allowed Values

filesystem
database
api
migration

MetadataState

Allowed Values

draft
active
archived
deprecated

MetadataStats

Properties

Property	Type	Required
path	`string`	optional
size	`number`	optional
mtime	`string`	optional
hash	`string`	optional
etag	`string`	optional
modifiedAt	`string`	optional
format	`Enum<'json' \| 'yaml' \| 'yml' \| 'ts' \| 'js' \| 'typescript' \| 'javascript'>`	optional

MetadataWatchEvent

Properties

Property	Type	Required
type	`Enum<'add' \| 'change' \| 'unlink' \| 'added' \| 'changed' \| 'deleted'>`	✅
path	`string`	✅
name	`string`	optional
stats	`Object`	optional
metadataType	`string`	optional
data	`any`	optional
timestamp	`string`	optional

PackagePublishResult

Properties

Property	Type	Required	Description
success	`boolean`	✅	Whether the publish succeeded
packageId	`string`	✅	The package ID that was published
version	`integer`	✅	New version number after publish
publishedAt	`string`	✅	Publish timestamp
itemsPublished	`integer`	✅	Total metadata items published
validationErrors	`Object[]`	optional	Validation errors if publish failed

On this page