---
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` のフェンスは本文中に置くコードブロックを表す）。

````
---
<YAML frontmatter>     # 索引層（第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/<ds-NNN>/        # ガイドライン（章ごとに分割）
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章）。
