ObjectStackObjectStack

Object Storage

Object Storage protocol schemas

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

Source: packages/spec/src/system/object-storage.zod.ts

TypeScript Usage

import { AccessControlConfigSchema, BucketConfigSchema, FileMetadataSchema, LifecycleActionSchema, LifecyclePolicyConfigSchema, LifecyclePolicyRuleSchema, MultipartUploadConfigSchema, ObjectMetadataSchema, ObjectStorageConfigSchema, PresignedUrlConfigSchema, StorageAclSchema, StorageClassSchema, StorageConnectionSchema, StorageProviderSchema, StorageScopeSchema } 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 = AccessControlConfigSchema.parse(data);

AccessControlConfig

Properties

PropertyTypeRequiredDescription
aclEnum<'private' | 'public_read' | 'public_read_write' | 'authenticated_read' | 'bucket_owner_read' | 'bucket_owner_full_control'>optional (default: "private")Default access control level
allowedOriginsstring[]optionalCORS allowed origins
allowedMethodsEnum<'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD'>[]optionalCORS allowed HTTP methods
allowedHeadersstring[]optionalCORS allowed headers
exposeHeadersstring[]optionalCORS exposed headers
maxAgenumberoptionalCORS preflight cache duration in seconds
corsEnabledbooleanoptional (default: false)Enable CORS configuration
publicAccess{ allowPublicRead: boolean; allowPublicWrite: boolean; allowPublicList: boolean }optionalPublic access control
allowedIpsstring[]optionalAllowed IP addresses/CIDR blocks
blockedIpsstring[]optionalBlocked IP addresses/CIDR blocks

Nested Shape: AccessControlConfig.publicAccess

PropertyTypeRequiredDescription
allowPublicReadbooleanoptional (default: false)Allow public read access
allowPublicWritebooleanoptional (default: false)Allow public write access
allowPublicListbooleanoptional (default: false)Allow public bucket listing

BucketConfig

Properties

PropertyTypeRequiredDescription
namestring✅Bucket identifier in ObjectStack (snake_case)
labelstring✅Display label
bucketNamestring✅Actual bucket/container name in storage provider
regionstringoptionalStorage region (e.g., us-east-1, westus)
providerEnum<'s3' | 'azure_blob' | 'gcs' | 'minio' | 'r2' | 'spaces' | 'wasabi' | 'backblaze' | 'local'>✅Storage provider
endpointstringoptionalCustom endpoint URL (for S3-compatible providers)
pathStylebooleanoptional (default: false)Use path-style URLs (for S3-compatible providers)
versioningbooleanoptional (default: false)Enable object versioning
encryption{ enabled: boolean; algorithm: Enum<'AES256' | 'aws:kms' | 'azure:kms' | 'gcp:kms'>; kmsKeyId?: string }optionalServer-side encryption configuration
accessControl{ acl: Enum<'private' | 'public_read' | 'public_read_write' | 'authenticated_read' | …>; allowedOrigins?: string[]; allowedMethods?: Enum<'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD'>[]; allowedHeaders?: string[]; … }optionalAccess control configuration
lifecyclePolicy{ enabled: boolean; rules: object[] }optionalLifecycle policy configuration
multipartConfig{ enabled: boolean; partSize: number; maxParts: number; threshold: number; … }optionalMultipart upload configuration
tagsRecord<string, string>optionalBucket tags for organization
descriptionstringoptionalBucket description
enabledbooleanoptional (default: true)Enable this bucket

Nested Shape: BucketConfig.encryption

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable server-side encryption
algorithmEnum<'AES256' | 'aws:kms' | 'azure:kms' | 'gcp:kms'>optional (default: "AES256")Encryption algorithm
kmsKeyIdstringoptionalKMS key ID for managed encryption

Nested Shape: BucketConfig.accessControl

PropertyTypeRequiredDescription
aclEnum<'private' | 'public_read' | 'public_read_write' | 'authenticated_read' | …>optional (default: "private")Default access control level
allowedOriginsstring[]optionalCORS allowed origins
allowedMethodsEnum<'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD'>[]optionalCORS allowed HTTP methods
allowedHeadersstring[]optionalCORS allowed headers
exposeHeadersstring[]optionalCORS exposed headers
maxAgenumberoptionalCORS preflight cache duration in seconds
corsEnabledbooleanoptional (default: false)Enable CORS configuration
publicAccess{ allowPublicRead: boolean; allowPublicWrite: boolean; allowPublicList: boolean }optionalPublic access control
allowedIpsstring[]optionalAllowed IP addresses/CIDR blocks
blockedIpsstring[]optionalBlocked IP addresses/CIDR blocks

Nested Shape: BucketConfig.lifecyclePolicy

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable lifecycle policies
rules{ id: string; enabled: boolean; action: Enum<'transition' | 'delete' | 'abort'>; prefix?: string; … }[]optional (default: [])Lifecycle rules

Nested Shape: BucketConfig.multipartConfig

PropertyTypeRequiredDescription
enabledbooleanoptional (default: true)Enable multipart uploads
partSizenumberoptional (default: 10485760)Part size in bytes (min 5MB, max 5GB)
maxPartsnumberoptional (default: 10000)Maximum number of parts (max 10,000)
thresholdnumberoptional (default: 104857600)File size threshold to trigger multipart upload (bytes)
maxConcurrentnumberoptional (default: 4)Maximum concurrent part uploads
abortIncompleteAfterDaysnumberoptionalAuto-abort incomplete uploads after N days

FileMetadata

Properties

PropertyTypeRequiredDescription
pathstring✅File path
namestring✅File name
sizeinteger✅File size in bytes
mimeTypestring✅MIME type
lastModifiedstring✅Last modified timestamp
createdstring✅Creation timestamp
etagstringoptionalEntity tag
fileIdstringoptionalOpaque sys_file id (ADR-0104 D3 file-as-reference)

LifecycleAction

Lifecycle policy action type

Allowed Values

  • transition
  • delete
  • abort

LifecyclePolicyConfig

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable lifecycle policies
rules{ id: string; enabled: boolean; action: Enum<'transition' | 'delete' | 'abort'>; prefix?: string; … }[]optional (default: [])Lifecycle rules

Nested Shape: LifecyclePolicyConfig.rules[number]

PropertyTypeRequiredDescription
idstring✅Rule identifier
enabledbooleanoptional (default: true)Enable this rule
actionEnum<'transition' | 'delete' | 'abort'>✅Action to perform
prefixstringoptionalObject key prefix filter (e.g., "uploads/")
tagsRecord<string, string>optionalObject tag filters
daysAfterCreationnumberoptionalDays after object creation
daysAfterModificationnumberoptionalDays after last modification
targetStorageClassEnum<'standard' | 'intelligent' | 'infrequent_access' | 'glacier' | 'deep_archive'>optionalTarget storage class for transition action

LifecyclePolicyRule

Properties

PropertyTypeRequiredDescription
idstring✅Rule identifier
enabledbooleanoptional (default: true)Enable this rule
actionEnum<'transition' | 'delete' | 'abort'>✅Action to perform
prefixstringoptionalObject key prefix filter (e.g., "uploads/")
tagsRecord<string, string>optionalObject tag filters
daysAfterCreationnumberoptionalDays after object creation
daysAfterModificationnumberoptionalDays after last modification
targetStorageClassEnum<'standard' | 'intelligent' | 'infrequent_access' | 'glacier' | 'deep_archive'>optionalTarget storage class for transition action

MultipartUploadConfig

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: true)Enable multipart uploads
partSizenumberoptional (default: 10485760)Part size in bytes (min 5MB, max 5GB)
maxPartsnumberoptional (default: 10000)Maximum number of parts (max 10,000)
thresholdnumberoptional (default: 104857600)File size threshold to trigger multipart upload (bytes)
maxConcurrentnumberoptional (default: 4)Maximum concurrent part uploads
abortIncompleteAfterDaysnumberoptionalAuto-abort incomplete uploads after N days

ObjectMetadata

Properties

PropertyTypeRequiredDescription
contentTypestring✅MIME type (e.g., image/jpeg, application/pdf)
contentLengthnumber✅File size in bytes
contentEncodingstringoptionalContent encoding (e.g., gzip)
contentDispositionstringoptionalContent disposition header
contentLanguagestringoptionalContent language
cacheControlstringoptionalCache control directives
etagstringoptionalEntity tag for versioning/caching
lastModifiedstringoptionalLast modification timestamp
versionIdstringoptionalObject version identifier
storageClassEnum<'standard' | 'intelligent' | 'infrequent_access' | 'glacier' | 'deep_archive'>optionalStorage class/tier
encryption{ algorithm: string; keyId?: string }optionalServer-side encryption configuration
customRecord<string, string>optionalCustom user-defined metadata

Nested Shape: ObjectMetadata.encryption

PropertyTypeRequiredDescription
algorithmstring✅Encryption algorithm (e.g., AES256, aws:kms)
keyIdstringoptionalKMS key ID if using managed encryption

ObjectStorageConfig

Properties

PropertyTypeRequiredDescription
namestring✅Storage configuration identifier
labelstring✅Display label
providerEnum<'s3' | 'azure_blob' | 'gcs' | 'minio' | 'r2' | 'spaces' | 'wasabi' | 'backblaze' | 'local'>✅Primary storage provider
scopeEnum<'global' | 'tenant' | 'user' | 'session' | 'temp' | 'cache' | 'data' | 'logs' | 'config' | 'public'>optional (default: "global")Storage scope
connection{ accessKeyId?: string; secretAccessKey?: string; sessionToken?: string; accountName?: string; … }✅Connection credentials
buckets{ name: string; label: string; bucketName: string; region?: string; … }[]optional (default: [])Configured buckets
defaultBucketstringoptionalDefault bucket name for operations
locationstringoptionalRoot path (local) or base location
quotaintegeroptionalMax size in bytes
optionsRecord<string, any>optionalProvider-specific configuration options
enabledbooleanoptional (default: true)Enable this storage configuration
descriptionstringoptionalConfiguration description

Nested Shape: ObjectStorageConfig.connection

PropertyTypeRequiredDescription
accessKeyIdstringoptionalAWS access key ID or MinIO access key
secretAccessKeystringoptionalAWS secret access key or MinIO secret key
sessionTokenstringoptionalAWS session token for temporary credentials
accountNamestringoptionalAzure storage account name
accountKeystringoptionalAzure storage account key
sasTokenstringoptionalAzure SAS token
environmentIdstringoptionalGCP project ID
credentialsstringoptionalGCP service account credentials JSON
endpointstringoptionalCustom endpoint URL
regionstringoptionalDefault region
useSSLbooleanoptional (default: true)Use SSL/TLS for connections
timeoutnumberoptionalConnection timeout in milliseconds

Nested Shape: ObjectStorageConfig.buckets[number]

PropertyTypeRequiredDescription
namestring✅Bucket identifier in ObjectStack (snake_case)
labelstring✅Display label
bucketNamestring✅Actual bucket/container name in storage provider
regionstringoptionalStorage region (e.g., us-east-1, westus)
providerEnum<'s3' | 'azure_blob' | 'gcs' | 'minio' | 'r2' | 'spaces' | 'wasabi' | 'backblaze' | 'local'>✅Storage provider
endpointstringoptionalCustom endpoint URL (for S3-compatible providers)
pathStylebooleanoptional (default: false)Use path-style URLs (for S3-compatible providers)
versioningbooleanoptional (default: false)Enable object versioning
encryption{ enabled: boolean; algorithm: Enum<'AES256' | 'aws:kms' | 'azure:kms' | 'gcp:kms'>; kmsKeyId?: string }optionalServer-side encryption configuration
accessControl{ acl: Enum<'private' | 'public_read' | 'public_read_write' | 'authenticated_read' | …>; allowedOrigins?: string[]; allowedMethods?: Enum<'GET' | 'PUT' | 'POST' | 'DELETE' | 'HEAD'>[]; allowedHeaders?: string[]; … }optionalAccess control configuration
lifecyclePolicy{ enabled: boolean; rules: object[] }optionalLifecycle policy configuration
multipartConfig{ enabled: boolean; partSize: number; maxParts: number; threshold: number; … }optionalMultipart upload configuration
tagsRecord<string, string>optionalBucket tags for organization
descriptionstringoptionalBucket description
enabledbooleanoptional (default: true)Enable this bucket

PresignedUrlConfig

Properties

PropertyTypeRequiredDescription
operationEnum<'get' | 'put' | 'delete' | 'head'>✅Allowed operation
expiresInnumber✅Expiration time in seconds (max 7 days)
contentTypestringoptionalRequired content type for PUT operations
maxSizenumberoptionalMaximum file size in bytes for PUT operations
responseContentTypestringoptionalOverride content-type for GET operations
responseContentDispositionstringoptionalOverride 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

PropertyTypeRequiredDescription
accessKeyIdstringoptionalAWS access key ID or MinIO access key
secretAccessKeystringoptionalAWS secret access key or MinIO secret key
sessionTokenstringoptionalAWS session token for temporary credentials
accountNamestringoptionalAzure storage account name
accountKeystringoptionalAzure storage account key
sasTokenstringoptionalAzure SAS token
environmentIdstringoptionalGCP project ID
credentialsstringoptionalGCP service account credentials JSON
endpointstringoptionalCustom endpoint URL
regionstringoptionalDefault region
useSSLbooleanoptional (default: true)Use SSL/TLS for connections
timeoutnumberoptionalConnection 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

On this page

TypeScript UsageAccessControlConfigPropertiesNested Shape: AccessControlConfig.publicAccessBucketConfigPropertiesNested Shape: BucketConfig.encryptionNested Shape: BucketConfig.accessControlNested Shape: BucketConfig.lifecyclePolicyNested Shape: BucketConfig.multipartConfigFileMetadataPropertiesLifecycleActionAllowed ValuesLifecyclePolicyConfigPropertiesNested Shape: LifecyclePolicyConfig.rules[number]LifecyclePolicyRulePropertiesMultipartUploadConfigPropertiesObjectMetadataPropertiesNested Shape: ObjectMetadata.encryptionObjectStorageConfigPropertiesNested Shape: ObjectStorageConfig.connectionNested Shape: ObjectStorageConfig.buckets[number]PresignedUrlConfigPropertiesStorageAclAllowed ValuesStorageClassAllowed ValuesStorageConnectionPropertiesStorageProviderAllowed ValuesStorageScopeAllowed Values