folio — relations (v1.0.0)

§1. W3C Standard Vocabulary

関係性は W3C 既存標準語彙 (dcterms / schema.org / PROV-O) を最優先で採用し、表現できない関係のみ §2 で folio 独自語彙を定義する。

§1.1 Dublin Core Terms (DCMI)

文書間関係 (置換 / 参照 / 部分 / 要求 / 来歴) は dcterms 語彙を採用 MUST、 JSON-LD context に dc prefix を宣言する。

DCMI Metadata Terms は文書間関係を表現する W3C 推奨語彙集である。 folio 規範では以下の語彙を採用する MUST。

採用する dcterms 語彙
folio で表したい関係	採用語彙	逆語彙	備考
supersedes (置き換える)	`dc:replaces`	`dc:isReplacedBy`	ADR supersedes 関係、 §5 で双方向 materialize 対象
cross-reference (参照)	`dc:references`	`dc:isReferencedBy`	spec 同士の引用、双方向 dual
subsection (一部である)	`dc:hasPart`	`dc:isPartOf`	cluster (例: decisions/) ↔ 個別 ADR
requirement (要求事項)	`dc:requires`	`dc:isRequiredBy`	強い依存、 folio:depends-on の代替を検討
provenance (来歴)	`dc:provenance`	(なし)	監査用、 audit trail に使用

@context prefix: "dc": "http://purl.org/dc/terms/" を JSON-LD context で MUST 宣言する。

§1.2 schema.org (補完)

dcterms で表せない型・記事メタデータは schema.org で補完し、 spec の base 型は schema:TechArticle とする。

dcterms で表現できない型情報・記事メタデータは schema.org で補完する。

採用する schema.org 型・プロパティ
用途	採用	備考
spec file の base 型	`schema:TechArticle`	`schema:Article` の specialization、技術文書向け
creative work 一般	`schema:CreativeWork`	ADR / research note 等の汎用型
citation (出典)	`schema:citation`	research/ から外部 URL を参照する際に使用
基底文書 (派生元)	`schema:isBasedOn`	research → spec の派生関係に使用可能

@context prefix: "schema": "https://schema.org/" を JSON-LD context で MUST 宣言する。

§1.3 PROV-O (履歴・派生)

派生・生成の来歴は PROV-O (wasDerivedFrom / wasGeneratedBy) を、使用時のみ採用する。

PROV-O (W3C Provenance Ontology) は出所・派生・寄与関係を表現する。 folio では derived-from 系の関係に採用する。

採用する PROV-O 語彙
folio で表したい関係	採用語彙	備考
derived-from (派生元)	`prov:wasDerivedFrom`	spec → 派生元 research の関係、 ADR → 元の dialog/issue
generated-by (生成プロセス)	`prov:wasGeneratedBy`	auto-generated artifact (将来の inventory.json 等)

@context prefix: "prov": "http://www.w3.org/ns/prov#" を JSON-LD context で MUST 宣言する (使用時のみ)。

§2. folio Custom Vocabulary

標準語彙で表せない folio 固有の関係のみ folio: prefix で独自定義し、追加は user 承認の ADR を経る MUST。

§2.1 folio 独自語彙 (規範定義)

folio:depends-on / extends / implements の 3 語を独自定義する (URI 実体は v1.0.0 で解決可能化予定の placeholder)。

folio:* prefix で定義する独自語彙
語彙	意味	逆語彙	W3C 代替検討
`folio:depends-on`	技術的依存 (この spec が成立するために必要な前提 spec)	`folio:depended-by`	`dc:requires` の方が強すぎる、折衷で独自定義
`folio:extends`	継承・拡張 (rules.html § 等を Layer 1 consumer が拡張する場合)	`folio:extended-by`	`schema:additionalType` は近いが意味が弱い
`folio:implements`	constitution 原則 (P-1〜P-13) の実装関係	`folio:implemented-by`	標準で対応する概念なし (constitution と spec の関係は folio 固有)

@context prefix: "folio": "https://folio.dev/spec/v1/" を JSON-LD context で MUST 宣言する (使用時のみ)。 URI 実体は v1.0.0 リリース時に解決可能化予定 (現在 placeholder)。

§2.2 命名規則 (standard 優先原則)

新規関係は標準語彙 → 既存独自語彙 → 新規 folio: 語彙の順で採用判断し、独自語彙の ADR には却下理由・逆語彙・使用例を含める MUST。

新規関係を spec で導入する際は、以下の順で採用語彙を決定する MUST。

§1 標準語彙 (dcterms / schema.org / PROV-O) で表現可能か検討する
表現可能なら標準語彙を使用する MUST (独自命名禁止)
表現不可能 (意味が弱い / 強い / 不適合) と判断した場合、 §2.1 既存独自語彙で代替可能か検討する
既存独自語彙で表現不可能な場合のみ、新規 folio:* 語彙を ADR で提案する

独自語彙導入時の ADR には以下を MUST 含める:

標準語彙で表現できない理由 (どの語彙を検討したか、なぜ却下したか)
逆語彙の有無 (双方向 dual を採用するか、単方向で済むか)
使用 spec 例 (どの spec で本語彙を使う予定か)

§3. JSON-LD Schema in `<head>`

各 spec は head に JSON-LD ブロックを 1 個 MUST 持ち、その関係性表現 schema を本章が規定する。

§3.1 Minimal Example (関係性なし)

関係性を持たない最小 spec の JSON-LD 例。 @type は schema:TechArticle を採用し、独自型は使わない。

関係性を持たない最小 spec の例 (constitution.html 等)。 @type は §1.2 推奨の schema:TechArticle を MUST 採用 (独自 FolioSpec 型は §2.2 命名規則に反するため使用しない)。 dc:title 等の dcterms 語彙を後から追加する場合は @context に "dc": "http://purl.org/dc/terms/" prefix の追加が MUST (§3.2 Full Example を参照):

<script type="application/ld+json">
{
  "@context": {
    "schema": "https://schema.org/",
    "folio": "https://folio.dev/spec/v1/"
  },
  "@id": "./constitution.html",
  "@type": "schema:TechArticle",
  "folio:version": "0.4.2-draft",
  "folio:stakeholders": ["Developer", "AI Agent"]
}
</script>

§3.2 Full Example (関係性込み)

複数の関係性 (references / depends-on 等) を宣言する spec の JSON-LD 例。

複数の関係性を持つ spec の例 (本 relations.html を含む):

<script type="application/ld+json">
{
  "@context": {
    "dc": "http://purl.org/dc/terms/",
    "schema": "https://schema.org/",
    "folio": "https://folio.dev/spec/v1/"
  },
  "@id": "./relations.html",
  "@type": "schema:TechArticle",
  "dc:title": "folio relations spec",
  "folio:version": "0.1.0-draft",
  "folio:stakeholders": ["Developer", "AI Agent", "External Reviewer"],
  "dc:references": [
    { "@id": "./rules.html#s4-format" },
    { "@id": "./constitution.html#s2-principles" },
    { "@id": "../research/spec-graph-management-research.html" }
  ],
  "folio:depends-on": [
    { "@id": "./rules.html" }
  ]
}
</script>

§3.3 `@id` Resolution Rules

@id と参照値の記述規則 (自己 / 同一 dir / 上位 dir / section anchor の相対 path、 architecture 配下は絶対 URL 禁止)。

@id および参照値 ({ "@id": "..." }) は以下の規則で記述する MUST。

自己参照 (self): "@id": "./<self-filename>" 形式で、 file 名のみ記述。例: "./relations.html"。
同一 dir 内 spec: "@id": "./<filename>"。例: "./rules.html"。
上位 dir spec: "@id": "../<path>"。例: "./constitution.html"。
section anchor: "@id": "<path>#<section-id>"。例: "./rules.html#s4-format"。
絶対 URL 禁止: architecture/ 配下では http(s):// で始まる絶対 URL を @id として記述しない (相対 path で表現する)。例外: @context の vocabulary URI (http://purl.org/dc/terms/ 等) は絶対 URL MUST。

§3.4 Conformance Level (Phase 1)

試作段階の遵守レベル: JSON-LD ブロックと標準語彙優先は MUST、 @id 自己参照と関係性宣言は次 Phase で MUST へ昇格する。

本 §3 の遵守レベルは試作段階 (Phase X2) では以下とする:

項目	Phase X2 (現在)	Phase X3 以降
JSON-LD ブロック存在	MUST	MUST
`@id` 自己参照	SHOULD	MUST
関係性宣言 (`dc:`, `folio:`)	SHOULD	MUST (リンクを HTML `<a href>` で書くなら JSON-LD でも書く)
標準語彙優先 (§2.2)	MUST	MUST

§4. Inventory Schema

全 spec を集約する inventory.json を auto-generate する設計の schema を規定する (実体 file は CLI 生成で手動作成禁止)。

§4.1 inventory.json Structure

inventory.json の構造と各 field の型・必須・source を定義する。

{
  "$schema": "https://folio.dev/inventory/v1.json",
  "generatedAt": "ISO-8601 timestamp",
  "folioVersion": "0.x.y-draft",
  "specs": [
    {
      "@id": "specs/relations.html",
      "title": "folio relations spec",
      "summary": "spec 間の関係性表現規約 (JSON-LD + W3C 語彙 + inventory)",
      "doc-type": "spec",
      "status": "draft",
      "version": "0.1.0-draft",
      "stakeholders": ["Developer", "AI Agent"],
      "relations": {
        "dc:references": ["specs/rules.html#s4-format"],
        "folio:depends-on": ["specs/rules.html"]
      }
    }
  ]
}

inventory.json field 定義
field	type	必須	source
`$schema`	URL	MUST	固定値 (folio CLI が埋込)
`generatedAt`	ISO 8601	MUST	CLI 実行時刻
`folioVersion`	SemVer string	MUST	plugin.json から読込
`specs[].@id`	relative path	MUST	spec の `<head>` JSON-LD から
`specs[].title`	string	MUST	spec `<title>` または JSON-LD `dc:title`
`specs[].summary`	string (1-2 文)	SHOULD	spec `<header> .meta` または最初の `<aside class="informative">` 第 1 段落
`specs[].doc-type`	enum	MUST	`<meta name="folio-doc-type">`
`specs[].status`	enum	MUST	`<meta name="folio-status">`
`specs[].version`	SemVer string	MUST	`<meta name="folio-version">`
`specs[].stakeholders`	array	SHOULD	`<meta name="folio-stakeholders">` または JSON-LD `folio:stakeholders`
`specs[].relations`	object	SHOULD	JSON-LD `dc:` / `folio:` プロパティ集約

§4.2 Three-Tier Progressive Disclosure Model

Anthropic Agent Skills の 3-tier loading に倣い、 Tier 1 (inventory) → Tier 2 (head + 要約) → Tier 3 (本文) で AI の context を効率化する。

3-tier model と folio file の対応
Tier	Anthropic Skills	folio 対応	tokens 目安
Tier 1	YAML `name` + `description`	`inventory.json` (本 §4 schema)	30-50 per spec
Tier 2	`SKILL.md` 本体	各 spec の `<head>` JSON-LD + 本文サマリ第 1 段落	500-2000 per spec
Tier 3	`reference` files	各 spec 本文全体 + `../research/*.html`	unbounded

AI agent は spec edit 開始時、 Tier 1 (inventory.json) のみ取得して全体構造を把握 MUST。関連する spec のみ Tier 2 (各 spec head + 第 1 段落) を読み、編集対象 spec のみ Tier 3 (本文) を読み込む。全 Tier 3 一括読込は context 圧迫の原因のため SHOULD NOT。

例: folio specs の 3-tier mapping

architecture/spec/ + constitution.html の Tier 別表現 (Phase X3 の inventory auto-generate 想定)
file	Tier 1 (inventory.json entry summary)	Tier 2 (head + 冒頭 aside)	Tier 3 (本文)
`constitution.html`	「folio の 14 不変原則 (P-1〜P-14、 3-tier)」	JSON-LD + §1 Purpose 第 1 段落	§1〜§7 全本文 + 不変原則本体
`rules.html`	「Layer 1 consumer 向け universal rules + Mandatory Actions」	JSON-LD + §0 Reader's Guide	§0、 §2〜§6、 §10 全本文
`folio-self-spec.html`	「folio Layer 0 framework 自身の architecture spec」	JSON-LD + §0 Reader's Guide	§0〜§9 全本文 + 8 mermaid 図
`relations.html` (本書)	「spec 間関係性表現規約 (JSON-LD + W3C 語彙 + inventory)」	JSON-LD + §0 Reader's Guide	§0〜§6 全本文

§4.3 Auto-Generation Timing

inventory.json の生成・stale 検出のタイミングと Phase を定める (現 X2 は非生成、 X3 で auto-update + CI 検出)。

事象	generation 動作	Phase
spec file 追加・編集・削除	`inventory.json` が auto-updated される MUST (具体的 enforcement mechanism は folio-self-spec.html §7 系に集約予定、試作 plugin 完成時)	X3 (試作 plugin 完成後)
CI build 開始時	`inventory.json` の stale 状態を検出し CI failure とする MUST (検出 mechanism は folio-self-spec.html §7.5 系に集約予定)	X3
scratch 段階 (現在 X2)	inventory.json は生成しない。必要なら手動の `specs/README.html` 内 file inventory 表が代替	X2 (現在)

§4.4 Input / Output Behavior

folio inventory CLI の WHAT (走査対象 dir・出力先・失敗モード) を規定し、実装 HOW は folio-self-spec §9 に隔離する。

§4.4.1 Scan target directories

architecture/spec/ + architecture/decisions/ + architecture/research/ を MUST scan (X4-C で scratch/ から canonical layout へ物理移植済、 changes/ は ADR-0021 で廃止)
scan 対象 file: *.html のうち <head> JSON-LD ブロックを持つもの
除外: @type=FolioConstitution の doc (folio 自身の不変 constitution) は scan 対象外 (FolioConstitution schema = spec の @context-object + @id 規約と別形のため spec graph に含めない、 ADR-0023)。除外は @type による schema-based 判定でファイル名 (constitution.html) に依存しないため、 consumer の conforming constitution (@type=schema:TechArticle) は通常 spec として scan + link-integrity 検査される (ADR-0024 §2.2、 2026-05-26 に ADR-0023 の name-based 除外を refine)
生成 view は scan 外: folio build が graph から導出する表示層 (architecture/index.html landing / glossary.html) は architecture 直下 (3 dir の外) に置かれ scan 対象に入らない — graph (SSoT) → view (派生) の一方向を保つ (ADR-0035 / ADR-0036 / ADR-0039。 view の鮮度は validate の nav-regen-drift / chrome-drift が検査)

§4.4.2 Output path

repo-root inventory.json (走査 base = architecture/ と出力先 = repo-root を decouple、 x4-plan §5 SSoT / ADR-0023)。試作 plugin の folio inventory CLI で auto-generate、 manual 作成は禁止、 .gitignore 対象

§4.4.3 Failure mode

失敗種別	動作
JSON-LD parse error	該当 file を skip + stderr に warn、 inventory 全体生成は継続
stale 検出 (CI build 時)	CI failure (rules.html §10.2 REQ-CI-016 json-ld-validation gate と integration)
file system access error	fatal exit、 stderr に error

本 §4.4 の規範を実機検証する scenario は、試作段階では verification.html §3.6 REQ-VER-010 / REQ-VER-011 の tests/scenarios/inventory-gen.yaml (kind: cli-golden、 folio inventory の生成出力を golden と byte-diff) に集約される。完成形の auto-regen / stale 検出 (research §7.5 use case 7 inventory-regen.yaml / REQ-REL-004) は Phase X4+。

§5. Bidirectional Reference

forward relation の記述 MUST と、 reverse relation を auto-materialize する計画 (Phase X3+) を集約する。

§5.1 双方向 dual の対象関係

双方向 dual で記述する SHOULD の forward / reverse 対 (replaces / references / hasPart / depends-on / extends / implements)。

以下の関係は双方向 dual で記述する SHOULD (片方を書いたら反対側も書く):

forward	reverse	典型例
`dc:replaces`	`dc:isReplacedBy`	ADR supersede 関係
`dc:references`	`dc:isReferencedBy`	spec cross-ref
`dc:hasPart`	`dc:isPartOf`	cluster ↔ 個別 spec
`folio:depends-on`	`folio:depended-by`	技術依存
`folio:extends`	`folio:extended-by`	Layer 1 拡張
`folio:implements`	`folio:implemented-by`	constitution ↔ spec

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff'}}}%%
flowchart TB
  accTitle: 双方向 relation の detect-remediate lifecycle
  accDescr: spec A が forward relation (dc:references → spec B) を head JSON-LD に宣言する。 Phase X3+ tooling 着地後は、 folio fix が target spec B に対応 reverse relation を auto-materialize し、 folio validate の broken-reverse gate が欠落 reverse を violation として報告する。 結果として relation graph は双方向に保たれる。
  DECL["spec A: forward 宣言
dc:references → spec B
(REQ-REL-001)"]
  DECL --> GATE{"folio validate
broken-reverse gate
(REQ-REL-004、 Phase X3+)"}
  GATE -->|"reverse 欠落"| VIO["broken-reverse
violation 報告"]
  VIO --> FIX["folio fix
(REQ-REL-002、 Phase X3+)"]
  GATE -->|"reverse 有り"| OK["clean"]
  FIX --> MAT["spec B に dc:isReferencedBy → spec A
を materialize"]
  MAT --> BIDI(["relation graph 双方向
(bidirectional)"])
  OK --> BIDI

§5.2 Precedent (log4brains pattern)

双方向 auto-materialize の precedent は log4brains の supersedeBy() で、 folio も同設計を Phase X3+ で採用予定。

§5.3 EARS 規範要件

forward 宣言・reverse auto-materialize・X2 手動・broken-reverse 報告の 4 件を EARS 要件として規定する。

REQ-REL-001 Ubiq. 各 spec は該当する forward relation (dc:replaces / dc:references / folio:depends-on 等) を <head> JSON-LD に宣言する (関係が存在する場合)。

REQ-REL-001: Each spec SHALL declare applicable forward relations (e.g., dc:replaces, dc:references, folio:depends-on) in its <head> JSON-LD block when such relations exist.

REQ-REL-002 Event Phase X3+ tooling が active で forward relation が宣言されると、対応する reverse relation (dc:isReplacedBy 等) を target spec に auto-materialize する。

REQ-REL-002: WHEN Phase X3+ tooling is active and a forward relation is declared in any spec, the system SHALL auto-materialize the corresponding reverse relation (e.g., dc:isReplacedBy) on the target spec.

REQ-REL-003 Ubiq. Phase X2 (現在) では reverse relation は X3 tooling 着地まで手動で記述する (SHOULD)。

REQ-REL-003: In Phase X2 (current), reverse relations SHOULD be written manually until X3 tooling lands.

REQ-REL-004 Event forward relation が対応 reverse を欠くと、 link-check tooling が broken-reverse violation を報告する (Phase X3+)。

REQ-REL-004: WHEN a forward relation lacks its corresponding reverse relation in Phase X3+, the link-check tooling SHALL report a broken-reverse violation (具体的な CLI 構文・実装機構は folio-self-spec.html §7 系に集約)。

folio relations

§0. Reader's Guide

§1. W3C Standard Vocabulary

§1.1 Dublin Core Terms (DCMI)

§1.2 schema.org (補完)

§1.3 PROV-O (履歴・派生)

§2. folio Custom Vocabulary

§2.1 folio 独自語彙 (規範定義)

§2.2 命名規則 (standard 優先原則)

§3. JSON-LD Schema in `<head>`

§3.1 Minimal Example (関係性なし)

§3.2 Full Example (関係性込み)

§3.3 `@id` Resolution Rules

§3.4 Conformance Level (Phase 1)

§4. Inventory Schema

§4.1 inventory.json Structure

§4.2 Three-Tier Progressive Disclosure Model

例: folio specs の 3-tier mapping

§4.3 Auto-Generation Timing

§4.4 Input / Output Behavior

§4.4.1 Scan target directories

§4.4.2 Output path

§4.4.3 Failure mode

§5. Bidirectional Reference

§5.1 双方向 dual の対象関係

§5.2 Precedent (log4brains pattern)

§5.3 EARS 規範要件

§6. References

§0. Reader's Guide

§1. W3C Standard Vocabulary

§1.1 Dublin Core Terms (DCMI)

§1.2 schema.org (補完)

§1.3 PROV-O (履歴・派生)

§2. folio Custom Vocabulary

§2.1 folio 独自語彙 (規範定義)

§2.2 命名規則 (standard 優先原則)

§3. JSON-LD Schema in <head>

§3.1 Minimal Example (関係性なし)

§3.2 Full Example (関係性込み)

§3.3 @id Resolution Rules

§3.4 Conformance Level (Phase 1)

§4. Inventory Schema

§4.1 inventory.json Structure

§4.2 Three-Tier Progressive Disclosure Model

例: folio specs の 3-tier mapping

§4.3 Auto-Generation Timing

§4.4 Input / Output Behavior

§4.4.1 Scan target directories

§4.4.2 Output path

§4.4.3 Failure mode

§5. Bidirectional Reference

§5.1 双方向 dual の対象関係

§5.2 Precedent (log4brains pattern)

§5.3 EARS 規範要件

§6. References

§3. JSON-LD Schema in `<head>`

§3.3 `@id` Resolution Rules