# chimata-OKF プロファイル仕様 v0.1

**ステータス**: ドラフト（言語非依存の正本仕様）
**最終更新**: 2026-06-15
**プロファイル識別子**: `chimata-okf/0.1`
**位置づけ**: 自治体システム標準仕様を機械可読標準仕様（MRSS）化するための、Open Knowledge Format（OKF）スタイル markdown バンドルの形式仕様。本仕様が**正本**であり、実装（TS/Python 等の検証器・変換器）は派生である。

---

## 0. この仕様の範囲

### 0.1 対象

国（総務大臣・デジタル庁）が標準化法に基づき全国一律に定める**自治体システム標準仕様そのもの**を、人間・AI・プログラムが等しく扱える markdown バンドルとして表現する規約を定める。具体的には:

- 規範レイヤー: 法律（L1）・省令＝標準化基準（L2）・告示（L3）
- 技術仕様正本（L4）: 機能要件系（総務省）・データ要件系（デジタル庁）・コード一覧・帳票要件
- 概念間のトレーサビリティ（authority / renders_to / projection）と識別子（URN）

### 0.2 範囲外（v0.1 では規定しない）

- **分析レイヤー**: ライフサイクル（状態機械）・イベント伝播・業務間参照／保存／機微性の各概念。これらは標準仕様書正本に対応せず、chimata が連携基盤設計のために導出した分析成果物である。プロトタイプには `gov-lifecycle` / `gov-events` / `gov-relations` として実例があるが、**正本の型ではない**ため v0.1 から除外し、別仕様（プロファイル拡張）として後追いで定義する。
- リポジトリ戦略・ガバナンス様式・改訂プロセス（`next-format-proposal.md` §5 のとおり別途決定）。
- Mermaid 自動生成器・round-trip ビルド検証の実装（仕様は本書、実装は派生）。

> **重要な前提**: 既存の chimata YAML DSL（`schemas/yaml/*.yaml`）やプロトタイプの payload は、標準仕様書そのものではなく**分析の中間成果物**である。本仕様は既存 YAML の構造に引きずられず、標準仕様書正本に忠実な型を定義する。

### 0.3 関連ファイル

| 種別 | パス |
|---|---|
| 設計の全体像 | [`next-format-proposal.md`](./next-format-proposal.md) |
| 表現力インベントリ | [`spec-body-expressiveness.md`](./spec-body-expressiveness.md) |
| プロトタイプ実例 | [`okf-prototype/`](./okf-prototype/) |
| 型記法の参照実装 | `tools/schema/spec_types.py` |
| JSON Schema 群（本仕様の機械可読版） | [`chimata-okf-profile-v0.1/`](./chimata-okf-profile-v0.1/) |

---

## 1. バンドル構造

### 1.1 概念ファイル

正本は **1 概念 = 1 markdown ファイル**で構成する。各ファイルは:

1. **YAML frontmatter**（`---` で囲む）— 索引・人間可読サマリ・URN・リンク。OKF が検索する構造化層（§3）。
2. **markdown body** — 知識（自然言語・表・Mermaid）と、**payload フェンス**（§4）。

```
<frontmatter>          # type / urn / title + type 別キー
# 見出し
本文（Why・表・Mermaid 図）
```yaml               # payload: 機械可読正本（valid YAML）
...
```
```text               # 規範文: byte 保持（§6）
...
```
```

### 1.2 ディレクトリ＝アイデンティティ

OKF の流儀に従い、ファイルパスが概念の所在を表す。v0.1 の正本系統:

```
norms/
  law/<法令ID>.md              # gov-law（L1）
  ordinance/<法令ID>.md        # gov-ordinance（L2）
  notice/<告示ID>.md           # gov-notice（L3）
business/<業務>/
  index.md                    # gov-business（業務索引）
  schema.md                   # gov-schema（データ要件系・L4）
  codes/<コード>.md            # gov-vocab（コード語彙・L4）
functional/<業務>/
  <大分類>/<中-小分類>.md       # gov-functional-requirement（機能要件系・L4 正本）
  forms/<帳票>.md              # gov-form（帳票要件・L4）[予約]
```

> 分析レイヤー（lifecycle/events/relations）は `business/<業務>/` 配下に同居しうるが、v0.1 の正規 type 集合には含めない（§0.2）。

---

## 2. 3 軸の直交モデル

各概念は次の 3 軸に位置づけられる。3 軸は直交する（`next-format-proposal.md` 方針2）。

1. **規範レイヤー**: L1 法 → L2 省令 → L3 告示 → **L4 技術仕様（正本）**。オーサリングの流れは L4→L3（告示は技術仕様の法定レンダリング）であり、法的権威の向き（L1→L4）とは逆。
2. **系統（プロファイル）**: 機能要件系（総務省、自然言語・規範中心）／データ要件系（デジタル庁、厳密・構造中心）。両系統は同一バンドルに共存し URN で相互リンクする。
3. **表現層**: 厳密（payload）／知識（body 自然言語）／関係（frontmatter リンク + Mermaid）。1 概念内に同居する。

---

## 3. frontmatter スキーマ

機械可読版: [`chimata-okf-profile-v0.1/frontmatter.schema.json`](./chimata-okf-profile-v0.1/frontmatter.schema.json)

### 3.1 全 type 共通

| キー | 必須 | 説明 |
|---|:---:|---|
| `type` | ✅ | 概念の型（§5 の 8 値のいずれか） |
| `urn` | ✅ | 概念の識別子（§7 の文法） |
| `title` | ✅ | 人間可読タイトル |
| `profile` | 推奨 | プロファイル識別子。v0.1 は `chimata-okf/0.1` |
| `tags` | 任意 | 検索用タグ |
| `timestamp` | 任意 | バンドル生成時刻（ISO 8601） |

### 3.2 トレーサビリティ系（規範・L4 で使用）

| キー | 説明 | 値 |
|---|---|---|
| `norm_layer` | 規範レイヤー | `L1`/`L2`/`L3`/`L4` |
| `authority` | 上位規範根拠（複数可） | URN 配列 |
| `governs` | この規範が適用される下位概念 | URN 配列 |
| `renders_to` | この概念が焼かれる法的文書 | URN 配列 |
| `projection` | 告示プロジェクション（§8） | `{notice_legal_fields[], technical_only[]}` |
| `compliance_date` | 適合基準日（省令第2条4号が定義） | ISO 8601 日付 |
| `impl_class` | 自治体規模別の実装区分（省令第2条3号） | `{designated_city, core_city, general}` 各 `required`/`optional`/`prohibited` |
| `related` | 関連概念 | URN 配列 |
| `business` | 所属業務（gov-business への参照） | std URN |

### 3.3 type 別の必須キー

| type | 共通 3 キーに加えて必須 |
|---|---|
| `gov-law` | `norm_layer`, `law_id`, `law_num` |
| `gov-ordinance` | `norm_layer`, `law_id`, `law_num`, `authority`, `governs` |
| `gov-notice` | `norm_layer`, `notice_id`, `authority` |
| `gov-business` | `business_code`, `legal_basis` |
| `gov-functional-requirement` | `norm_layer`, `function_id`, `authority`, `impl_class`, `compliance_date` |
| `gov-form` | `norm_layer`, `form_no`, `authority` ［予約・§5.8］ |
| `gov-schema` | `norm_layer`, `business` |
| `gov-vocab` | `code_id`, `business` |

type 固有の補助キー（`spec_version` / `spec_source` / `function_id` / `category` / `entity_kind` / `item_count` 等）は許容するが、必須化はしない。

---

## 4. payload メタスキーマ

### 4.1 原則

- body の ```yaml フェンスが**機械可読正本**。markdown 抽出で valid YAML となり、変換器（Avro/JSON Schema/DDL/CDDL 生成器）の入力になる。
- frontmatter は索引、payload は正本。**厳密な型システムは frontmatter ではなく payload に温存する**（全項目を frontmatter に展開しない）。
- payload は **chimata-OKF メタスキーマ（JSON Schema）で検証する**。これにより「frontmatter は OKF が見るが payload は素通り」を防ぐ（検証ツール B1 の責務）。

### 4.2 type 別 payload スキーマ

| type | payload ルート | スキーマファイル |
|---|---|---|
| `gov-schema` | `ledger` + `fields[]` | [`schema.payload.schema.json`](./chimata-okf-profile-v0.1/schema.payload.schema.json) |
| `gov-functional-requirement` | `function_id` + `managed_items[]` + `validations` | [`functional-requirement.payload.schema.json`](./chimata-okf-profile-v0.1/functional-requirement.payload.schema.json) |
| `gov-vocab` | `code{id,name,values}` | [`vocab.payload.schema.json`](./chimata-okf-profile-v0.1/vocab.payload.schema.json) |
| `gov-ordinance` | `terms`/`functional_standard`/`form_standard`/`prohibition`/`transitional` | [`ordinance.payload.schema.json`](./chimata-okf-profile-v0.1/ordinance.payload.schema.json) |
| `gov-notice` | `notice_id` + `tables[]` | [`notice.payload.schema.json`](./chimata-okf-profile-v0.1/notice.payload.schema.json) |
| `gov-form` | `form{no,name,...}` ［予約］ | [`form.payload.schema.json`](./chimata-okf-profile-v0.1/form.payload.schema.json) |
| `gov-law` | （payload なし。条文は body と規範文フェンス§6） | — |
| `gov-business` | （payload なし。索引ノード） | — |

### 4.3 field 定義（gov-schema の核）

データ要件系のフィールドは原本「基本データリスト」の列を回収する:

| キー | 必須 | 由来する原本列 |
|---|:---:|---|
| `id` | ✅ | 項目ID（`{業務}-{5桁}`） |
| `name` | ✅ | 項目名 |
| `type` | ✅ | データ型＋桁数（§9 の記法） |
| `group` | | グループ |
| `class` | | クラス分類（概念階層） |
| `pk` | | 主キー |
| `required` | | `true`/`false`/`conditional` |
| `required_condition` | | `※※` 記法（`{doc, when[{field,op,value}]}`、§4.4） |
| `code` | | 参照コード一覧ID（gov-vocab） |
| `spec_ref` | | 標準仕様書関連箇所（機能要件系への明示リンク・機能ID群） |
| `sensitivity` | | 機微性（`pii_high`/`pii`/`internal`/`public`） |
| `impl_type` | | 実装類型（原本記号 ◎/○/×/-） |
| `definition` / `note` / `sample` | | 定義・項目説明・サンプル |

> `impl_type`（原本の記号転記、フィールド単位）と frontmatter の `impl_class`（規模別の機能要件区分）は**別軸**。混同しないこと。

### 4.4 conditional required の表現

原本「項目説明」の `※※00100007が1の場合かつ00100102が「なし」「不明」でない場合` 形式を構造化する:

```yaml
required: conditional
required_condition:
  doc: 住民種別が日本人かつ本籍が「なし」「不明」でない場合
  when:
    - { field: 001-00007, op: eq, value: "1" }
    - { field: 001-00102, op: not_in, value: ["なし", "不明"] }
```

- `when` は AND 配列。`op` は `eq`/`ne`/`in`/`not_in`/`lt`/`le`/`gt`/`ge`。
- JSON Schema の `if`/`then`/`allOf` へ機械変換される。

### 4.5 YAML スカラー規約（payload の落とし穴）

payload は YAML だが、JSON Schema 検証は JSON 値に対して行う。YAML 1.1 の暗黙型変換が型不一致を生むため、次を規約とする:

- **予約語キー・値の引用符**: `no`/`yes`/`on`/`off`/`true`/`false`（および大文字・タイトルケース）は YAML 1.1 で真偽値に解釈される（いわゆる "Norway problem"）。これらをキーまたは値に使う場合は必ず引用する。
  - 特に告示別号の `no:`（号番号）は `False` キーに化ける。番号には引用済みキー（`"no":`）を用いるか、`number:` 等の非予約語に改める。
- **日付・コード値の引用**: ISO 日付（`compliance_date` 等）・先頭ゼロを持つコード値（`"004"`, `"131016"`）は文字列として引用する。引用しない日付は YAML が `date` オブジェクト化し、JSON Schema の `type: string` と不一致になる。
- 検証ツール B1 は payload を YAML→JSON 正規化（日付・真偽値を仕様の期待型へ）してからスキーマ適用する。

> プロトタイプの省令 payload は `no: 2`（引用なし）を含み、本規約に未適合（中間成果物のため）。正本化時に修正する。

---

## 5. 8 type の規約

v0.1 の正規 type 集合は次の 8 つ（標準仕様書正本に忠実な集合）。

### 5.1 `gov-law`（法律・L1）
- 役割: 標準化法等の法律。下位レイヤーの究極根拠。
- 主役の表現層: 知識（条文）。
- payload: なし。条文は body + 規範文フェンス（§6）。
- projection: なし。

### 5.2 `gov-ordinance`（省令＝標準化基準・L2）
- 役割: 標準化基準を定める省令。用語（実装区分・適合基準日）を定義し、下位の機能要件・帳票要件が参照する規範語の源。
- 必須: `authority`（委任元の法）、`governs`（適用業務）。
- payload: `terms` / `functional_standard` / `form_standard` / `prohibition` / `transitional`。
- 設計含意: `prohibition.type: whitelist`（定義されていない＝実装してはならない）を表現でき、網羅性検証が法的意味を持つ。

### 5.3 `gov-notice`（告示・L3）
- 役割: 省令が委任した細目・実装区分・適合基準日を定める告示（別表）。**L4 技術仕様正本からの生成物**。
- payload: `notice_id` + `tables[].rows[]`。各行は `source`（生成元 L4 概念 URN）と `legal_fields`（byte 保持の法的フィールド）を持つ。
- projection: 受け皿。L4 の `renders_to` がここを指す。round-trip 検証の比較対象（§8）。

### 5.4 `gov-business`（業務索引）
- 役割: 1 業務 = 1 ディレクトリの索引ノード。Why（機械可読化の動機）・法令根拠・派生成果物一覧・概念グラフへの入口。
- 必須: `business_code`, `legal_basis`。
- payload: なし（純粋な索引）。

### 5.5 `gov-functional-requirement`（機能要件系・L4 正本）
- 役割: 総務省・機能要件の正本。「何を管理対象とするか」の規範。告示（L3）へ projection で焼く。
- 必須: `function_id`, `authority`（法・省令）, `impl_class`（規模別）, `compliance_date`。
- payload: `managed_items[]`（規範が管理を求める項目群。型・桁数は gov-schema 側）+ `validations`（errors/alerts）。
- 規範文（機能要件欄の原文）は ```text フェンスで byte 保持（§6）。
- projection: あり（§8）。

### 5.6 `gov-schema`（データ要件系・L4 正本）
- 役割: デジタル庁・基本データリストの正本。項目の型・桁数・コード参照・出力条件を厳密定義。
- 必須: `norm_layer`, `business`。
- payload: `ledger` + `fields[]`（§4.3）。Avro/JSON Schema/DDL/CDDL 生成器の入力。
- 2 系統交差: 各 field の `spec_ref` が機能要件系の機能IDを指し、機能要件の `managed_items[].field` が逆リンクする。**双方向リンクは原本データ由来**（人工 URN ではない）。
- projection: なし。

### 5.7 `gov-vocab`（コード語彙・L4）
- 役割: コード一覧。gov-schema の field `code:` と gov-functional-requirement の `code:` が参照する。
- 必須: `code_id`, `business`。
- payload: `code{id, name, values{}}`。
- projection: なし。

### 5.8 `gov-form`（帳票要件・L4）［予約］
- 役割: 別記様式（省令別表PDF）の法定レイアウトと出力項目。
- **v0.1 では予約**: 実例（`appendix_workflow.xlsx` の帳票レイアウト）未入手のため、frontmatter 骨格（`form_no` / `authority`）と payload 暫定骨格のみ規定し `additionalProperties` を許容する。確定は実データ入手後。

---

## 6. 規範文 byte 保持ルール

法的拘束力を持つフィールド（**規範文**）は、装飾・語順変更・正規化を一切加えず原文を byte 単位で保持する。

- **対象**: 告示別表の機能要件欄原文、法・省令の条文原文。
- **記法**: ```text フェンスに原文をそのまま格納する（```yaml ではない）。markdown 装飾（`**強調**` 等）を混入させない。
- **理由**: 告示は法的正本であり、技術仕様正本からの projection が配布告示と **byte 一致**することを CI で検証する。プロトタイプ実証では、初回に (a) `**管理**` の装飾混入、(b)「管理（※）すること」の語順変更、の 2 点で不一致が検知された。round-trip 検証が機能した証拠であり、byte 保持制約はこの実証から導かれた。
- **適用範囲**: 規範文のみ。Why・要件の考え方・validations 等の技術補足（projection の `technical_only`）は通常の markdown/payload でよい。

```text
日本人住民について、以下の項目を管理（※）すること。
※「管理」とは、データの設定・保持・修正ができることをいう。
（シート「項目詳細一覧」を参照）
```

---

## 7. URN 体系

### 7.1 名前空間オーナーは国（gov）

識別対象は標準仕様の概念であり、その権威者は国（総務大臣・デジタル庁）。自治体は適合義務を負う側で、仕様の名前空間オーナーではない。全自治体が同一の `001-00020 氏名` を共有できるのは、それが 1 つの国の標準だからである。よって正本は全て `urn:jp:gov:...`。

`urn:jp:lg:{団体コード}:...`（自治体独自定義レイヤー）は**予約のみ**。独自拡張コード・例規・特定団体デプロイ等を将来識別するためのもので、v0.1 では定義しない。

### 7.2 2 系統の URN

URN は固定プレフィクス `urn:jp:gov:` の後、広→狭で降りる（RFC 8141）。「ドメイン逆順」（DNS/Java 流）の概念は適用しない。

**(1) std 概念系**（業務スコープ）:

```
urn:jp:gov:std:{業務コード}:{種別}[:{id}]
```

- 分割軸は「粗くて安定した軸を先」の原則に従い**業務コードが先**。種別はその下位ファセット。`business/<業務>/` ディレクトリ構造と一致する。
- `{業務コード}`: 3 桁（`001` 等、先頭ゼロ保持）。
- `{種別}`: `business` / `schema` / `vocab` / `func` 等の小文字スラッグ。
- `{id}`: 種別内の識別子（コードID・機能ID 等）。

| 概念 | URN 例 |
|---|---|
| 業務索引 | `urn:jp:gov:std:001:business` |
| データ要件系スキーマ | `urn:jp:gov:std:001:schema` |
| コード語彙 | `urn:jp:gov:std:001:vocab:004` |
| 機能要件 | `urn:jp:gov:std:001:func:0010580` |

**(2) 法令系**（法令ID スコープ）:

```
urn:jp:gov:{law|ordinance|notice}:{法令ID}[#フラグメント]
```

- 規範レイヤーは業務スコープではなく法令IDで識別する。
- フラグメント: 条/号（`#art6`、`#art4-1`）、告示別表行（`#bt1-0010580`）。

| 概念 | URN 例 |
|---|---|
| 法律 | `urn:jp:gov:law:503AC0000000040#art6` |
| 省令 | `urn:jp:gov:ordinance:508M60000008031#art4-1` |
| 告示 | `urn:jp:gov:notice:508_soumu_99#bt1-0010580` |

### 7.3 関係はリンク

概念間・コード参照・業務間参照・法令参照は markdown リンク（URN または相対パス）で辿る。これが OKF のグラフ性を担う。

> **プロトタイプとの差分**: 既存プロトタイプは `std:business:001`（種別先）/ `std:juki:func:0010580`（短縮名）等が混在する。v0.1 では §7.2(1) の**業務コード先・数値コード**に正規化する。プロトタイプは中間成果物であり、本仕様が正本。

---

## 8. 告示プロジェクション

L4 技術仕様正本（機能要件系）は、その一部を L3 告示別表に焼く。どのフィールドを焼くかを frontmatter `projection` が宣言する:

```yaml
renders_to:
  - urn:jp:gov:notice:508_soumu_99#bt1-0010580   # 焼き先（告示第99号 別表第一）
projection:
  notice_legal_fields: [機能要件, impl_class, compliance_date, managed_items]  # 焼く（法的）
  technical_only: [要件の考え方, validations, related]                          # 焼かない（技術補足）
```

- `notice_legal_fields`: 告示別表に出力される法的フィールド。byte 保持（§6）。
- `technical_only`: 技術仕様にのみ存在する補足。告示には焼かない。
- **round-trip 検証**: projection で生成した告示別表行を、配布告示原本（例: 令和8年総務省告示第99号）と byte 比較する。プロトタイプでは機能ID 0010580 の全 10 legal フィールドが byte 一致を実証済み（`required→◎`、`compliance_date 2026-04-01→Excel serial 46113` の双方向変換含む）。
- gov-notice 側の `tables[].rows[].source` が、生成元 L4 概念 URN への逆リンク（`renders_to` の対）。

---

## 9. 型記法

データ型は標準仕様書（データ要件・連携要件標準仕様書 総論 §2.2）準拠の記法を用いる。参照実装: `tools/schema/spec_types.py`。機械可読版: `common.schema.json#/$defs/specType`。

### 9.1 公式型（9 種）

| 記法 | 意味 |
|---|---|
| `X` | 半角文字列 |
| `N` | 全角文字列（原本は全角Ｎ） |
| `9` | 整数（半角数字） |
| `9V` | 小数点付き実数 |
| `S9` | 符号付き整数 |
| `BLOB` | 画像 |
| `YEAR` | 年（YYYY） |
| `DATE` | 日付（YYYY-MM-DD、不詳日を条件付き許容） |
| `TIME` | 時刻（HH:MM:SS、秒省略可） |

### 9.2 桁数制約

| 記法 | 意味 |
|---|---|
| `X(6)` | 固定 6 桁 |
| `X(..20)` | 可変長 20 桁以内 |
| `9V(5,2)` | 整数部 5 桁・小数部 2 桁 |
| `S9(..10)` | 符号付き・可変長 10 桁以内 |
| `N(..100)` | 全角・可変長 100 桁以内 |

### 9.3 拡張型・配列

- 拡張型（公式仕様外だが実用上必要）: `timestamp`（ISO 8601）/ `boolean`（X(1) コード相当）/ `bytes`（BLOB 以外の任意バイナリ）。
- 配列はサフィックス `[]`（例: `X(6)[]`）。
- レガシー別名（`string`→X / `int`→9 / `float`→9V / `date`→DATE 等）は入力として許容するが、正本では公式記法に正規化する。

### 9.4 不詳日付

`DATE` は不詳日を許容する（特に外国人住民の生年月日）。形式 `E-YYYY-MM-DD`（不詳月 `00`/`A1`〜`A4`、不詳日 `00`/`A1`〜`A3`）。詳細は `docs/date-format.md`。

---

## 10. 適合性

バンドルが chimata-OKF プロファイル v0.1 に適合するとは、次を全て満たすことをいう:

1. 各概念ファイルの frontmatter が `frontmatter.schema.json` に適合する（type 別必須キーを含む）。
2. 各 payload フェンスが当該 type の payload スキーマに適合する。
3. 規範文が ```text フェンスで byte 保持されている（§6）。
4. URN が §7.2 の文法に適合し、`authority`/`renders_to`/`related`/`spec_ref` の参照先が解決可能。
5. projection を持つ概念は、生成した告示別表行が配布告示原本と byte 一致する（§8）。

> 1〜2 は検証ツール B1、5 は round-trip ビルド検証の責務。これらの実装は本仕様の派生であり、別途。

---

## 付録A: プロトタイプとの対応・差分

| 項目 | プロトタイプ実物 | v0.1 仕様 |
|---|---|---|
| type 数 | 11（lifecycle/events/relations 含む） | **8**（分析 3 type を除外・§0.2） |
| URN 文法 | 3 形式混在 | **業務コード先・数値**に正規化（§7.2） |
| 規範文 | ```text byte 保持（実証済み） | 規約化（§6） |
| payload | type ごとに実例あり | JSON Schema 化（§4） |
| projection | 0010580 で round-trip 実証 | 規約化（§8） |

## 付録B: 後追いで定義する拡張

- **分析レイヤープロファイル**: `gov-lifecycle` / `gov-events` / `gov-relations`（状態機械・イベント伝播・業務間参照／保存／機微性）。プロトタイプに実例あり。
- **`gov-form` の確定**: 帳票レイアウト実データ入手後（§5.8）。
- **`urn:jp:lg:` 自治体独自定義レイヤー**: 独自拡張コード・例規等（§7.1）。
