---
title: Object Storage
description: Object Storage protocol schemas
---

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

Object Storage Protocol

Unified storage protocol that combines:

- Object storage systems (S3, Azure Blob, GCS, MinIO)

- Scoped storage configuration (temp, cache, data, logs, config, public)

- Multi-cloud storage providers

- Bucket/container configuration

- Access control and permissions

- Lifecycle policies for data retention

- Presigned URLs for secure direct access

- Multipart uploads for large files

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

## TypeScript Usage

```typescript
import { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system';
import type { AccessControlConfig, BucketConfig, FileMetadata, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider, StorageScope } from '@objectstack/spec/system';

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

---

## AccessControlConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **acl** | `Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full_control'>` | ✅ | Default access control level |
| **allowedOrigins** | `string[]` | optional | CORS allowed origins |
| **allowedMethods** | `Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]` | optional | CORS allowed HTTP methods |
| **allowedHeaders** | `string[]` | optional | CORS allowed headers |
| **exposeHeaders** | `string[]` | optional | CORS exposed headers |
| **maxAge** | `number` | optional | CORS preflight cache duration in seconds |
| **corsEnabled** | `boolean` | ✅ | Enable CORS configuration |
| **publicAccess** | `Object` | optional | Public access control |
| **allowedIps** | `string[]` | optional | Allowed IP addresses/CIDR blocks |
| **blockedIps** | `string[]` | optional | Blocked IP addresses/CIDR blocks |


---

## BucketConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Bucket identifier in ObjectStack (snake_case) |
| **label** | `string` | ✅ | Display label |
| **bucketName** | `string` | ✅ | Actual bucket/container name in storage provider |
| **region** | `string` | optional | Storage region (e.g., us-east-1, westus) |
| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Storage provider |
| **endpoint** | `string` | optional | Custom endpoint URL (for S3-compatible providers) |
| **pathStyle** | `boolean` | ✅ | Use path-style URLs (for S3-compatible providers) |
| **versioning** | `boolean` | ✅ | Enable object versioning |
| **encryption** | `Object` | optional | Server-side encryption configuration |
| **accessControl** | `Object` | optional | Access control configuration |
| **lifecyclePolicy** | `Object` | optional | Lifecycle policy configuration |
| **multipartConfig** | `Object` | optional | Multipart upload configuration |
| **tags** | `Record<string, string>` | optional | Bucket tags for organization |
| **description** | `string` | optional | Bucket description |
| **enabled** | `boolean` | ✅ | Enable this bucket |


---

## FileMetadata

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **path** | `string` | ✅ | File path |
| **name** | `string` | ✅ | File name |
| **size** | `integer` | ✅ | File size in bytes |
| **mimeType** | `string` | ✅ | MIME type |
| **lastModified** | `string` | ✅ | Last modified timestamp |
| **created** | `string` | ✅ | Creation timestamp |
| **etag** | `string` | optional | Entity tag |


---

## LifecycleAction

Lifecycle policy action type

### Allowed Values

* `transition`
* `delete`
* `abort`


---

## LifecyclePolicyConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable lifecycle policies |
| **rules** | `Object[]` | ✅ | Lifecycle rules |


---

## LifecyclePolicyRule

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Rule identifier |
| **enabled** | `boolean` | ✅ | Enable this rule |
| **action** | `Enum<'transition' \| 'delete' \| 'abort'>` | ✅ | Action to perform |
| **prefix** | `string` | optional | Object key prefix filter (e.g., "uploads/") |
| **tags** | `Record<string, string>` | optional | Object tag filters |
| **daysAfterCreation** | `number` | optional | Days after object creation |
| **daysAfterModification** | `number` | optional | Days after last modification |
| **targetStorageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Target storage class for transition action |


---

## MultipartUploadConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable multipart uploads |
| **partSize** | `number` | ✅ | Part size in bytes (min 5MB, max 5GB) |
| **maxParts** | `number` | ✅ | Maximum number of parts (max 10,000) |
| **threshold** | `number` | ✅ | File size threshold to trigger multipart upload (bytes) |
| **maxConcurrent** | `number` | ✅ | Maximum concurrent part uploads |
| **abortIncompleteAfterDays** | `number` | optional | Auto-abort incomplete uploads after N days |


---

## ObjectMetadata

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **contentType** | `string` | ✅ | MIME type (e.g., image/jpeg, application/pdf) |
| **contentLength** | `number` | ✅ | File size in bytes |
| **contentEncoding** | `string` | optional | Content encoding (e.g., gzip) |
| **contentDisposition** | `string` | optional | Content disposition header |
| **contentLanguage** | `string` | optional | Content language |
| **cacheControl** | `string` | optional | Cache control directives |
| **etag** | `string` | optional | Entity tag for versioning/caching |
| **lastModified** | `string` | optional | Last modification timestamp |
| **versionId** | `string` | optional | Object version identifier |
| **storageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Storage class/tier |
| **encryption** | `Object` | optional | Server-side encryption configuration |
| **custom** | `Record<string, string>` | optional | Custom user-defined metadata |


---

## ObjectStorageConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Storage configuration identifier |
| **label** | `string` | ✅ | Display label |
| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Primary storage provider |
| **scope** | `Enum<'global' \| 'tenant' \| 'user' \| 'session' \| 'temp' \| 'cache' \| 'data' \| 'logs' \| 'config' \| 'public'>` | ✅ | Storage scope |
| **connection** | `Object` | ✅ | Connection credentials |
| **buckets** | `Object[]` | ✅ | Configured buckets |
| **defaultBucket** | `string` | optional | Default bucket name for operations |
| **location** | `string` | optional | Root path (local) or base location |
| **quota** | `integer` | optional | Max size in bytes |
| **options** | `Record<string, any>` | optional | Provider-specific configuration options |
| **enabled** | `boolean` | ✅ | Enable this storage configuration |
| **description** | `string` | optional | Configuration description |


---

## PresignedUrlConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **operation** | `Enum<'get' \| 'put' \| 'delete' \| 'head'>` | ✅ | Allowed operation |
| **expiresIn** | `number` | ✅ | Expiration time in seconds (max 7 days) |
| **contentType** | `string` | optional | Required content type for PUT operations |
| **maxSize** | `number` | optional | Maximum file size in bytes for PUT operations |
| **responseContentType** | `string` | optional | Override content-type for GET operations |
| **responseContentDisposition** | `string` | optional | Override content-disposition for GET operations |


---

## StorageAcl

Storage access control level

### Allowed Values

* `private`
* `public_read`
* `public_read_write`
* `authenticated_read`
* `bucket_owner_read`
* `bucket_owner_full_control`


---

## StorageClass

Storage class/tier for cost optimization

### Allowed Values

* `standard`
* `intelligent`
* `infrequent_access`
* `glacier`
* `deep_archive`


---

## StorageConnection

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **accessKeyId** | `string` | optional | AWS access key ID or MinIO access key |
| **secretAccessKey** | `string` | optional | AWS secret access key or MinIO secret key |
| **sessionToken** | `string` | optional | AWS session token for temporary credentials |
| **accountName** | `string` | optional | Azure storage account name |
| **accountKey** | `string` | optional | Azure storage account key |
| **sasToken** | `string` | optional | Azure SAS token |
| **environmentId** | `string` | optional | GCP project ID |
| **credentials** | `string` | optional | GCP service account credentials JSON |
| **endpoint** | `string` | optional | Custom endpoint URL |
| **region** | `string` | optional | Default region |
| **useSSL** | `boolean` | ✅ | Use SSL/TLS for connections |
| **timeout** | `number` | optional | Connection timeout in milliseconds |


---

## StorageProvider

Storage provider type

### Allowed Values

* `s3`
* `azure_blob`
* `gcs`
* `minio`
* `r2`
* `spaces`
* `wasabi`
* `backblaze`
* `local`


---

## StorageScope

Storage scope classification

### Allowed Values

* `global`
* `tenant`
* `user`
* `session`
* `temp`
* `cache`
* `data`
* `logs`
* `config`
* `public`


---

