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

🎯 既存スキーマのオーバーライド

このガイドでは、既存の Nodeblocks スキーマをオーバーライドおよび拡張して、検証ルールをカスタマイズしたり、新しいフィールドを追加したり、既存のフィールド制約を変更したりする方法を説明します。組み込みの userSchema をカスタム検証ルールと追加の必須フィールドで拡張する方法を示します。

🏗️ スキーマオーバーライドアーキテクチャ​

スキーマオーバーライドにより、以下が可能になります：

  1. 既存スキーマの拡張 - SDK の事前定義されたスキーマを基に構築
  2. カスタム検証の追加 - ドメイン固有の検証ルールを実装
  3. フィールド制約の変更 - 最小値/最大値、パターン、または型を変更
  4. 必須フィールドの制御 - 必要に応じてフィールドを必須またはオプションにする

1️⃣ 組み込みスキーマの理解​

Nodeblocks は、一般的なエンティティ用の事前構築されたスキーマを提供します。userSchema には標準的なユーザーフィールドが含まれています：

// 組み込み userSchema の構造
{
  type: 'object',
  properties: {
    email: { type: 'string' },
    name: { type: 'string' },
    status: { type: 'string' }
    // ... その他の組み込みプロパティ
  },
  additionalProperties: false
}

2️⃣ 基本的なスキーマオーバーライド​

カスタム検証で既存のスキーマをオーバーライドする方法：

src/schemas/customUserSchema.ts
import {
  primitives,
  schemas,
} from '@nodeblocks/backend-sdk';

const { withSchema } = primitives;
const { userSchema } = schemas;

export const createUserSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          // 既存のスキーマを展開
          ...userSchema,
          properties: {
            // 既存のプロパティを展開
            ...userSchema.properties,
            // 新しいプロパティをオーバーライドまたは追加
            age: {
              type: 'number',
              minimum: 18,
              maximum: 100,
            }
          },
          // 既存の必須フィールドに加えて age を必須にする
          required: ['age'],
        },
      },
    },
    required: true,
  },
});

3️⃣ スキーマオーバーライドパターン​

パターン 1: フィールドの追加​

// 新しいオプションフィールドを追加
schema: {
  ...existingSchema,
  properties: {
    ...existingSchema.properties,
    newField: { type: 'string' }
  }
}

パターン 2: フィールドを必須にする​

// 既存のオプションフィールドを必須にする
schema: {
  ...existingSchema,
  required: [...(existingSchema.required || []), 'existingField']
}

パターン 3: フィールド制約のオーバーライド​

// より厳しい検証で既存のフィールドをオーバーライド
properties: {
  ...existingSchema.properties,
  email: {
    ...existingSchema.properties.email,
    pattern: '^[company-domain]@company\\.com$'
  }
}

パターン 4: フィールドの削除​

// 分割代入でフィールドを削除
const { unwantedField, ...allowedProperties } = existingSchema.properties;
schema: {
  ...existingSchema,
  properties: allowedProperties
}

➡️ 次のステップ​

スキーマを拡張できます：

  • カスタム検証ルールの追加 - ビジネス固有の制約を実装
  • 再利用可能なスキーマコンポーネントの作成 - 一般的なスキーマパターンのライブラリを構築
  • 複雑な検証の実装 - 条件付きスキーマとカスタムバリデーターを使用
  • スキーマ検証のテスト - オーバーライドの包括的なテストスイートを作成

🔗 関連ドキュメント​