メインコンテンツまでスキップ
バージョン: 0.9.0 (最新)

📤 レスポンススキーマ

レスポンススキーマは、Nodeblocksアプリケーション全体で標準化されたAPIレスポンス構造とエラーハンドリング用のJSONスキーマ定義を提供します。これらのスキーマは、一貫したレスポンスフォーマットとエラー報告を保証します。

🎯 概要​

レスポンススキーマは以下の目的で設計されています：

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

📋 レスポンススキーマタイプ​

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

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

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

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

監査スキーマ​

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

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

errorSchema​

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

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

スキーマ詳細:

  • Type: object
  • Required Fields: code, message
  • Additional Properties: false（厳密な検証）
  • Properties:
    • code: string - エラーコード識別子
    • message: string - 人間が読めるエラーメッセージ
    • details?: object - 追加のエラー詳細（オプション）

使用例:

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

const { errorSchema } = schemas;
const validate = ajv.compile(errorSchema.schemas as SchemaDefinition);
const isValid = validate({
  code: 'VALIDATION_ERROR',
  message: 'Invalid input data',
  details: { field: 'email', issue: 'Invalid format' }
});

successSchema​

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

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

スキーマ詳細:

  • Type: object
  • Required Fields: message
  • Additional Properties: false（厳密な検証）
  • Properties:
    • message: string - 成功メッセージ
    • data?: object - レスポンスデータ（オプション）

使用例:

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

const { successSchema } = schemas;
const validate = ajv.compile(successSchema.schemas as SchemaDefinition);
const isValid = validate({
  message: 'User created successfully',
  data: { identityId: '123', email: 'user@example.com' }
});

auditSchema​

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

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

スキーマ詳細:

  • Type: object
  • Required Fields: id, entity_type, entity_id, action, user_id, created_at
  • Additional Properties: false（厳密な検証）
  • Properties:
    • 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.schemas as SchemaDefinition);
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' } }
});