---
type: guideline
title: 第5章 payload（型付き正本）の書き方
source: デジタル庁
profile: mrlgss-doc/0.1
category: data-interop
status: draft
updated: 2026-06-16
---

# 第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` | | 定義・項目説明・サンプル |

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

```yaml
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の場合` のような条件を、機械可読な構造に起こす。

```yaml
- 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` のキー（コード値）は先頭ゼロや
予約語に化けないよう引用する。

```yaml
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` フェンスは「改変不可の原文」を担う。役割を混同しない。