第5章 payload（型付き正本）の書き方

payload は文書の正本層である。データ要件・コード一覧・機能要件のように、型・桁数・コード参照・出力条件といった厳密な構造を持つ概念は、本文中の ```yaml フェンスに型付きデータとして書く。これがプログラム（Avro／JSON Schema／DDL／告示生成器）の入力となる。

5.1 原則

本文の ```yaml フェンスが機械可読正本である。Markdown から抽出すると valid YAML になる。
frontmatter は索引、payload は正本。厳密な型システムは frontmatter ではなく payload に温存する（全項目を frontmatter に展開しない）。
payload は型ごとのメタスキーマ（JSON Schema）で検証する（第9章）。

5.2 型記法

データ型は標準仕様書（データ要件・連携要件標準仕様書総論）準拠の記法を用いる。

記法	意味
`X`	半角文字列
`N`	全角文字列
`9`	整数（半角数字）
`9V`	小数点付き実数
`S9`	符号付き整数
`BLOB`	画像
`YEAR`	年（YYYY）
`DATE`	日付（YYYY-MM-DD、不詳日を条件付き許容）
`TIME`	時刻（HH:MM:SS、秒省略可）

桁数は括弧で添える。

記法	意味
`X(6)`	固定 6 桁
`X(..20)`	可変長 20 桁以内
`9V(5,2)`	整数部 5 桁・小数部 2 桁
`N(..100)`	全角・可変長 100 桁以内

配列はサフィックス []（例 X(6)[]）。不詳日付は E-YYYY-MM-DD 形式（不詳月・不詳日を許容）で表す。

5.3 データ要件スキーマ（gov-schema）

基本データリストは ledger（台帳メタ）＋ fields[]（項目）で書く。各項目は次のキーを持つ。

キー	必須	由来する原本列
`id`	✅	項目 ID（`{業務}-{5桁}`）
`name`	✅	項目名
`type`	✅	型＋桁数（§5.2）
`group` / `class`		グループ・クラス分類
`pk`		主キー
`required`		`true` / `false` / `conditional`
`required_condition`		条件付き必須の構造（§5.4）
`code`		参照コード一覧 ID（gov-vocab）
`spec_ref`		機能要件への参照（機能 ID 群）
`impl_type`		実装類型（原本記号 ◎/○/×/-）
`definition` / `note` / `sample`		定義・項目説明・サンプル

実例（住民記録基本データリストより。先頭ゼロを持つコード値は引用する）:

ledger:
  business_code: "001"
  short_name: juki
fields:
  - id: 001-00001
    name: 市区町村コード
    type: X(6)
    required: true
    group: 住民情報
    class: 市区町村コード
    pk: true
    impl_type: ◎
    definition: 市区町村を一意に識別するコード（指定都市においては区までを特定）
    sample: "131016"
  - id: 001-00002
    name: 宛名番号
    type: X(15)
    required: true
    pk: true
    spec_ref:
      - "0010539"
      - "0010165"

5.4 条件付き必須（conditional required）

原本「項目説明」の ※※00100012が1の場合 のような条件を、機械可読な構造に起こす。

- id: 001-00013
  name: 異動年月日_不詳表記
  type: N(72)
  required: conditional
  required_condition:
    doc: 異動年月日が不詳の場合
    when:
      - { field: 001-00012, op: eq, value: "1" }

when は AND 配列。op は eq／ne／in／not_in／lt／le／gt／ge。
doc には人間可読の条件文を、when には機械評価可能な述語を書く。
これは JSON Schema の if／then／allOf へ機械変換される。

5.5 コード語彙（gov-vocab）

コード一覧は 1 コード = 1 ```yaml フェンスで書く。values のキー（コード値）は先頭ゼロや予約語に化けないよう引用する。

code:
  id: "001"
  name: 性別
  values:
    "0": 不明（未記入）
    "1": 男
    "2": 女

5.6 YAML スカラーの規約（payload の落とし穴）

payload は YAML だが、検証は JSON 値に対して行う。YAML 1.1 の暗黙型変換が型不一致を生むため、次を守る。

予約語の引用（Norway problem）: no／yes／on／off／true／false（大文字・タイトルケース含む）はキー・値とも真偽値に解釈される。告示別号の no:（号番号）は false キーに化けるため、 "no": と引用するか number: に改める。
日付・コード値の引用: ISO 日付・先頭ゼロを持つコード値（"004"／"131016"）は文字列として引用する。引用しない日付は YAML が日付オブジェクト化し、type: string と不一致になる。
検証ツールは payload を YAML→JSON 正規化（日付・真偽値を期待型へ）してからスキーマを適用する。

5.7 規範文は payload に混ぜない

法的拘束力を持つ規範文（機能要件欄の原文・条文）は payload ではなく ```text フェンスで byte 保持する（第4章 §4.5）。payload は「型付きデータ」を、text フェンスは「改変不可の原文」を担う。役割を混同しない。