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 { CompleteChunkedUploadRequestSchema, CompleteChunkedUploadResponseSchema, CompleteUploadRequestSchema, FileDownloadUrlResponseSchema, FileTypeValidationSchema, FileUploadResponseSchema, GetPresignedUrlRequestSchema, InitiateChunkedUploadRequestSchema, InitiateChunkedUploadResponseSchema, PresignedUrlResponseSchema, RawUploadResponseSchema, UploadChunkRequestSchema, UploadChunkResponseSchema, UploadProgressSchema } from '@objectstack/spec/api' ; import type { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileDownloadUrlResponse, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, RawUploadResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } from '@objectstack/spec/api' ; // Validate data const result = CompleteChunkedUploadRequestSchema. parse (data); Property Type Required Description uploadId string✅ Multipart upload session ID parts { chunkIndex: integer; eTag: string }[]✅ Ordered list of uploaded parts for assembly
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { fileId: string; key: string; size: integer; mimeType: string; … }✅
Property Type Required Description fileId string✅ File ID returned from presigned request eTag stringoptional S3 ETag verification
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { url: string }✅
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 integeroptional Maximum file size in bytes minFileSize integeroptional Minimum file size in bytes (e.g., reject empty files)
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { path: string; name: string; size: integer; mimeType: string; … }✅ 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 stringoptional 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 stringoptional 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 { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { uploadId: string; resumeToken: string; fileId: string; totalChunks: integer; … }✅
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { uploadUrl: string; downloadUrl?: string; fileId: string; method: Enum<'PUT' | 'POST'>; … }✅
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { key: string }✅
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 { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { chunkIndex: integer; eTag: string; bytesReceived: integer }✅
Property Type Required Description success boolean✅ Operation success status error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | … +266 more>; message: string; category?: string; httpStatus?: integer; … }optional Error details if success is false meta { timestamp: string; duration?: number; requestId?: string; traceId?: string }optional Response metadata data { uploadId: string; fileId: string; filename: string; totalSize: integer; … }✅
ObjectStack