Skip to content

metadata-persistence.mdx

Latest commit

 

History

History
409 lines (285 loc) · 12.5 KB

metadata-persistence.mdx

File metadata and controls

409 lines (285 loc) · 12.5 KB
Raw
title Metadata Persistence
description Metadata Persistence protocol schemas

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

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 Description
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 Description
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 Description
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 Description
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 Description
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 Description
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