メインコンテンツまでスキップ
バージョン: 0.6.0 (Latest)

🔍 File Storage Schema Blocks

File storage schema blocks 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 schema blocks 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​