---
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/. */}

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

## TypeScript Usage

```typescript
import { MetadataCollectionInfo, MetadataFormat, MetadataImportOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel';
import type { MetadataCollectionInfo, MetadataFormat, MetadataImportOptions, MetadataLoadResult, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/kernel';

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

---

## MetadataCollectionInfo

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | Collection type |
| **count** | `integer` | ✅ | Number of items |
| **formats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Formats in collection |
| **totalSize** | `integer` | optional | Total size in bytes |
| **lastModified** | `string` | optional | Last modification date |
| **location** | `string` | optional | Collection location |


---

## MetadataFormat

### Allowed Values

* `json`
* `yaml`
* `typescript`
* `javascript`


---

## MetadataImportOptions

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **conflictResolution** | `Enum<'skip' \| 'overwrite' \| 'merge' \| 'fail'>` | ✅ | How to handle existing items |
| **validate** | `boolean` | ✅ | Validate before import |
| **dryRun** | `boolean` | ✅ | Simulate import without saving |
| **continueOnError** | `boolean` | ✅ | Continue if validation fails |
| **transform** | `string` | optional | Transform items before import |


---

## MetadataLoadResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **data** | `any \| null` | ✅ | Loaded metadata |
| **fromCache** | `boolean` | ✅ | Loaded from cache |
| **notModified** | `boolean` | ✅ | Not modified since last request |
| **etag** | `string` | optional | Entity tag |
| **stats** | `Object` | optional | Metadata statistics |
| **loadTime** | `number` | optional | Load duration in ms |


---

## MetadataLoaderContract

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Loader identifier |
| **protocol** | `Enum<'file:' \| 'http:' \| 's3:' \| 'datasource:' \| 'memory:'>` | ✅ | Protocol identifier |
| **capabilities** | `Object` | ✅ | Loader capabilities |
| **supportedFormats** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>[]` | ✅ | Supported formats |
| **supportsWatch** | `boolean` | ✅ | Supports file watching |
| **supportsWrite** | `boolean` | ✅ | Supports write operations |
| **supportsCache** | `boolean` | ✅ | Supports caching |


---

## MetadataSaveOptions

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | ✅ | Output format |
| **prettify** | `boolean` | ✅ | Format with indentation |
| **indent** | `integer` | ✅ | Indentation spaces |
| **sortKeys** | `boolean` | ✅ | Sort object keys |
| **includeDefaults** | `boolean` | ✅ | Include default values |
| **backup** | `boolean` | ✅ | Create backup file |
| **overwrite** | `boolean` | ✅ | Overwrite existing file |
| **atomic** | `boolean` | ✅ | Use atomic write operation |
| **path** | `string` | optional | Custom output path |


---

## MetadataSaveResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Save successful |
| **path** | `string` | ✅ | Output path |
| **etag** | `string` | optional | Generated entity tag |
| **size** | `integer` | optional | File size |
| **saveTime** | `number` | optional | Save duration in ms |
| **backupPath** | `string` | optional | Backup file path |


---

## MetadataStats

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **size** | `integer` | ✅ | File size in bytes |
| **modifiedAt** | `string` | ✅ | Last modified date |
| **etag** | `string` | ✅ | Entity tag for cache validation |
| **format** | `Enum<'json' \| 'yaml' \| 'typescript' \| 'javascript'>` | ✅ | Serialization format |
| **path** | `string` | optional | File system path |
| **metadata** | `Record<string, any>` | optional | Provider-specific metadata |


---

## MetadataWatchEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'added' \| 'changed' \| 'deleted'>` | ✅ | Event type |
| **metadataType** | `string` | ✅ | Type of metadata |
| **name** | `string` | ✅ | Item identifier |
| **path** | `string` | ✅ | File path |
| **data** | `any` | optional | Item data |
| **timestamp** | `string` | ✅ | Event timestamp |


---

