バージョン: 0.14.0 (最新)

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

このガイドでは、既存の Nodeblocks スキーマをオーバーライドおよび拡張して、検証規則をカスタマイズしたり、新しいフィールドを追加したり、既存フィールドの制約を変更したりする方法を示します。組み込みの profileSchema を、カスタム検証規則と追加の必須フィールドで拡張します。SDK は JSON Schema draft-07 に対して AJV で検証するため、draft-07 のキーワードセット全体を withSchema 内で直接使用できます。

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

スキーマオーバーライドにより、次のことができます。

既存スキーマの拡張 - SDK の定義済みスキーマを基盤にする
カスタム検証の追加 - ドメイン固有の検証規則を実装する
フィールド制約の変更 - 最小／最大値、パターン、型を変更する
必須フィールドの制御 - 必要に応じてフィールドを必須または任意にする

1️⃣ 組み込みスキーマを理解する

Nodeblocks は一般的なエンティティ用の事前構築済みスキーマを提供します。profileSchema には標準プロフィールフィールドが含まれます。

// 組み込み profileSchema の構造
{
  $schema: 'http://json-schema.org/draft-07/schema#',
  type: 'object',
  additionalProperties: false,
  properties: {
    avatar: {
      oneOf: [avatarSchema, { type: 'null' }],
    },
    identityId: { type: 'string' },
    name: { type: 'string' },
  },
}

createProfileSchema はこれを基盤とし、identityId と name を必須にします。

Draft-07 サポート

SDK は AJV の draft-07 モードでスキーマをコンパイルするため、追加のアダプターレイヤーなしで draft-07 キーワードを使用できます。

使用できる代表的な draft-07 キーワードは次のとおりです。

allOf、anyOf、oneOf、not
if、then、else
const、enum
pattern、patternProperties
dependencies、contains
definitions、format、default

SDK は、対応するスキーマ分岐を走査しながら独自のオブジェクトデフォルトも適用します。

明示的にオーバーライドしない限り、オブジェクトスキーマには additionalProperties: false が適用されます。
MongoDB 形式のクエリフィルターを保護するため、オブジェクトスキーマには queryFilter: true が適用されます。

このデフォルト適用処理は、properties、allOf、oneOf、anyOf、配列の items を走査します。レガシーな withSchema(schemaA, schemaB) の使用では、SDK はコンパイル前に同じ型のスキーマを深くマージします。OpenAPI 形式の withSchema({ requestBody, parameters }) では、コンパイル前に指定されたスキーマをこれらのデフォルトで拡張します。

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

const {withSchema} = primitives;

export const accountSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          additionalProperties: false,
          if: {
            properties: {
              accountType: {const: 'organization'},
            },
            required: ['accountType'],
          },
          then: {
            required: ['organizationName'],
          },
          else: {
            not: {
              required: ['organizationName'],
            },
          },
          properties: {
            accountType: {enum: ['personal', 'organization']},
            organizationName: {type: 'string', minLength: 2},
          },
          required: ['accountType'],
          type: 'object',
        },
      },
    },
    required: true,
  },
});

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

カスタム検証で既存スキーマをオーバーライドする方法を示します。

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

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

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

次に、カスタムスキーマを既存ルートと合成できます。

import {primitives, routes} from '@nodeblocks/backend-sdk';
import {createCustomProfileSchema} from './schemas/customProfileSchema';

const {compose} = primitives;
const {createProfileRoute} = routes;

export const createCustomProfileFeature = compose(createCustomProfileSchema, createProfileRoute);

// features.createProfileFeature ではなく createCustomProfileFeature を使用

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

パターン 1: フィールドを追加する

// 新しい任意フィールドを追加
schema: {
  ...existingSchema,
  properties: {
    ...existingSchema.properties,
    newField: { type: 'string' }
  }
}

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

// 既存の任意フィールドを必須にする（常にマージし、置換しない）
schema: {
  ...existingSchema,
  required: [...(existingSchema.required || []), 'existingField']
}

パターン 3: フィールド制約をオーバーライドする

// より厳格な検証で既存フィールドをオーバーライド
properties: {
  ...existingSchema.properties,
  name: {
    ...existingSchema.properties.name,
    minLength: 2,
    maxLength: 80
  }
}

パターン 4: フィールドを削除する

// 分割代入でフィールドを削除し、required からも削除
const { unwantedField, ...allowedProperties } = existingSchema.properties;
const required = (existingSchema.required || []).filter(
  (field) => field !== 'unwantedField'
);

schema: {
  ...existingSchema,
  properties: allowedProperties,
  required,
}

➡️ 次のステップ

以下によりスキーマを拡張できます。

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

🔗 関連項目

複合サービスの作成 - カスタムスキーマで複数のサービスを結合
Profile サービス - プロフィールスキーマとエンドポイントのリファレンス
Schema コンポーネント - スキーマ合成を理解する
Service コンポーネント - サービスアーキテクチャを理解する
Feature コンポーネント - 機能合成を学ぶ
エラーハンドリング - 検証エラーを適切に処理する

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

1️⃣ 組み込みスキーマを理解する​

Draft-07 サポート​

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

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

パターン 1: フィールドを追加する​

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

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

パターン 4: フィールドを削除する​

➡️ 次のステップ​

🔗 関連項目​