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

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

## TypeScript Usage

```typescript
import { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataRecord, MetadataSaveOptions, MetadataSaveResult, MetadataScope, MetadataSource, MetadataState, MetadataStats, MetadataWatchEvent, PackagePublishResult } from '@objectstack/spec/system';
import type { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, 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'>` | ✅ |  |


---

## 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` | ✅ |  |
| **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 |
| **organizationId** | `string` | optional | Organization identifier for multi-tenant isolation |
| **environmentId** | `string` | optional | Deprecated (ADR-0006 v4): legacy environment_id column. New writes leave unset. |
| **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` | ✅ |  |


---

## 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'>` | ✅ |  |
| **organizationId** | `string` | optional | Organization identifier for multi-tenant isolation |
| **tenantId** | `string` | optional | Tenant identifier for multi-tenant isolation |
| **environmentId** | `string` | optional | Deprecated (ADR-0006 v4): legacy environment_id column. New code must use organization_id only. |
| **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 |


---

