YAML Schemaでenum制約を定義する

YAML Schemaのenum制約

enumキーワードはフィールドを事前定義された許可値のセットに制限します。JSONからYAML Schemaへの変換時、コンバーターは既知のパターンに一致するフィールドを識別し、enum制約を提案します。

JSON入力の例

{
  "environment": "production",
  "logLevel": "warn",
  "region": "us-east-1",
  "protocol": "https"
}

生成されるYAML Schema

type: object
properties:
  environment:
    type: string
    enum: [development, staging, production]
  logLevel:
    type: string
    enum: [trace, debug, info, warn, error, fatal]
  region:
    type: string
    enum:
      - us-east-1
      - us-west-2
      - eu-west-1
      - eu-central-1
      - ap-northeast-1
  protocol:
    type: string
    enum: [http, https]
required:
  - environment
  - logLevel
  - region

enum vs const

正確に1つの値でなければならないフィールドにはconstを使用します：

apiVersion:
  type: string
  const: "v2"

これはenum: ["v2"]と同等ですが、意図がより明確です。

デフォルト付きenum

logLevel:
  type: string
  enum: [trace, debug, info, warn, error, fatal]
  default: info

数値のenum

enumは文字列だけでなく、あらゆる型で動作します：

priority:
  type: integer
  enum: [1, 2, 3, 4, 5]
  description: "1=重大、5=低"

説明注釈付きenum

よりよいドキュメントのために、enumとdescriptionを組み合わせます：

environment:
  type: string
  enum: [development, staging, production]
  description: |
    デプロイ環境：
    - development: デバッグ機能付きのローカル開発
    - staging: 本番前のテスト環境
    - production: ユーザー向けのライブ環境

enumと他の制約の組み合わせ

region:
  type: string
  enum: [us-east-1, us-west-2, eu-west-1]
  pattern: "^[a-z]{2}-[a-z]+-\\d+$"

ここではpattern制約は冗長ですが、将来のenum追加時のフォーマットを文書化しています。

検証エラーメッセージ

値がenumに一致しない場合、バリデーターは以下を報告します：

Error: Value "staging2" is not one of the allowed values:
  development, staging, production
  at path '/environment'

enum vs patternの使い分け

• enum: 有効な値の完全なセットが既知で小さい場合（20項目未満）
• pattern: 値がフォーマットに従うが正確なセットが大きいか進化する場合
• 両方: フォーマットのドキュメントと固定リストの両方が必要な場合