validating-json-data

z-schema による JSON データの検証

z-schema は、JSON Schema（draft-04、draft-06、draft-07、draft-2019-09、draft-2020-12）に照らして JSON データを検証します。デフォルトのドラフト：draft-2020-12。

クイックスタート

import ZSchema from 'z-schema';

const validator = ZSchema.create();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'integer', minimum: 0 },
  },
  required: ['name'],
};

// Throws on invalid data
validator.validate({ name: 'Alice', age: 30 }, schema);

インストール：npm install z-schema

検証モードの選択

z-schema には、async と safe の2つの切り替え設定に基づく4つのモードがあります。用途に合ったモードを選んでください。

モード	ファクトリー呼び出し	戻り値	使用する場面
同期・例外をスロー	ZSchema.create()	true または ValidateError をスロー	デフォルト — 単純なスクリプトやミドルウェア
同期・安全	ZSchema.create({ safe: true })	{ valid, err? }	try/catch を使わずにエラーを調べたい場合
非同期・例外をスロー	ZSchema.create({ async: true })	Promise<true> または reject	非同期フォーマットバリデーターを使用する場合
非同期・安全	ZSchema.create({ async: true, safe: true })	Promise<{ valid, err? }>	非同期かつ例外をスローしない場合

同期・例外をスロー（デフォルト）

import ZSchema from 'z-schema';

const validator = ZSchema.create();

try {
  validator.validate(data, schema);
} catch (err) {
  // err is ValidateError
  console.log(err.details); // SchemaErrorDetail[]
}

同期・安全

const validator = ZSchema.create({ safe: true });

const result = validator.validate(data, schema);
if (!result.valid) {
  console.log(result.err?.details);
}

または、通常の（例外をスローする）バリデーターで .validateSafe() を呼び出すと、同じ形式の結果を取得できます。

const validator = ZSchema.create();
const { valid, err } = validator.validateSafe(data, schema);

非同期・例外をスロー

非同期フォーマットバリデーターを使用する場合に必要です。

const validator = ZSchema.create({ async: true });

try {
  await validator.validate(data, schema);
} catch (err) {
  console.log(err.details);
}

非同期・安全

const validator = ZSchema.create({ async: true, safe: true });

const { valid, err } = await validator.validate(data, schema);

エラーの調査

ValidateError には、SchemaErrorDetail の配列である .details があります。

interface SchemaErrorDetail {
  message: string; // "Expected type string but found type number"
  code: string; // "INVALID_TYPE"
  params: (string | number | Array<string | number>)[];
  path: string | Array<string | number>; // "#/age" or ["age"]
  keyword?: string; // "type", "required", "minLength", etc.
  inner?: SchemaErrorDetail[]; // sub-errors from anyOf/oneOf/not
  schemaPath?: Array<string | number>;
  schemaId?: string;
}

例：ネストされたエラーをたどる

コンビネーター（anyOf、oneOf、not）は、ネストされた inner エラーを生成します。

const { valid, err } = validator.validateSafe(data, schema);
if (!valid && err) {
  for (const detail of err.details) {
    console.log(`${detail.path}: [${detail.code}] ${detail.message}`);
    if (detail.inner) {
      for (const sub of detail.inner) {
        console.log(`  └─ ${sub.path}: [${sub.code}] ${sub.message}`);
      }
    }
  }
}

エラーのフィルタリング

3番目の引数として ValidateOptions を渡すと、特定のエラーコードを含めたり除外したりできます。

// Only report type errors
validator.validate(data, schema, { includeErrors: ['INVALID_TYPE'] });

// Suppress string-length errors
validator.validate(data, schema, { excludeErrors: ['MIN_LENGTH', 'MAX_LENGTH'] });

エラーコードの一覧については、references/error-codes.md を参照してください。

スキーマの事前コンパイル

実行時のパフォーマンスを向上させ、相互参照を解決するには、起動時にスキーマをコンパイルします。

const validator = ZSchema.create();

const schemas = [
  {
    id: 'address',
    type: 'object',
    properties: { city: { type: 'string' }, zip: { type: 'string' } },
    required: ['city'],
  },
  {
    id: 'person',
    type: 'object',
    properties: {
      name: { type: 'string' },
      home: { $ref: 'address' },
    },
    required: ['name'],
  },
];

// Compile all schemas (validates them and registers references)
validator.validateSchema(schemas);

// Validate data using a compiled schema ID
validator.validate({ name: 'Alice', home: { city: 'Paris' } }, 'person');

リモート参照

手動登録

ZSchema.setRemoteReference('http://example.com/schemas/address.json', addressSchema);
// or per-instance:
validator.setRemoteReference('http://example.com/schemas/person.json', personSchema);

スキーマリーダーによる自動読み込み

import fs from 'node:fs';
import path from 'node:path';

ZSchema.setSchemaReader((uri) => {
  const filePath = path.resolve(__dirname, 'schemas', uri + '.json');
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
});

見つからない参照の診断

const { valid, err } = validator.validateSafe(data, schema);
if (!valid && err) {
  const missing = validator.getMissingReferences(err);
  const remote = validator.getMissingRemoteReferences(err);
}

カスタムフォーマットバリデーター

グローバル（すべてのバリデーターインスタンスで共有）

ZSchema.registerFormat('postal-code', (value) => {
  return typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value);
});

インスタンススコープ

const validator = ZSchema.create();
validator.registerFormat('postal-code', (value) => {
  return typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value);
});

作成時のオプションで指定

const validator = ZSchema.create({
  customFormats: {
    'postal-code': (value) => typeof value === 'string' && /^\d{5}(-\d{4})?$/.test(value),
  },
});

非同期フォーマットバリデーター

Promise<boolean> を返します。{ async: true } が必要です。

const validator = ZSchema.create({ async: true });
validator.registerFormat('user-exists', async (value) => {
  if (typeof value !== 'number') return false;
  const user = await db.findUser(value);
  return user != null;
});

登録済みフォーマットの一覧表示

const formats = ZSchema.getRegisteredFormats();

ドラフトバージョンの選択

スキーマが特定のバージョンを対象としている場合は、ドラフトを明示的に設定します。

const validator = ZSchema.create({ version: 'draft-07' });

有効な値：'draft-04'、'draft-06'、'draft-07'、'draft2019-09'、'draft2020-12'（デフォルト）、'none'。

各ドラフトの機能比較については、references/draft-comparison.md を参照してください。

よく使うオプション

オプション	デフォルト	目的
breakOnFirstError	false	最初のエラーで検証を停止する
noEmptyStrings	false	型が string の空文字列を拒否する
noEmptyArrays	false	型が array の空配列を拒否する
strictMode	false	すべての厳密チェックを一度に有効にする
ignoreUnknownFormats	false	不明なフォーマットのエラーを抑制する（最新のドラフトでは常に無視）
formatAssertions	null	null=常にアサート、true=語彙に従う、false=注釈のみ
reportPathAsArray	false	エラーパスを JSON Pointer 文字列ではなく配列として報告する

オプションの全項目については、references/options.md を参照してください。

サブスキーマの検証

スキーマ内の特定のパスを対象にします。

validator.validate(carData, fullSchema, { schemaPath: 'definitions.car' });

ブラウザーでの使用（UMD）

<script src="node_modules/z-schema/umd/ZSchema.min.js"></script>
<script>
  var validator = ZSchema.create();
  try {
    validator.validate({ name: 'test' }, { type: 'object' });
  } catch (err) {
    console.log(err.details);
  }
</script>

TypeScript の型

すべての型はパッケージからエクスポートされています。

import type {
  JsonSchema, // Schema type (all drafts union)
  ZSchemaOptions, // Configuration options
  ValidateOptions, // Per-call options (schemaPath, includeErrors, excludeErrors)
  ValidateResponse, // { valid: boolean, err?: ValidateError }
  SchemaErrorDetail, // Individual error detail
  ErrorCode, // Error code string literal type
  FormatValidatorFn, // (input: unknown) => boolean | Promise<boolean>
  SchemaReader, // (uri: string) => JsonSchema
} from 'z-schema';

import { ValidateError } from 'z-schema';

リファレンスファイル

• references/error-codes.md — 説明と使用例を含む、エラーコードの全一覧
• references/options.md — デフォルト値を含む、オプションの完全なリファレンス
• references/draft-comparison.md — JSON Schema の各ドラフト間の機能比較

重要な規約

• 常に ZSchema.create(options?) を使用してください。new ZSchema() は使用しないでください。ファクトリーは、正しい型のバリアントを返します。
• エラーの詳細は .details にあります（.errors ではありません）。
• 型は import type { ... } で、値は import { ValidateError } でインポートしてください。
• デフォルトのドラフトは draft2020-12 です。古いドラフトを対象とする場合は、明示的に指定してください。