Storage
Storage protocol schemas
Storage Service Protocol
Defines the API contract for client-side file operations.
Focuses on secure, direct-to-cloud uploads (Presigned URLs)
rather than proxying bytes through the API server.
Source: packages/spec/src/api/storage.zod.ts
import { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } from '@objectstack/spec/api';
import type { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } from '@objectstack/spec/api';
// Validate data
const result = CompleteChunkedUploadRequest.parse(data);
| Property | Type | Required | Description |
|---|
| uploadId | string | ✅ | Multipart upload session ID |
| parts | Object[] | ✅ | Ordered list of uploaded parts for assembly |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | |
| Property | Type | Required | Description |
|---|
| fileId | string | ✅ | File ID returned from presigned request |
| eTag | string | optional | S3 ETag verification |
| Property | Type | Required | Description |
|---|
| mode | Enum<'whitelist' | 'blacklist'> | ✅ | whitelist = only allow listed types, blacklist = block listed types |
| mimeTypes | string[] | ✅ | List of MIME types to allow or block (e.g., "image/jpeg", "application/pdf") |
| extensions | string[] | optional | List of file extensions to allow or block (e.g., ".jpg", ".pdf") |
| maxFileSize | integer | optional | Maximum file size in bytes |
| minFileSize | integer | optional | Minimum file size in bytes (e.g., reject empty files) |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | Uploaded file metadata |
| Property | Type | Required | Description |
|---|
| filename | string | ✅ | Original filename |
| mimeType | string | ✅ | File MIME type |
| size | number | ✅ | File size in bytes |
| scope | string | ✅ | Target storage scope (e.g. user, private, public) |
| bucket | string | optional | Specific bucket override (admin only) |
| Property | Type | Required | Description |
|---|
| filename | string | ✅ | Original filename |
| mimeType | string | ✅ | File MIME type |
| totalSize | integer | ✅ | Total file size in bytes |
| chunkSize | integer | ✅ | Size of each chunk in bytes (minimum 5MB per S3 spec) |
| scope | string | ✅ | Target storage scope |
| bucket | string | optional | Specific bucket override (admin only) |
| metadata | Record<string, string> | optional | Custom metadata key-value pairs |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | |
| Property | Type | Required | Description |
|---|
| uploadId | string | ✅ | Multipart upload session ID |
| chunkIndex | integer | ✅ | Zero-based chunk index |
| resumeToken | string | ✅ | Resume token from initiate response |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | |
| Property | Type | Required | Description |
|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| data | Object | ✅ | |
ObjectStack