Metadata Persistence Metadata Persistence protocol schemas
Source: packages/spec/src/system/metadata-persistence.zod.ts
import { MetadataCollectionInfoSchema, MetadataDiffResultSchema, MetadataFallbackStrategySchema, MetadataFormatSchema, MetadataHistoryQueryOptionsSchema, MetadataHistoryQueryResultSchema, MetadataHistoryRecordSchema, MetadataHistoryRetentionPolicySchema, MetadataLoadOptionsSchema, MetadataLoadResultSchema, MetadataLoaderContractSchema, MetadataManagerConfigSchema, MetadataRecordSchema, MetadataSaveOptionsSchema, MetadataSaveResultSchema, MetadataScopeSchema, MetadataSourceSchema, MetadataStateSchema, MetadataStatsSchema, MetadataWatchEventSchema, PackagePublishResultSchema } from '@objectstack/spec/system' ; import type { MetadataCollectionInfo, MetadataDiffResult, MetadataFallbackStrategy, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataSource, MetadataState, MetadataStats, MetadataWatchEvent, PackagePublishResult } from '@objectstack/spec/system' ; // Validate data const result = MetadataCollectionInfoSchema. parse (data); Property Type Required Description type string✅ count number✅ namespaces string[]✅
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 stringoptional Human-readable summary of changes
Metadata file format
yamljsontypescriptjavascript
Property Type Required Description limit integeroptional Maximum number of history records to return offset integeroptional Number of records to skip since stringoptional Only return history after this timestamp until stringoptional Only return history before this timestamp operationType Enum<'create' | 'update' | 'publish' | 'revert' | 'delete'>optional Filter by operation type includeMetadata booleanoptional (default: true) Include full metadata payload
Property Type Required Description records { id: string; name: string; type: string; version: number; … }[]✅ total integer✅ hasMore boolean✅
Property Type Required Description id string✅ 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> | nulloptional Snapshot of metadata definition at this version (raw JSON string or parsed object) checksum string✅ SHA-256 checksum of metadata content previousChecksum stringoptional Checksum of the previous version changeNote stringoptional Description of changes made in this version organizationId stringoptional Organization identifier for multi-tenant isolation environmentId stringoptional Deprecated (ADR-0006 v4): legacy environment_id column. New writes leave unset. recordedBy stringoptional User who made this change recordedAt string✅ Timestamp when this version was recorded
Property Type Required Description id string✅ 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> | nulloptional Snapshot of metadata definition at this version (raw JSON string or parsed object) checksum string✅ SHA-256 checksum of metadata content previousChecksum stringoptional Checksum of the previous version changeNote stringoptional Description of changes made in this version organizationId stringoptional Organization identifier for multi-tenant isolation environmentId stringoptional Deprecated (ADR-0006 v4): legacy environment_id column. New writes leave unset. recordedBy stringoptional User who made this change recordedAt string✅ Timestamp when this version was recorded
Property Type Required Description maxVersions integeroptional Maximum number of versions to retain maxAgeDays integeroptional Maximum age of history records in days autoCleanup booleanoptional (default: false) Enable automatic cleanup of old history cleanupIntervalHours integeroptional (default: 24) How often to run cleanup (in hours)
Property Type Required Description scope Enum<'system' | 'platform' | 'user'>optional namespace stringoptional raw booleanoptional Return raw file content instead of parsed JSON cache booleanoptional useCache booleanoptional validate booleanoptional ifNoneMatch stringoptional recursive booleanoptional limit numberoptional patterns string[]optional loader stringoptional Specific loader to use (e.g. filesystem, database)
Property Type Required Description data any✅ stats { path?: string; size?: number; mtime?: string; hash?: string; … }optional format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format source stringoptional fromCache booleanoptional etag stringoptional notModified booleanoptional loadTime numberoptional
Property Type Required Description path stringoptional size numberoptional mtime stringoptional hash stringoptional etag stringoptional modifiedAt stringoptional format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format
Property Type Required Description name string✅ protocol Enum<'file:' | 'http:' | 's3:' | 'datasource:' | 'memory:'>✅ Loader protocol identifier description stringoptional supportedFormats string[]optional supportsWatch booleanoptional supportsWrite booleanoptional supportsCache booleanoptional capabilities { read: boolean; write: boolean; watch: boolean; list: boolean }✅
Property Type Required Description datasource stringoptional Datasource name reference for database persistence tableName stringoptional (default: "sys_metadata") Database table name for metadata storage fallback Enum<'filesystem' | 'memory' | 'none'>optional (default: "none") Fallback strategy when datasource is unavailable rootDir stringoptional 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 booleanoptional (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
Property Type Required Description enabled booleanoptional (default: true) Enable caching ttl integeroptional (default: 3600) Cache TTL in seconds maxSize integeroptional Max cache size in bytes databaseLoader { enabled: boolean; maxSize: integer; ttl: integer }optional DatabaseLoader read-through cache
Property Type Required Description ignored string[]optional Patterns to ignore persistent booleanoptional (default: true) Keep process running ignoreInitial booleanoptional (default: true) Ignore initial add events
Property Type Required Description strict booleanoptional (default: true) Strict validation throwOnError booleanoptional (default: true) Throw on validation error
Property Type Required Description writable booleanoptional (default: true) Allow base metadata writes via register() overlayWritable neveroptional [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.
Property Type Required Description id string✅ name string✅ type string✅ namespace stringoptional (default: "default") packageId stringoptional Package ID that owns/delivered this metadata managedBy Enum<'package' | 'platform' | 'user'>optional Who manages this metadata record lifecycle scope Enum<'system' | 'platform' | 'user'>optional (default: "platform") metadata Record<string, any>✅ extends stringoptional Name of the parent metadata to extend/override strategy Enum<'merge' | 'replace'>optional (default: "merge") owner stringoptional state Enum<'draft' | 'active' | 'archived' | 'deprecated'>optional (default: "active") organizationId stringoptional Organization identifier for multi-tenant isolation tenantId stringoptional Tenant identifier for multi-tenant isolation environmentId stringoptional Deprecated (ADR-0006 v4): legacy environment_id column. New code must use organization_id only. version numberoptional (default: 1) Record version for optimistic concurrency control checksum stringoptional 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 anyoptional Snapshot of the last published definition publishedAt stringoptional When this metadata was last published publishedBy stringoptional Who published this version createdBy stringoptional createdAt stringoptional Creation timestamp updatedBy stringoptional updatedAt stringoptional Last update timestamp
Property Type Required Description format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format create booleanoptional (default: true) overwrite booleanoptional (default: true) path stringoptional prettify booleanoptional indent numberoptional sortKeys booleanoptional backup booleanoptional atomic booleanoptional loader stringoptional Specific loader to use (e.g. filesystem, database)
Property Type Required Description success boolean✅ path stringoptional stats { path?: string; size?: number; mtime?: string; hash?: string; … }optional etag stringoptional size numberoptional saveTime numberoptional backupPath stringoptional
Property Type Required Description path stringoptional size numberoptional mtime stringoptional hash stringoptional etag stringoptional modifiedAt stringoptional format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format
filesystemdatabaseapimigration
draftactivearchiveddeprecated
Property Type Required Description path stringoptional size numberoptional mtime stringoptional hash stringoptional etag stringoptional modifiedAt stringoptional format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format
Property Type Required Description type Enum<'added' | 'changed' | 'deleted'>✅ path string✅ name stringoptional stats { path?: string; size?: number; mtime?: string; hash?: string; … }optional metadataType stringoptional data anyoptional timestamp stringoptional
Property Type Required Description path stringoptional size numberoptional mtime stringoptional hash stringoptional etag stringoptional modifiedAt stringoptional format Enum<'yaml' | 'json' | 'typescript' | 'javascript'>optional Metadata file format
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 { type: string; name: string; message: string }[]optional Validation errors if publish failed
Property Type Required Description type string✅ Metadata type that failed validation name string✅ Item name that failed validation message string✅ Validation error message
ObjectStack