YAML Schemaでデフォルト値を指定する

YAML Schemaのデフォルト値

YAML Schemaのdefaultキーワードは、プロパティがドキュメントに存在しない場合に使用する値を指定します。これはJSON Schema仕様では純粋に情報的ですが、多くのツールやバリデーターが欠落値の自動補完に使用します。

JSON入力の例

{
  "host": "0.0.0.0",
  "port": 3000,
  "workers": 4,
  "logLevel": "info",
  "gracefulShutdown": true,
  "shutdownTimeout": 30
}

デフォルト値付きの生成されるYAML Schema

type: object
properties:
  host:
    type: string
    default: "0.0.0.0"
  port:
    type: integer
    default: 3000
    minimum: 1
    maximum: 65535
  workers:
    type: integer
    default: 4
    minimum: 1
  logLevel:
    type: string
    default: info
    enum: [trace, debug, info, warn, error, fatal]
  gracefulShutdown:
    type: boolean
    default: true
  shutdownTimeout:
    type: integer
    default: 30
    minimum: 1
    description: プロセスを強制終了するまでの待機秒数
required:
  - host
  - port

デフォルトとrequiredの関係

これら2つの概念は重要な相互作用があります：

組み合わせ	動作
required + デフォルトなし	フィールドが存在しなければエラー
required + デフォルトあり	フィールドが存在しなければエラー；デフォルトは情報的
optional + デフォルトあり	フィールドは不在可；ツールがデフォルトを注入する場合あり
optional + デフォルトなし	フィールドは不在可；フォールバックなし

スキーマ対応の設定マージ

多くのツールは検証前にスキーマからデフォルトをマージします：

# ユーザー提供（最小設定）：
port: 9090

# スキーマ対応マージ後：
host: "0.0.0.0"     # デフォルト適用
port: 9090           # ユーザー値保持
workers: 4           # デフォルト適用
logLevel: info       # デフォルト適用
gracefulShutdown: true  # デフォルト適用
shutdownTimeout: 30    # デフォルト適用

ネストされたオブジェクトのデフォルト

properties:
  logging:
    type: object
    default:
      level: info
      format: json
    properties:
      level:
        type: string
        default: info
      format:
        type: string
        default: json

オブジェクト自体とその個々のプロパティの両方にデフォルトを設定できることに注意してください。

ツールサポート

ツール	デフォルト使用？
ajv（useDefaultsオプション）	はい
yq	いいえ（検証のみ）
pykwalify	はい
Kubernetes admission controllers	Webhookに依存
Helm	はい（values.yaml）

ベストプラクティス

1. オプションフィールドには常にデフォルトを提供 -- スキーマを自己文書化する
2. 現実的な値を使用 -- デフォルトはプレースホルダーではなく本番環境で安全な値であるべき
3. デフォルト動作を文書化 -- デフォルトの選択理由を説明するdescriptionを追加
4. デフォルトのみの設定をテスト -- 必須フィールドのみでサービスが正しく起動することを確認