From d68d60a62aa5ab230bbf55a78da4523c41b048ce Mon Sep 17 00:00:00 2001 From: NIAOJIANG <47109379+LearnerHong@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:34:09 +0800 Subject: [PATCH 1/2] okf: allow extensible bundle-root frontmatter Define optional bundle title/description descriptors and clarify conformance, versioning, and the v0.1 delta. --- okf/SPEC.md | 48 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/okf/SPEC.md b/okf/SPEC.md index a516d501..7b6fbde6 100644 --- a/okf/SPEC.md +++ b/okf/SPEC.md @@ -507,8 +507,26 @@ disclosure**: letting a human or agent see what is available before opening individual documents. Index files contain no frontmatter, with one exception: a bundle-root -`index.md` MAY carry an `okf_version` key (§12). The body uses one or more -sections, each grouping concepts under a heading: +`index.md` MAY carry a YAML frontmatter block. The following optional fields +are defined for that block: + +- `okf_version`: The OKF version targeted by the bundle (§12). +- `title`: A human-readable display name for the bundle. +- `description`: A single sentence summarizing the bundle's scope and when a + consumer should consult it. + +The bundle-root frontmatter MAY also contain additional producer-defined +key/value pairs. Consumers MUST tolerate unknown keys and SHOULD preserve them +when round-tripping. + +`title` and `description` form a compact **bundle descriptor**. They describe +a bundle as a whole rather than an individual concept. This enables +progressive disclosure across multiple bundles: a consumer MAY inspect +available descriptors to select relevant bundles before reading an index body +or any concept document. This guidance does not prescribe how bundles are +enumerated, identified, stored, or transported. + +The body uses one or more sections, each grouping concepts under a heading: ```markdown # Section / Group Heading @@ -526,7 +544,6 @@ frontmatter. Producers MAY generate `index.md` automatically; consumers MAY synthesize one on the fly when none is present. --- - ## 9. Log files A `log.md` file MAY appear at any level of the hierarchy to record the @@ -736,7 +753,7 @@ A bundle is **conformant** with OKF v0.2 if: 1. Every non-reserved `.md` file in the tree contains a parseable YAML frontmatter block. -2. Every frontmatter block contains a non-empty `type` field. +2. Every concept frontmatter block contains a non-empty `type` field. 3. Every reserved filename (`index.md`, `log.md`) follows the structure in §8 and §9 respectively when present. @@ -752,14 +769,13 @@ present, producers SHOULD follow §5 through §10, and consumers: Consumers SHOULD treat all other constraints as soft guidance. In particular, consumers MUST NOT reject a bundle because of: -- Missing optional frontmatter fields. +- Missing optional frontmatter fields, including bundle descriptor fields. - Unknown `type` values. - Unknown additional frontmatter keys. - Broken cross-links. - Missing `index.md` files. --- - ## 12. Versioning This document specifies OKF version **0.2**. Revisions are versioned as @@ -770,11 +786,11 @@ This document specifies OKF version **0.2**. Revisions are versioned as - A **major** version bump may make breaking changes (renaming required fields, changing reserved filenames). -Bundles MAY declare the version they target with `okf_version: "0.2"` in a -bundle-root `index.md` frontmatter block (the only place frontmatter is -permitted in an `index.md`). Consumers that do not understand the declared -version SHOULD attempt best-effort consumption rather than refusing the -bundle. +Bundles MAY declare the version they target with `okf_version: "0.2"` in the +bundle-root `index.md` frontmatter block described in §8. The bundle-root +`index.md` is the only index file in which frontmatter is permitted. Consumers +that do not understand the declared version SHOULD attempt best-effort +consumption rather than refusing the bundle. ### Considered and deferred @@ -789,7 +805,6 @@ The following are intentionally left to a future revision: shifts from SQL equality to model-and-binding equality. --- - ## 13. Changes from v0.1 v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for @@ -810,12 +825,14 @@ the fallbacks noted here. ### 13.2 Additive changes All of the following are additive: new optional keys, one new concept -type, and one new conventional heading. Their absence yields a plain v0.1 -concept. +type, and one new conventional heading. Omitting them leaves the corresponding +v0.1 structures unchanged. - New frontmatter families: `sources` with its per-source credibility signals (`author`, `usage_count`, `last_modified`) and the `usage_window` sibling; `generated`, `verified`; `status`, `stale_after` (§5). +- Bundle-root `index.md` frontmatter may include additional producer-defined + keys and the optional `title` and `description` bundle descriptors (§8). - New concept type `Attested Computation` and its computation keys `runtime`, `parameters`, `computation`, `executor`, `attester` (§10). - New conventional body heading `# Computation` (§4.2). @@ -823,11 +840,10 @@ concept. Everything else (bundle structure, reserved filenames, the required `type`, recommended `title`/`description`/`resource`/`tags`, cross-linking, -index files, log files, permissive conformance) is carried forward +index-file bodies, log files, permissive conformance) is carried forward unchanged. --- - ## Appendix A: Worked example, an income statement One bundle exercising every family, shown as a v0.1 to v0.2 migration of an From aec44d8bcfbf8edc86f35f706197a263c0f60e17 Mon Sep 17 00:00:00 2001 From: NIAOJIANG <47109379+LearnerHong@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:35:57 +0800 Subject: [PATCH 2/2] docs: preserve section spacing --- okf/SPEC.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/okf/SPEC.md b/okf/SPEC.md index 7b6fbde6..08ef410b 100644 --- a/okf/SPEC.md +++ b/okf/SPEC.md @@ -544,6 +544,7 @@ frontmatter. Producers MAY generate `index.md` automatically; consumers MAY synthesize one on the fly when none is present. --- + ## 9. Log files A `log.md` file MAY appear at any level of the hierarchy to record the @@ -776,6 +777,7 @@ particular, consumers MUST NOT reject a bundle because of: - Missing `index.md` files. --- + ## 12. Versioning This document specifies OKF version **0.2**. Revisions are versioned as @@ -805,6 +807,7 @@ The following are intentionally left to a future revision: shifts from SQL equality to model-and-binding equality. --- + ## 13. Changes from v0.1 v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for @@ -844,6 +847,7 @@ index-file bodies, log files, permissive conformance) is carried forward unchanged. --- + ## Appendix A: Worked example, an income statement One bundle exercising every family, shown as a v0.1 to v0.2 migration of an