JSON Schema生成におけるboolean型とnull型

生成されたスキーマにおけるbooleanとnullの扱い

booleanとnullは最もシンプルなJSON型ですが、ほぼすべての実世界のスキーマに登場します。ジェネレーターがこれらをどのように処理するか、いつ調整が必要かを理解することが重要です。

booleanの生成

ジェネレーターが true または false を検出すると、次を出力します:

{ "isActive": { "type": "boolean" } }

これはリテラルのJSON値 true と false のみを受け入れます。文字列の "true" や "false"、数値の 0 や 1 はバリデーションに失敗します。

nullの生成

サンプルの null 値は次を生成します:

{ "deletedAt": { "type": "null" } }

しかし、null のみの型を持つフィールドは実用的ではありません。通常必要なのは nullable フィールド（主要な型またはnullを受け入れるフィールド）です。

フィールドをnullableにする

JSON Schemaはnullableフィールドに2つのアプローチをサポートしています:

型配列（Draft 2020-12で推奨）:

{
  "deletedAt": {
    "type": ["string", "null"],
    "format": "date-time"
  }
}

anyOf を使用:

{
  "deletedAt": {
    "anyOf": [
      { "type": "string", "format": "date-time" },
      { "type": "null" }
    ]
  }
}

ベストプラクティス

• フィールドが本当に値を持つべきでない場合を除き、type: "null" 単独での使用は避けてください。
• 明確性のために型配列構文を推奨します: ["string", "null"]。
• null がいつ期待されるかを消費者が分かるように、nullableフィールドに description でドキュメントを追加してください。