第3章 frontmatter の書き方

frontmatter は文書の索引層である。検索・カタログ・RAG・ナビゲーションがここを読む。Open Knowledge Format（OKF）に倣い、ファイル先頭の --- 〜 --- に YAML で書く。

3.1 共通必須キー

すべての概念ファイルが次の 3 キーを持つ。

キー	型	説明
`type`	string（enum）	概念の種別。§3.2 の値から選ぶ
`title`	string	人間可読タイトル
`source`	string	発行主体（例: `デジタル庁` / `総務省` / `個人情報保護委員会`）

OKF の唯一の必須フィールドは type だが、本書は title／source を必須に締める。

3.2 type の値

文書の性格に応じて次から選ぶ。前半は索引層中心の「軽い」種別、後半（gov- 接頭辞）は正本層（payload）を持つ「重い」種別である。

type	対象	payload
`standard-spec`	標準仕様書本体（機能要件等）	任意
`guideline`	ガイドライン・解説・技術レポート	なし
`law`	法令（法律）	なし
`changelog`	変更履歴	なし
`other`	上記外	任意
`gov-business`	業務索引	なし
`gov-schema`	データ要件スキーマ（基本データリスト）	`ledger`＋`fields[]`
`gov-vocab`	コード語彙（コード一覧）	`code{}`
`gov-functional-requirement`	機能要件（正本）	`managed_items[]`＋`validations`
`gov-ordinance`	省令＝標準化基準	`terms` 他
`gov-notice`	告示	`notice_id`＋`tables[]`

軽い種別（data-list／linkage-spec など旧称）と重い種別（gov-schema 等）は、移行期には併存する。新規にテキスト正本を起こす場合は、型付き正本を持てる gov- 系を用いることを推奨する。

3.3 推奨キー（あると望ましい）

キー	型・パターン	用途
`profile`	string	準拠プロファイルの宣言（例 `mrlgss-doc/0.1`）
`urn`	string	概念の識別子（第6章。`gov-` 系で推奨）
`business_code`	`^[0-9]{3}$`	業務コード 3 桁
`version`	string	版（`4.1` を推奨。原表記 `第4.1版` も可）
`spec_date`	`YYYY-MM-DD`	仕様基準日
`ds_code`	`^ds-[0-9]{3}$`	DS 番号（ガイドライン）
`category`	string	カテゴリ（`security`／`data-interop` 等）
`law_id`	string	e-Gov 法令 ID
`norm_layer`	`L1`〜`L4`	規範レイヤー（第6章）
`status`	string	`draft` 等。草案の明示
`timestamp` / `updated`	ISO 日付	更新時刻
`original_file`	string	変換元ファイル名（トレーサビリティ）
`view`	string	SSG の特殊表示（`payload-table`／`data-table`）

type 別の必須キー（gov-schema は norm_layer／business、gov-vocab は code_id／business 等）は第6章で扱う。

3.4 値の書き方の注意（YAML の落とし穴）

frontmatter は YAML なので、暗黙の型変換に注意する（payload も同様。第5章で詳述）。

先頭ゼロを持つコード・番号は引用符で囲む。business_code: "001" と書く。001 は整数 1 に化ける。
日付を文字列で扱いたい場合は引用する。version: "4.1" のように、版番号は文字列として引用する（4.1 自体は数値に解釈され得る）。
yes／no／on／off／true／false は真偽値に解釈される（Norway problem）。これらを文字列値として使うときは引用する。

3.5 実例（住民記録基本データリスト）

type: gov-schema
title: 住民基本台帳 基本データリスト【第4.1版】
source: デジタル庁
profile: mrlgss-doc/0.1
urn: urn:jp:gov:std:001:schema
norm_layer: L4
business: urn:jp:gov:std:001:business
business_code: "001"
version: "4.1"
spec_date: 2025-09-30
item_count: 1027
view: payload-table