--- type: guideline title: 第2章 ファイルとディレクトリの規約 source: デジタル庁 profile: mrlgss-doc/0.1 category: data-interop status: draft updated: 2026-06-16 --- # 第2章 ファイルとディレクトリの規約 ## 2.1 1 概念 = 1 ファイル 正本は **1 概念 = 1 Markdown ファイル**で構成する。「概念」とは、業務索引・データ要件スキーマ・ コード語彙・機能要件・法令・告示といった、参照の単位となるまとまりである。 1 ファイルは次の構造をとる（`yaml`／`text` のフェンスは本文中に置くコードブロックを表す）。 ```` --- # 索引層（第3章） --- # 見出し 本文（趣旨・解説・図表） # 知識層（第4章） ```yaml # 正本層（第5章）。型付きデータ ... ``` ```text # 規範文（第4章）。byte 保持 ... ``` ```` frontmatter は必須。本文・payload・規範文は概念の性格に応じて持つ。 ## 2.2 ディレクトリ＝アイデンティティ ファイルの**パスがその概念の所在を表す**。URL もパスに一致させる（SSG はパスをそのまま URL にする）。 標準仕様の正本系統は次のディレクトリ構造をとる。 ``` businesses/<業務>/ # 業務単位（例 001-juki） index.md # 業務索引 spec/ # 機能要件（章ごとに分割） index.md 01-....md data-list.md # データ要件（基本データリスト） codes.md # コード一覧 er.md # データモデル linkage-spec.md # 連携要件 laws/ # 法令・省令 guidelines// # ガイドライン（章ごとに分割） character-standard/ # 文字要件 ``` 業務コードのような「粗くて安定した軸」を上位に、種別を下位に置く。これは URN の構成（第6章）と 一致する。 ## 2.3 章分割の規約 仕様書本文・ガイドライン・本書のような長文は、**章ごとにファイルを分割**し、ディレクトリにまとめる。 - ディレクトリ直下に `index.md`（序文＋章目次）を置く。 - 章ファイルは `NN-slug.md`（2 桁連番＋英小文字スラッグ）で、連番が章順を表す。 - 各章ファイルの本文は H1（`#`）見出しで始める。章内の節は H2 以下を用いる。 - 見出しレベルは歯抜けにせず連続させる（H1 の次は H2、H2 の次は H3）。 > SSG は `index.md`＋章ファイル群を検出し、章一覧と見出しアウトラインを持つサイドバーを自動生成する。 > ファイル名の連番が章の並び順、本文の H1 が章タイトル、H2 以下がアウトラインになる。 ## 2.4 ファイル名に意味を埋めない 旧来の変換物は `001_住民基本台帳_基本データリスト【第2.4版】_20250228.md` のように、ファイル名に 業務名・種別・版・日付を詰め込んでいた。テキスト正本ではこれらを**すべて frontmatter のキーへ昇格** させ、ファイル名は安定したスラッグ（`data-list.md`）に保つ（第3章）。版や日付が変わってもファイル名＝ URL を変えないためである。 ## 2.5 添付資産（画像・SVG・CSV・フォント） 本文から参照する画像・図・データファイルは、概念ファイルと同じディレクトリかその `assets/` 配下に パス保持で置き、本文からは相対パス（`./assets/...` または `../assets/...`）で参照する。 - 図は可能な限り**テキストから生成する**（Mermaid・Graphviz DOT）。生成元テキストを本文に残し、 ビルド時に SVG へ焼く。手書きのバイナリ画像は最小限にとどめる（第4章）。 - 巨大データ（数万行）は CSV を添付し、本文はそれを参照するストリーミング表示に委ねる（第7章）。