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

結論: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ステップだけです:
- YAML ファイルをパースしてオブジェクト/配列を得る;
- JSON Schema をロードする;
- スキーマでデータを検証し、エラーを出すか通過させる。
ステップ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つの境界
- パーサーのバージョン差異はパース層で発生する。スキーマが見るのはパース結果です。PyYAML が読んだ
NOはすでにfalseであり、スキーマはtype/patternでこの誤値を封じ込めることしかできません。根本対策はやはり引用符であり、スキーマにパーサーの修正を期待してはいけません。 - 論理エラーは管轄外。selector と labels の綴り不一致、K8s で selector が存在しないラベルを指す場合、スキーマは形状しか見ません。これらは admission webhook、OPA ポリシー、
kubectl apply --dry-run=serverで対応します。 - 重複キーは黙って後勝ち。多くの 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 変換ツール をご利用ください。