YAML Schemaで必須フィールドを定義する

YAML Schemaの必須フィールド

YAML Schemaのrequiredキーワードは、有効なドキュメントに存在しなければならないプロパティ名を列挙します。JSONからの変換時、コンバーターは通常すべての存在するフィールドを必須としてマークし、その後実際の要件に基づいて調整します。

JSON入力の例

{
  "name": "web-api",
  "version": "2.0.0",
  "port": 3000,
  "host": "0.0.0.0",
  "debug": false,
  "logLevel": "info"
}

生成されるYAML Schema

type: object
properties:
  name:
    type: string
  version:
    type: string
  port:
    type: integer
  host:
    type: string
  debug:
    type: boolean
  logLevel:
    type: string
required:
  - name
  - version
  - port
additionalProperties: false

必須 vs オプションフィールド

生成後に、どのフィールドが本当に必須かを判断します：

フィールド	必須？	理由
name	はい	サービスを識別する
version	はい	互換性に必要
port	はい	ポートなしではサービスが起動できない
host	いいえ	デフォルトは0.0.0.0
debug	いいえ	デフォルトはfalse
logLevel	いいえ	デフォルトはinfo

additionalProperties

リストにないキーが許可されるかを制御します：

type: object
properties:
  name:
    type: string
additionalProperties: false    # propertiesにないキーを拒否

additionalProperties:
  type: string                  # 追加キーを許可するが、値はstringでなければならない

条件付き要件

特定の条件下でのみ必須となるフィールドにはif/thenを使用します：

properties:
  database:
    type: string
    enum: [postgres, mysql, sqlite]
  connectionString:
    type: string
  filePath:
    type: string
if:
  properties:
    database:
      const: sqlite
then:
  required:
    - filePath
else:
  required:
    - connectionString

ネストされた必須フィールド

各ネストされたオブジェクトには独自のrequired配列があります：

properties:
  server:
    type: object
    properties:
      host:
        type: string
      port:
        type: integer
    required:
      - port
required:
  - server

ここでは、serverオブジェクト自体が必須であり、その中のportは必須ですがhostはオプションです。

検証動作

必須フィールドが欠落している場合、バリデーターはフィールドパスを指定するエラーを返します：

Error: Required property 'port' is missing at path '/server'

この正確なエラー報告により、設定の問題を簡単に特定して修正できます。