JSON Toolkit

JSON SchemaでYAMLを検証する:設定ファイルの型の防波堤

要点:YAMLのパースが通っても、値が正しい保証はありません。country: NO は YAML 1.1 パーサーでは文字列ですらなく、version: 1.10 は黙って浮動小数点 1.1 になります。本ガイドでは、JSON Schema がなぜ YAML を検証できるのか、CLI とエディターの2つの実装経路、ノルウェー国コード事故をスキーマで事前に防ぐ方法、そしてスキーマ検証ができない3つのことを解説します。

中級約 6 分で読めます2026-11-13 公開2026-11-13 更新
JSON SchemaでYAML設定ファイルを検証する型の防波堤の概念図

結論:YAML 1.2 は JSON の厳密なスーパーセットです。つまり JSON Schema が検証するのはパース後のデータ構造であって、ファイル形式ではありません。スキーマは一度書けば JSON と YAML の両方に使え、これこそが「パーサーが黙って型を変える」事故を防げる理由です。

yaml.safe_load がエラーを出さないことは、そのファイルが合法的な YAML であることの証明にすぎません。country: NO がまだ文字列であることの証明にはなりません。YAML 1.1 パーサーでは、あなたのコードが触る前から false になっています。

一、パースが通る ≠ 設定が正しい:まず実際の事故から

あるECチームはノルウェーを配送対象国に追加しました。Ansible の group_vars のリストに NO の1行を足し、レビューを通してリリース。1週間後、ノルウェーからの注文はゼロ——サーバー上の JSON ファイルには "DK", false, "SE" が書かれていました。Ansible は変数ファイルを PyYAML(YAML 1.1 パーサー)で読むため、NO はファイルから読み込まれた瞬間にブール値 false になっており、to_json フィルターはそれを忠実に出力したのです。テンプレートは正常にレンダリングされ、JSON は合法、エラーは一切出ません。ただ checkout サービスが NO not in list でノルウェーの顧客を一人ずつ拒否し続けていただけです。

この種の事故に共通するのは、構文レベルのツールはすべて緑なのに、データ層ではすでに間違っていることです。次の表は PyYAML 6.0.3 で実測した型の変質です。YAML 1.2 パーサーでも一部しか修正されません:

書いた値 YAML 1.1 の読み取り YAML 1.2 の読み取り 意図した値
country: NO false "NO" "NO"
version: 1.10 浮動小数点 1.1 浮動小数点 1.1 "1.10"
zip: 02134 8進数 1116 10進数 2134 "02134"
mode: 0755 10進数 493 10進数 755 493 または "0755"
ports: ["22:22"] 60進数 1342 "22:22" "22:22"

根本的な対策は、コード的な文字列はすべて引用符で囲むこと。しかし引用符は人間の記憶に頼り、スキーマは機械が検査します。だからこそ YAML には JSON Schema を用意すべきなのです。

二、なぜ JSON Schema が YAML を管理できるのか

YAML 1.2 仕様は明言しています。1.2 の第一の目標は YAML を JSON の厳密なスーパーセットにすることであり、1.2 パーサーは通常の JSON をそのまま読めます。両形式はパース後に同じデータ構造になるため、バリデーターにとって拡張子は無意味です。パイプラインは3ステップだけです:

  1. YAML ファイルをパースしてオブジェクト/配列を得る;
  2. JSON Schema をロードする;
  3. スキーマでデータを検証し、エラーを出すか通過させる。

ステップ1で YAML を JSON テキストにシリアライズして再度パースする必要はありません。どの言語の YAML ライブラリも、データ構造を直接バリデーターに渡せます。スキーマ自体を YAML で書くこともできます(yq -P schema.json > schema.yaml の1コマンドで相互変換)が、JSON のままにするのが無難です。ツールチェーンの互換性が高く、schemastore.org のカタログにあるスキーマもすべて JSON だからです。

三、CLI の3つの実装経路

config.yaml を例にします。スキーマは name と version を必須とし、version はセマンティックバージョン形式、countries は2文字の大文字英字文字列の配列を要求します:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

Python(jsonschema + PyYAML):

import json, yaml
from jsonschema import validate

data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)

Node(js-yaml + Ajv):

import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";

const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);

純パイプ(yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# または check-jsonschema は YAML を直接受け取る
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

3経路の違いはパース層だけです。最初の2つは明示的な2段階、パイプは1本で流し、check-jsonschema は内部で YAML→JSON 変換を行います。スキーマファイルは3つとも同じものです。

四、エディターでのリアルタイム検証:modeline と SchemaStore

Red Hat の YAML 拡張(yaml-language-server ベース)は VS Code で約3000万インストールを持ち、JSON Schema draft-04/07/2019-09/2020-12 をサポートします。接続方法は3つ:

# 方法1:modeline。ファイルの1行目でスキーマを指す
# yaml-language-server: $schema=./schema.json
name: checkout
// 方法2/3:.vscode/settings.json でファイル名または glob で関連付け
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable はデフォルトで有効です。package.json、GitHub workflow、docker-compose などの一般的なファイルは自動的に schemastore.org のカタログに関連付けられ、設定は1行も不要です。スキーマの description は補完候補の説明とホバー表示になり、required の欠落には赤線が引かれます。設定ミスは「デプロイ後の調査」から「タイピングした瞬間」に前倒しされます。これはまた、SchemaStore が使われる理由でもあります。YAML には公式のスキーマ標準がなく、JSON Schema が事実上の標準だからです。

五、スキーマはノルウェー問題をどう防げたか

第1節の NO 事故に戻ります。countries に要素レベルのスキーマを書きます:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

PyYAML が読み取った false は文字列ではないため、type: string が即座に失敗します。仮に別のパーサーが小文字の "no" として読んだとしても、pattern が阻止します。より厳しくするなら enum のホワイトリストを追加できます。同じスキーマを CI では第3節の CLI 経路で、エディターでは第4節の modeline で動かせば、両端とも同じ契約になります。

yamllint との役割分担も一言で言えます。yamllint の truthy ルール(true/false のみ許可し、他のブール風の綴りはすべて警告)が管轄するのは記述スタイルで、lint 層で flag: yes を検出します。JSON Schema が管轄するのはデータの形状で、どのパーサーを使っても関係ありません。事故チームは結局3点セットをすべて導入しました。文字列の引用符化、パイプラインへの yamllint truthy 導入、テンプレートでの2文字文字列のアサーションです。2つの防御層は重複ではなく補完関係にあります。

六、Kubernetes マニフェストの一括検証

Kubernetes の API 自体が OpenAPI で記述されており、kubernetes-json-schema プロジェクトがそれを標準的な JSON Schema に変換しています。kubeconform はこのスキーマ群で一括検証を行います。4コアのラップトップで 35139 ファイル・50714 リソースを kubeconform -ignore-missing-schemas -n 8 -summary で検証したところ 6.7 秒、同じ作業を kubeval では35秒かかりました。Helm ユーザーの定石は先にレンダリングしてから検証です:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict はスキーマに定義されていないフィールドを拒否し(タイプミスの早期発見)、CRD リソースは -ignore-missing-schemas でスキップするか、-schema-location でカスタムスキーマを差し込みます。

七、スキーマ検証ができないこと:3つの境界

  1. パーサーのバージョン差異はパース層で発生する。スキーマが見るのはパース結果です。PyYAML が読んだ NO はすでに false であり、スキーマは type/pattern でこの誤値を封じ込めることしかできません。根本対策はやはり引用符であり、スキーマにパーサーの修正を期待してはいけません。
  2. 論理エラーは管轄外。selector と labels の綴り不一致、K8s で selector が存在しないラベルを指す場合、スキーマは形状しか見ません。これらは admission webhook、OPA ポリシー、kubectl apply --dry-run=server で対応します。
  3. 重複キーは黙って後勝ち。多くの YAML パーサーは重複キーを警告なしで受け入れます。スキーマが受け取るデータはすでに1つのキーを失っており、yamllint の key-duplicates やパースフックで検出するしかありません。

リリース前チェックリスト:コード的な文字列は引用符で囲む → yamllint(truthy + key-duplicates)→ JSON Schema 検証(CI とエディターの両方)→ クラスタリソースは --dry-run=server も通す。この4ステップを踏めば、第1節のノルウェー事故はこのパイプラインの2ステップ目で止まります。

よくある質問

JSON Schema は YAML ファイルを直接検証できますか?

できますが、検証対象は「ファイル」ではなくファイルをパースした後のデータです。YAML 1.2 は JSON の厳密なスーパーセットであり、両者は同じデータ構造にパースされるため、1つのスキーマが JSON と YAML の両方に使えます。Python、Node、yq パイプ、check-jsonschema の4経路のいずれでも、手動での形式変換は不要です。

SchemaStore とは何で、どう使いますか?

schemastore.org は JSON Schema のカタログ(catalog.json)で、package.json、GitHub workflow、docker-compose など何百種もの一般的な設定ファイルのスキーマを収録しています。YAML/JSON 言語サポートを入れたエディターはデフォルトで自動関連付けを行い、yaml.schemas で URL を手動マップすることもできます。自社プロジェクトの設定ファイルなら、独自スキーマをカタログに投稿することも可能です。

yamllint と JSON Schema 検証は重複していますか?

重複しません。yamllint は記述スタイル(インデント、行長、truthy、重複キー)をテキスト層で検査し、JSON Schema はデータ構造(型、必須、列挙、pattern)をデータ層で検査します。ノルウェー事故の修正リストには両方がありました。truthy ルールは flag: yes のような綴りを検出し、スキーマは文字列配列に混入した false を検出します。

Kubernetes マニフェストの検証は kubeconform と kubectl dry-run のどちらを使うべきですか?

役割が違います。kubeconform はオフラインで一括処理でき、クラスタを必要とせず、CI に組み込んで構造的エラーを防ぐのに適しています。dry-run=server は実際の API サーバーに問い合わせ、admission webhook やクォータ層の問題を検出できますが、クラスタ接続が必須です。標準的な組み合わせは、CI で kubeconform を実行し、デプロイ前に dry-run=server を一度通すこと。両方の層を省略しないでください。


スキーマを書いたら、まず オンラインJSON検証ツール に YAML から変換した JSON を貼り付けてエラーを確認できます。スキーマのキーワードの書き方は JSON Schema 完全ガイド を、CI でスキーマをテストに監視させる方法は JSON Schema 契約テスト を、日常の JSON↔YAML 変換には JSON YAML XML 変換ツール をご利用ください。