メインコンテンツへスキップ

入力仕様定義（YAML → ドメイン）最終版

1. 入力全体の位置づけ

  • 入力は 一度きり使う YAML 定義
  • YAML に書かれた 記載順＝処理順
  • 既存構造は破壊せず、新規作成のみ
  • 既存要素が存在する場合は SKIP
  • YAML は BookStack の状態と同期しない（使い捨て）

2. トップレベルスキーマ

book_id: int
wip_markdown: string
pages: list[string]        # optional
chapters: list[chapter]    # optional

2.1 トップレベル項目定義

キー 型 必須 説明
book_id int 必須 BookStack の Book ID（name は使用しない）
wip_markdown string 必須 新規作成ページに入れる Markdown 本文
pages list[string] 任意 Book 直下に作成するページ名リスト
chapters list[object] 任意 章および章配下ページ定義

2.2 トップレベルキーの一意性（重複禁止）

  • トップレベルキー book_id, wip_markdown, pages, chapters は それぞれ一度のみ定義可能とする
  • 同一キーの重複定義は 入力仕様違反とみなす
  • ただし、重複キー検出のための特別な処理は行わず、YAML パーサが正常にロードできた入力のみを前提とする （重複キーはパーサ依存で上書きされ得るため、仕様として禁止することで可読性・予測可能性を担保する）

※ pages / chapters は キー自体は 1 回のみであり、複数要素は list の要素として表現する。

3. Book直下ページ（pages）

3.1 構造

pages:
  - "ページタイトル1"
  - "ページタイトル2"

3.2 意味論

  • pages は ページ名（string）のみの配列
  • 記載順で上から処理される

同一性判定ルール（Book直下ページ）

  • 対象：book_id に紐づく既存ページ

  • 判定条件：name 完全一致

  • 結果：

    • 一致 → SKIP
    • 不一致 → 新規作成（Book直下）

4. 章および章配下ページ（chapters）

4.1 構造

chapters:
  - name: "章名"
    pages:
      - "ページタイトルA"
      - "ページタイトルB"

4.2 chapter オブジェクト定義

キー 型 必須 説明
name string 必須 章名（完全一致で同一性判定）
pages list[string] 任意 章配下に作成するページ名リスト

4.3 意味論

章の同一性判定

  • 対象：book_id 内の章一覧

  • 判定条件：name 完全一致

  • 結果：

    • 一致 → 既存章を使用
    • 不一致 → 新規章を作成

章配下ページの同一性判定

  • 対象：該当章内のページ一覧

  • 判定条件：name 完全一致

  • 結果：

    • 一致 → SKIP
    • 不一致 → 新規作成（章配下）

5. 処理順序（仕様として固定）

YAML 全体として、以下の順序で処理される。

  1. YAML ロード

  2. 入力バリデーション

  3. Book 直下ページ一覧取得（SKIP判定用）

  4. pages を 上から順に処理

  5. chapters を 上から順に処理

    1. 章の存在確認（なければ作成）
    2. 章内ページ一覧取得
    3. 章配下 pages を 上から順に処理

※ 順序そのものが意味を持つ仕様であり、並び替えは行わない。

6. 入力エラーとして扱う条件（バリデーション）

6.1 必須チェック

  • book_id が存在し、int 型であること
  • wip_markdown が存在し、空でない stringであること

6.2 型チェック

  • pages が存在する場合：

    • list 型
    • 全要素が string

  • chapters が存在する場合：

    • list 型
    • 各要素が object
    • name が string で必須
    • pages が存在する場合は list[string]

6.3 重複チェック（入力エラー）

安全側設計として、以下は 入力エラーとする。

  • pages 内で同名ページが重複
  • chapters 内で章名が重複
  • 同一章の pages 内で同名ページが重複

※ Book直下 pages と章配下 pages の同名は 許容（別スコープ）

7. ドメインデータへの対応（次工程への前提）

入力 YAML は、少なくとも以下の ドメイン単位に分解される前提とする。

  • BookInput

    • book_id
    • wip_markdown
    • pages[]
    • chapters[]

  • ChapterInput

    • name
    • pages[]

※ 具体的な dataclass 定義は **次工程（ドメイン設計）**で行う。

上に戻る