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

📤 レスポンススキーマブロック

レスポンススキーマブロックは、Nodeblocksアプリケーション全体で標準化されたAPIレスポンス構造とエラー処理のためのJSONスキーマ定義を提供します。これらのスキーマは、一貫したレスポンスフォーマッティングとエラー報告を確保します。

🎯 概要​

レスポンススキーマブロックは以下を目的として設計されています：

  • すべてのエンドポイントでのAPIレスポンスの標準化
  • 一貫したエラー処理のためのエラーレスポンス構造の検証
  • 適切なデータフォーマッティングによる成功レスポンス一貫性の確保
  • エンティティ変更とユーザーアクションのための監査ログのサポート
  • エンティティ固有レスポンススキーマとのコンポジションの実現

📋 レスポンススキーマ種類​

エラーレスポンススキーマ​

標準化されたエラーレスポンス構造のためのスキーマ。

成功レスポンススキーマ​

標準化された成功レスポンス構造のためのスキーマ。

監査スキーマ​

監査ログとエンティティ変更追跡のためのスキーマ。

🔧 利用可能なレスポンススキーマ​

errorSchema​

標準化されたAPIエラーレスポンスのためのエラーレスポンススキーマ。

目的: APIエンドポイント全体でエラーレスポンス構造を検証

スキーマ詳細:

  • タイプ: object
  • 必須フィールド: code, message
  • 追加プロパティ: false（厳密な検証）
  • プロパティ:
    • code: string - エラーコード識別子
    • message: string - 人が読めるエラーメッセージ
    • details?: object - 追加のエラー詳細（オプション）

使用方法:

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

const { errorSchema } = schemas;

const validate = ajv.compile(errorSchema);
const isValid = validate({
  code: 'VALIDATION_ERROR',
  message: '無効な入力データです',
  details: { field: 'email', issue: '形式が無効です' }
});

successSchema​

標準化されたAPI成功レスポンスのための成功レスポンススキーマ。

目的: APIエンドポイント全体で成功レスポンス構造を検証

スキーマ詳細:

  • タイプ: object
  • 必須フィールド: message
  • 追加プロパティ: false（厳密な検証）
  • プロパティ:
    • message: string - 成功メッセージ
    • data?: object - レスポンスデータ（オプション）

使用方法:

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

const { successSchema } = schemas;

const validate = ajv.compile(successSchema);
const isValid = validate({
  message: 'ユーザーが正常に作成されました',
  data: { userId: '123', email: 'user@example.com' }
});

auditSchema​

エンティティ変更とユーザーアクション追跡のための監査ログスキーマ。

目的: システム変更の監査証跡レコードを検証

スキーマ詳細:

  • タイプ: object
  • 必須フィールド: id, entity_type, entity_id, action, user_id, created_at
  • 追加プロパティ: false（厳密な検証）
  • プロパティ:
    • id: string - 監査レコードID（UUIDフォーマット）
    • entity_type: string - 監査対象エンティティのタイプ
    • entity_id: string - 監査対象エンティティのID（UUIDフォーマット）
    • action: "create" | "update" | "delete" - 実行されたアクション
    • user_id: string - アクションを実行したユーザーのID（UUIDフォーマット）
    • created_at: string - アクションのタイムスタンプ（date-timeフォーマット）
    • changes?: object - 行われた変更を含むオブジェクト（オプション）

使用方法:

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

const { auditSchema } = schemas;

const validate = ajv.compile(auditSchema);
const isValid = validate({
  id: '550e8400-e29b-41d4-a716-446655440000',
  entity_type: 'user',
  entity_id: '550e8400-e29b-41d4-a716-446655440001',
  action: 'update',
  user_id: '550e8400-e29b-41d4-a716-446655440002',
  created_at: '2023-01-01T00:00:00Z',
  changes: { name: { from: 'John', to: 'Jane' } }
});

🔗 関連ドキュメント​