# mrlgss 文書プロファイル仕様 v0.1（mrlgss-doc/0.1）

**ステータス**: ドラフト（言語非依存の正本仕様）
**プロファイル識別子**: `mrlgss-doc/0.1`
**位置づけ**: 現行の自治体システム標準仕様書・政府ガイドライン・関連法令を、Word/Excel から
変換した **Markdown 文書** として記述するための軽量メタデータ規約。全文検索・RAG・MCP 参照・
GitHub 改訂・AI フレンドリーな Web ホストといった「現実的なニーズ層」を満たすことを目的とする。

**OKF 準拠**: 本プロファイルは [Open Knowledge Format（OKF）](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
のプロファイルである。OKF は「markdown ファイル + YAML frontmatter のディレクトリ」で知識を表現する
最小限の仕様で、**唯一の必須フィールドは `type`**、`timestamp`/`title`/`tags` 等は標準だが任意。本プロファイルは
OKF の `type` を文書種別の表明に用い、加えて `title`/`source` を必須化する（OKF の任意フィールドを必須に締めるのは
プロファイルの裁量）。OKF 標準の `timestamp` も任意フィールドとして受ける。これにより OKF エコシステムの
ツールがそのまま本文書群を扱える。

## 0. 範囲とスタンス

### 0.1 これは「文書コンテナ規約」である

本プロファイルが規定するのは **frontmatter（YAML メタデータ）だけ** である。本文（markdown body）は
自由テキストでよい。表・図・条文・データリストの**構造化や型付けは行わない**。

- 厳密な型付き payload（フィールド型・桁数・コード参照・告示 projection 等）は、別系統の
  **chimata-OKF プロファイル v0.1**（`chimata-okf-profile-v0.1.md`）が担う。本プロファイルはその**手前**に位置し、
  「まず現行文書を構造化メタデータ付きで扱える」ことを保証する。
- 両プロファイルは**独立**して共存する。1 文書が両方に適合することもあるが、要求はしない。

### 0.2 設計原則

1. **既存慣行の昇華**: chimata のクローラ（`crawler/guidelines.py`）が既に付与している frontmatter
   （`ds_code`/`title_ja`/`category`/`source`/`updated`/`original_file`）を壊さず、規約として明文化する。
2. **緩く受けて段階移行**: 必須は最小限（4 キー）。`additionalProperties: true` で旧キー・将来キーを許容する。
3. **ファイル名に埋まった情報の昇格**: 現行ファイル名（例 `002_印鑑登録_機能別連携仕様【第2.4版】_20250228.md`）に
   埋まった業務コード・文書種別・版・日付を、検索可能な frontmatter キーへ昇格させる。

### 0.3 範囲外（v0.1 では規定しない）
- 本文の構造化・表の型抽出（→ chimata-OKF プロファイル）。
- リンク解決・出典 URL の到達性検証（→ 後続の意味検証ツール）。
- 既存文書群への frontmatter 一括付与（バッチ移行は別作業）。

---

## 1. 文書ファイル構造

```
---
<YAML frontmatter>   # 本プロファイルが検証する唯一の対象
---
<markdown body>      # 自由テキスト（変換済み本文。検証しない）
```

frontmatter は先頭の `---` 〜 次の `---` で囲む。frontmatter を持たない文書（素の変換ダンプ）は
**本プロファイル未適合**とする（検証器は「frontmatter 無し」を明示エラーとして報告する）。

---

## 2. frontmatter キー

### 2.1 共通必須キー

| キー | 型 | 説明 |
|---|---|---|
| `type` | string (enum) | OKF 必須フィールド。本プロファイルでは文書種別（§2.2）を値とする |
| `title` | string | 文書タイトル（人間可読） |
| `source` | string | 発行主体（例: `デジタル庁` / `総務省` / `e-Gov`） |

> OKF の唯一の必須フィールドは `type`。本プロファイルはそこに `title`/`source` を足して必須3キーとする。

### 2.2 type の値（enum）

OKF の `type` フィールドに入れる文書種別。実データから導出した 8 種:

| 値 | 対象 |
|---|---|
| `standard-spec` | 標準仕様書（データ要件・連携要件 総論／各論など） |
| `data-list` | 基本データリスト |
| `linkage-spec` | 機能別連携仕様 |
| `guideline` | 政府ガイドライン（デジタル社会推進標準ガイドライン群、DS 番号系） |
| `law` | 法令（e-Gov） |
| `changelog` | 変更履歴 |
| `comparison` | 新旧対照表 |
| `other` | 上記に当てはまらない文書 |

### 2.3 任意キー（type に応じて推奨。欠けても適合）

> v0.1 では type 別の必須化は**行わない**（緩く受けて段階移行）。下表は「あると望ましい」キー。

| キー | 型・パターン | 用途 | 主な type |
|---|---|---|---|
| `timestamp` | ISO 8601 date-time | OKF 標準フィールド。最終更新時刻 | 全般 |
| `profile` | const `mrlgss-doc/0.1` | 本プロファイル準拠の明示 | 全般 |
| `business_code` | `^[0-9]{3}$` | 業務コード3桁 | data-list / linkage-spec / standard-spec |
| `version` | string | 版（`4.1` 推奨。`第2.4版`も可） | standard-spec / data-list / linkage-spec |
| `spec_date` | ISO date `YYYY-MM-DD` | 仕様基準日 | data-list / linkage-spec |
| `ds_code` | `^ds-[0-9]{3}$` | DS 番号 | guideline |
| `category` | string | DS カテゴリ（security 等） | guideline |
| `law_id` | `^[0-9A-Za-z]+$` | e-Gov 法令ID | law |
| `title_en` | string | 英題 | guideline |
| `updated` | ISO date | 取得・更新日 | 全般 |
| `original_file` | string | 変換元ファイル名（トレーサビリティ） | 全般 |
| `tags` | string[] | 検索タグ | 全般 |

> `profile` は OKF 必須ではなく任意。OKF は `type` のみ必須なので、`profile` を付けずとも本プロファイルの
> 必須3キーを満たせば適合とみなす。`profile` は「この文書は mrlgss-doc/0.1 に従う」という producer の宣言。

### 2.4 後方互換（既存ガイドライン frontmatter）

`crawler/guidelines.py` が生成した既存 frontmatter は `source` は持つが、`type`/`title` を持たず `title_ja` を
使う。したがって**現行のガイドライン frontmatter はそのままでは v0.1 未適合**であり、最小限の移行
（`type`/`title` の追記）が必要になる。v0.1 は次の方針で受ける:

- `type`/`title`/`source` を必須とするが、schema は `additionalProperties: true` なので `title_ja`/`ds_code`/
  `original_file` 等の旧キーは**そのまま許容**される。旧キーを壊さず、必須キーの追記だけで適合する。
- 移行期は `title`（必須）と `title_ja`（任意・互換）が併存しうる。`title` への一本化は別タスク。
- `version` は `第2.4版` のような原表記も string として許容する（`4.1` への正規化は推奨に留める）。

---

## 3. 適合性

文書が mrlgss-doc/0.1 に適合するとは、次を満たすことをいう:

1. 先頭に YAML frontmatter ブロックを持つ。
2. frontmatter が `document.frontmatter.schema.json` に適合する（共通必須3キー `type`/`title`/`source`・type enum・各パターン）。

本文は検証しない。適合性の機械検証は検証器（`src/doc-validate.ts` / CLI `--doc`）が担う。

機械可読版スキーマ: [`doc-v0.1/document.frontmatter.schema.json`](./doc-v0.1/document.frontmatter.schema.json)

---

## 付録: chimata-OKF プロファイルとの関係

| 観点 | mrlgss-doc/0.1（本書） | chimata-okf/0.1 |
|---|---|---|
| 対象 | 現行の変換済み文書（仕様書・ガイドライン・法令） | 理想形の機械可読標準仕様（型付き正本） |
| 検証対象 | frontmatter のみ | frontmatter + payload(```yaml```) |
| 型の厳密さ | 要求しない（緩い索引） | 厳密（X(6)/N(100)/conditional required 等） |
| ねらい | 検索・RAG・ホスト・改訂を回す現実層 | 生成・告示 projection・round-trip の正本層 |
| 検証器 | doc-validate（CLI `--doc`） | B1（CLI 既定） |

両者は同じ抽出・YAML 正規化基盤（`src/extract.ts` / `src/yaml.ts`）を共有するが、スキーマも
バリデータも独立している。
