runbook YAML の JSON Schema 化 方針メモ

runbook-json-schema.md

runbook YAML の JSON Schema 化 方針メモ

背景

• runn のシナリオ（runbook）は YAML で記述されるが、
  記法が複雑になってきており どんなキーや型が許されるか分かりづらい。
• バリデーションや補完のために JSON Schema を用意したい。
• しかし「既存の YAMLを収集 → サンプルから逆生成」だと メンテナンス性に課題がある。

---

選択肢と評価

1. サンプル YAML から半自動生成

• 方法: valid な runbook YAML を複数用意し、ツールで JSON Schema を推定。
• メリット: すぐ始められる、PoC が簡単。
• デメリット:
  • サンプルの網羅性に依存 → 抜け漏れしやすい
  • 実装変更時に Schema を追従するのが手作業になりがち

➡️ 補助的に使えるが、本番の方針には向かない。

---

2. Go の構造体定義から自動生成

• 方法: runn の YAML パーサが struct に Unmarshal している場合、その struct を invopop/jsonschema 等でスキーマ化。
• メリット:
  • 実装とスキーマが自動で一致
  • CI/CD に組み込んで自動生成可能
• デメリット:
  • runn が実際に struct でなく map[string]interface{} を使っている場合は難しい

➡️ struct ベースなら最有力。

---

3. コードにスキーマ情報コメントを埋め込む

• 方法: map[string]interface{} を使っている場合、処理ロジックの近くに期待する型をコメントで明記し、ツールで集約して JSON Schema を生成。

  // @runbook.schema path=steps[].if {"type":"string"}
  if v, ok := s[ifSectionKey]; ok {
      st.ifCond, ok = v.(string)
      ...
  }

• メリット:
  • 柔軟なパース実装でも対応可能
  • 「どんな型を想定しているか」がコードと一緒に残る
  • 実装とスキーマの乖離が少ない
• デメリット:
  • コメント整備の工数
  • DSL 設計の必要性（必須／enum／配列などをどう表現するか）

➡️ map[string]interface{} ベースなら有力な現実解。

---

方針決定の意図

• runn が struct ベースなら → #2 の「Go struct → JSON Schema 自動生成」 を採用する。
• runn が map ベースなら → #3 の「コードコメントにスキーマ情報を埋め込む」 を採用する。
• #1 の「サンプル YAML から逆生成」は補助ツールとして利用可能だが、メインには据えない。

---

まとめ

• まず runn のソース実装を調査し、YAML パーサが struct か map かを確認する。
• struct ならライブラリで自動生成、map ならコメント駆動で Schema を整備する。
• いずれの場合も「実装と Schema が自動的に一致する」ことを重視する。