PART 04 — 構造設計とJSON Schema
ネスト設計の指針と検証自動化

レビューのたびに「このプロパティは必須にすべきでは」「この値は0以上のはず」という指摘を繰り返しているうちに、それは人間がその都度目視で確認することではなく、スキーマとして一度書いてしまえば機械が永遠にチェックし続けてくれる類のルールだと気づきました。この記事は、その気づきをJSON Schemaという形にまとめたものです。

配列 vs キー付きオブジェクト — どちらを選ぶか

複数の要素を持つデータを表現する際、配列（array）にするかキーで引けるオブジェクト（object）にするかは、設計の初期段階でよく迷うポイントです。

正規化と冗長性のトレードオフ

リレーショナルDBの正規化の考え方と同様に、JSONでも「同じ情報を複数箇所に重複させるか、参照（ID）で1箇所にまとめるか」という判断が発生します。

API レスポンスのように「読み取り専用で、クライアント側の処理を単純にしたい」用途では非正規化（埋め込み）が好まれる傾向があり、設定ファイルやマスタデータのように「更新の一貫性」が重要な用途では正規化（参照）が好まれます。用途に応じて意図的に選択することが重要です。

JSON Schema とは

図1: データとスキーマをバリデータに渡すことで、構造・型が仕様どおりかを機械的に判定できる

JSON Schemaは、JSONデータの構造・型・必須項目・値の範囲などをJSON自体で記述する仕様です。「このデータはこういう形であるべき」という契約をコードとして定義し、レビューではなくツールに検証させられるのが最大の利点です。

スキーマの実装例

PART 03で扱ったメンバー情報のJSONに対して、実際にJSON Schemaを定義してみます。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Project",
  "type": "object",
  "required": ["project", "members"],
  "properties": {
    "project": { "type": "string", "minLength": 1 },
    "members": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["name", "role"],
        "properties": {
          "name": { "type": "string" },
          "role": { "type": "string", "enum": ["Engineer", "Reviewer", "PM"] },
          "age":  { "type": "integer", "minimum": 0, "maximum": 120 }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

ajv による検証自動化

ajvはNode.js製の高速なJSON Schemaバリデータです。CLI版のajv-cliを使えば、コマンド一発でデータとスキーマの整合性をチェックできます。

# ajv-cli のインストール
npm install -g ajv-cli ajv-formats

# データをスキーマに対して検証
ajv validate -s member.schema.json -d project.json

# 検証成功時の出力
# project.json valid

# 検証失敗時の出力例
# project.json invalid
# data/members/0 must have required property 'role'

まとめ

構造設計の判断基準とJSON Schemaによる検証を組み合わせることで、「なんとなく良さそうな形」で終わらせず、レビューで指摘していた項目の多くを機械的なチェックに置き換えられます。