migrating-json-schemas

JSON Schema のドラフト間移行

z-schema は draft-04、draft-06、draft-07、draft-2019-09、draft-2020-12 をサポートしています。このスキルでは、ドラフト間でスキーマを移行し、z-schema で検証する方法を説明します。

移行ワークフロー

1. 移行元のドラフトを特定します（$schema または id／$id の使用状況を確認します）。
2. バリデーターに対象バージョンを設定します。

   import ZSchema from 'z-schema';
   const validator = ZSchema.create({ version: 'draft2020-12' });
   

3. validator.validateSchema(schema) を実行して、互換性の問題を検出します。
4. 以下のキーワード対応表を使って、報告されたエラーをそれぞれ修正します。
5. スキーマが検証に合格するまで再検証します。

クイックリファレンス：キーワードの変更

旧キーワード（draft-04）	新キーワード（draft-2020-12）	導入されたドラフト
id	$id	draft-06
definitions	$defs	draft-2019-09
配列形式の items（タプル）	prefixItems	draft-2020-12
additionalItems	items（prefixItems がある場合）	draft-2020-12
exclusiveMinimum: true（ブール値）	exclusiveMinimum: <number>	draft-06
exclusiveMaximum: true（ブール値）	exclusiveMaximum: <number>	draft-06
dependencies（文字列配列）	dependentRequired	draft-2019-09
dependencies（スキーマ値）	dependentSchemas	draft-2019-09
$recursiveRef / $recursiveAnchor	$dynamicRef / $dynamicAnchor	draft-2020-12

例を含むキーワードの完全な対応表については、references/keyword-mapping.md を参照してください。

よくある移行パス

Draft-04 → Draft-2020-12

最も大きな変更を伴う移行です。次の順序で変更を適用します。

1. id を $id に変更する

// Before (draft-04)
{ "id": "http://example.com/person.json", "type": "object" }

// After (draft-2020-12)
{ "$id": "http://example.com/person.json", "type": "object" }

2. ブール値の exclusiveMinimum／exclusiveMaximum を数値に変換する

// Before (draft-04)
{ "type": "number", "minimum": 0, "exclusiveMinimum": true }

// After (draft-2020-12)
{ "type": "number", "exclusiveMinimum": 0 }

注：exclusiveMinimum を数値に変換する際は、minimum キーワードを削除します。exclusiveMinimum: 0 は「0 より大きい」を意味するためです。

3. definitions を $defs に変更する

// Before
{ "definitions": { "address": { "type": "object" } } }

// After
{ "$defs": { "address": { "type": "object" } } }

#/definitions/... を参照するすべての $ref の値を #/$defs/... に更新します。

4. dependencies を分割する

// Before (draft-04) — mixed dependencies
{
  "dependencies": {
    "billing_address": ["credit_card"],
    "credit_card": { "type": "object", "properties": { "cvv": { "type": "string" } } }
  }
}

// After (draft-2020-12) — split into two keywords
{
  "dependentRequired": {
    "billing_address": ["credit_card"]
  },
  "dependentSchemas": {
    "credit_card": { "type": "object", "properties": { "cvv": { "type": "string" } } }
  }
}

5. タプル形式の items を prefixItems に変換する

// Before (draft-04)
{
  "type": "array",
  "items": [{ "type": "string" }, { "type": "number" }],
  "additionalItems": false
}

// After (draft-2020-12)
{
  "type": "array",
  "prefixItems": [{ "type": "string" }, { "type": "number" }],
  "items": false
}

items が配列（タプル検証）だった場合は、prefixItems に変換します。以前の additionalItems は items になります。

6. $schema 宣言を追加する

{ "$schema": "https://json-schema.org/draft/2020-12/schema" }

Draft-07 → Draft-2020-12

変更は比較的少なめです。主な変更点は次のとおりです。

1. definitions → $defs（および $ref のパスを更新）
2. 配列形式の items → prefixItems
3. additionalItems → items（prefixItems がある場合）
4. dependencies → dependentRequired／dependentSchemas
5. 組み合わせたスキーマをより厳密に検証するため、unevaluatedProperties／unevaluatedItems の採用を検討する

Draft-2019-09 → Draft-2020-12

変更は最小限です。

1. 配列形式の items → prefixItems、additionalItems → items
2. $recursiveRef／$recursiveAnchor → $dynamicRef／$dynamicAnchor

移行後のスキーマの検証

移行後、対象ドラフトのメタスキーマに対してスキーマ自体を検証します。

import ZSchema from 'z-schema';

const validator = ZSchema.create({ version: 'draft2020-12' });

try {
  validator.validateSchema(migratedSchema);
  console.log('Schema is valid for draft-2020-12');
} catch (err) {
  console.log('Schema issues:', err.details);
}

次に、データ検証をテストして、動作が変わっていないことを確認します。

// Test with known-good data
validator.validate(knownGoodData, migratedSchema);

// Test with known-bad data
const { valid } = validator.validateSafe(knownBadData, migratedSchema);
if (valid) {
  console.warn('Migration issue: previously invalid data now passes');
}

下位互換性

複数のドラフトバージョンでスキーマを動作させる必要がある場合は、version: 'none' を使用し、各スキーマに $schema を設定して、それぞれのドラフトを宣言します。

const validator = ZSchema.create({ version: 'none' });

参考ファイル

• references/keyword-mapping.md — すべてのドラフトにわたるキーワードの完全な対応表と変更前後の例