メインコンテンツまでスキップ
バージョン: 🚧 Canary

🔍 File Storage Schemas

File storage schemas provide JSON Schema definitions for file management data validation in NodeBlocks applications. These schemas ensure data integrity and provide clear contracts for file storage-related API endpoints.

🎯 Overview​

File storage schemas are designed to:

  • Validate image upload requests with content type validation
  • Handle file size limits and constraints
  • Support multiple image formats with MIME type validation
  • Provide secure file operation contracts
  • Ensure proper response structure for signed URLs

📋 File Storage Schema Types​

Image Upload Schemas​

Schemas for image upload operations with content type and size validation.

Response Schemas​

Schemas for file storage operation responses with signed URLs.

🔧 Available File Storage Schemas​

getSignedImageUploadUrlSchema​

Image upload schema with required fields for uploading images.

Purpose: Validates image upload URL generation requests

Schema Details:

  • Type: OpenAPIOperation
  • Parameters: Query parameters for content type and file size
  • Response: Object with objectId and signedUrl
  • Content Types: Supported image MIME types only
  • File Size Limit: 10MB maximum

Query Parameters:

  • contentType: string (required) - A supported image MIME type
  • contentLength: integer (required) - The file size in bytes (max 10MB)

Supported Image MIME Types:

  • image/jpeg
  • image/png
  • image/webp
  • image/gif
  • image/svg+xml
  • image/avif
  • image/bmp
  • image/x-icon
  • image/tiff
  • image/heif
  • image/heic

Response Structure:

{
  objectId: string;    // Cloud Storage object path, e.g. 'bucket-name/object-key'
  signedUrl: string;   // Pre-signed URL to access the object
}

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { getSignedImageUploadUrlSchema } = schemas;

const imageUploadSchema = getSignedImageUploadUrlSchema({});
const validate = ajv.compile(imageUploadSchema.schemas as SchemaDefinition);
const isValid = validate({
  contentType: 'image/jpeg',
  contentLength: 1024000
});

Example Request:

GET /files/image/upload-url?contentType=image/jpeg&contentLength=1024000

Example Response:

{
  "objectId": "bucket-name/object-key",
  "signedUrl": "https://storage.googleapis.com/bucket-name/object-key?signature=..."
}

getSignedFileUploadUrlSchema​

File upload schema with content type and size validation for secure file uploads.

Purpose: Validates signed file upload URL generation requests with security checks

Schema Details:

  • Type: OpenAPIOperation
  • Parameters: Query parameters for content type and file size
  • Response: Object with objectId and signedUrl
  • Security: Excludes dangerous MIME types from allowed list
  • File Size Limit: 10MB maximum

Query Parameters:

  • contentType: string (required) - A supported MIME type from the mime-types library
  • contentLength: integer (required) - The file size in bytes (max 10MB)

MIME Type Validation:

  • Uses mime-types library enum for validation
  • Excludes dangerous file types that could be exploited
  • Supports a wide range of safe file formats

Dangerous MIME Types Excluded:

  • Executable files (.exe, .com, .bat, etc.)
  • Script files (.js, .vbs, .py, etc.)
  • Macro-enabled documents
  • Archives and compressed files
  • Other potentially harmful file types

Response Structure:

{
  objectId: string;    // Cloud Storage object name/key
  signedUrl: string;   // Pre-signed URL for file access
}

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { getSignedFileUploadUrlSchema } = schemas;

const fileUploadSchema = getSignedFileUploadUrlSchema({});
const validate = ajv.compile(fileUploadSchema.schemas as SchemaDefinition);
const isValid = validate({
  contentType: 'image/jpeg',
  contentLength: 1024000
});

Example Request:

GET /files/upload-url?contentType=image/jpeg&contentLength=1024000

Example Response:

{
  "objectId": "bucket-name/object-key.jpg",
  "signedUrl": "https://storage.googleapis.com/bucket-name/object-key.jpg?signature=..."
}

🔗 Related Documentation​