Scope

Use this page to check which Open Knowledge Format behavior Superbee reads, authors, validates, and preserves. It describes the current stable release against OKF v0.2 at revision 4bc03b7.

OKF defines the portable Markdown and YAML format. Superbee adds authoring, querying, validation, concurrency, Kinds, recipes, and presentation. A valid OKF bundle does not require Superbee, and a Superbee extension remains an ordinary producer-defined frontmatter field unless this page says otherwise.

Edition support

The root declaration must be a non-empty YAML string. Use okf_version: '0.2'; an unquoted YAML number is not recognized as the edition by the stable parser.

Initialization supports only 0.1 and 0.2. Reopening an existing bundle leaves its root index.md unchanged. Changing that one file does not migrate the documents, Kinds, saved queries, or View code within the bundle.

Bundle structure and reserved files

An OKF bundle is a directory tree. Every non-reserved .md file is a concept document. Its concept ID is the bundle-relative path with the final .md removed. For example, evidence/launch-probe.md has ID evidence/launch-probe.

Superbee recognizes the two OKF reserved filenames at every directory level:

Superbee separates reserved files from concept documents. The stable health report does not perform a complete structural validation of every index.md or log.md body against the OKF specification.

OKF includes non-reserved Markdown beneath dot-prefixed files and directories. Superbee's filesystem discovery deliberately skips every dot-prefixed path segment. Such concepts are absent from list, query, graph projections, and status, even though another OKF consumer may include them. Keep portable concepts on visible paths when Superbee must discover them.

Concept IDs entering the core must be canonical and bundle-relative. They use forward slashes and reject absolute paths, . or .. segments, duplicate slashes, trailing slashes, and a non-final path segment ending in .md. CLI entry points can accept a file-like spelling and normalize it before the canonical identity reaches storage.

Concept documents

Every conformant concept document is UTF-8 Markdown with a YAML frontmatter block. OKF v0.2 always requires a non-empty type; all other standard fields are optional.

Stable Superbee enforces a non-empty string type on writes. It tolerates unknown type values and preserves producer-defined frontmatter keys. A missing or malformed optional OKF family does not make an otherwise readable document disappear, although malformed YAML is reported and skipped by whole-bundle queries such as status.

The Markdown body has no required OKF sections. A bundle-owned Kind may impose additional fields, enumerated values, headings, or relationship expectations for documents of one type. Those Kind rules are Superbee conventions layered on the portable document.

Standard v0.2 metadata

When generated is newly supplied through the governed mutation path, generated.by must use human:<id>, process:<id>, or <producer>/<version>. On document creation, a supplied generated.at must be a string accepted by JavaScript Date.parse. This check is looser than OKF's requirement for an explicit UTC offset. Existing-document mutation advances or preserves the clock instead of separately validating a candidate spelling. Use the official timestamp grammar when authoring portable metadata. Imported metadata is consumed permissively: unknown keys and unusual legacy actor spellings remain available instead of being silently discarded.

Superbee records its advisory mutation attribution separately. In v0.2, --actor can persist superbee_updated_by; it does not replace the provenance actor in generated.by.

Superbee preserves a bare verified mapping as supplied. Code that derives the OKF trust tier must apply the specification's rule that a bare mapping is equivalent to a one-element list.

Links and relationships

OKF relationships are standard Markdown links in the body. Superbee resolves both supported forms:

[Root-relative release evidence](/sources/current-release.md)
[Relative release evidence](../sources/current-release.md)

The stored link is directed from the current document to the target concept. Superbee derives backlinks from those bodies and does not store a second edge database. Links to missing concepts remain valid unresolved relationships, consistent with OKF's allowance for not-yet-written knowledge.

External URLs, mailto: links, in-page anchors, non-Markdown targets, image links, and links to reserved index.md or log.md files do not become concept edges. Link text carries the relationship meaning; Kinds may add a typed relationship vocabulary without changing the stored Markdown form.

The derived edge and backlink graph recognizes inline [text](href) body links whose href contains no whitespace. Reference-style Markdown links and path-valued frontmatter such as sources[].resource, computation, executor.resource, and attester.resource remain preserved data but do not become graph edges. The graph is therefore a bounded Superbee projection rather than a complete projection of every OKF relationship-bearing value.

Validation boundaries

superbee status is a read-only bundle health report. It reports malformed YAML, Kind conformance, unresolved links, freshness, graph expectations, View registration problems, and relevant legacy findings. Findings do not make the command fail after the analysis completes.

The stable release is a permissive OKF consumer. It does not claim a complete schema validator for every optional sources, verified, lifecycle, or attested-computation field. Use the official OKF specification when producing those families, and preserve unknown fields when integrating another producer's bundle.

Attested Computation fields are parsed, preserved, queried, and transported as producer frontmatter. Stable Superbee does not execute computations, run attesters, validate receipts, or derive attestation verdicts.

Superbee's authoring paths add stricter rules where they own a mutation:

• generic writes require a non-empty type;

• a Kind-aware new operation validates the declared Kind strictly;

• generic writes can warn or use --strict when a Kind governs the type;

• compare-and-swap versions protect a write from replacing a newer document; and

• unsupported authoring editions are rejected before a new bundle is created.

Normalization and byte behavior

Superbee reads local document bytes as UTF-8, parses YAML frontmatter, and keeps YAML date and date-time scalars as strings so a date-only value such as 2026-07-27 does not become a midnight timestamp. The legacy top-level timestamp field is normalized to an ISO 8601 string when the YAML parser identifies it as a timestamp.

A document mutation serializes the parsed frontmatter and Markdown body into Superbee's canonical form. Unknown values remain semantically present, but YAML comments, quoting choices, spacing, key order, and other source formatting are not a byte-preservation promise. Read-only query and transport probes do not rewrite the source bundle.

The core document store does not declare an OKF document-size maximum in the stable release. Bounded presentation channels have separate limits:

These presentation limits do not shorten the stored document. A rendered view that reports bounded: true is incomplete and should not be used as a full-fidelity export.

v0.1 compatibility and migration

OKF v0.2 supersedes the v0.1 timestamp clock with generated.at and the body # Citations list with sources. Both v0.2 families are optional, so imported v0.1 content remains readable. Superbee's v0.1 write policy supplies a top-level timestamp when it is missing. The v0.2 policy does not invent timestamp, sources, or verified.

The largest field collision is workflow progress. OKF v0.2 owns top-level status for the draft | stable | deprecated lifecycle. Superbee exposes the logical field name progress_status for a Kind that declares the edition-specific storage coordinate:

The alias is declaration-driven. It applies only when the document's governing Kind declares the physical workflow field, and it never reclassifies a v0.2 lifecycle status value as workflow progress.

Before changing a v0.1 bundle's root edition:

1. Commit or back up the bundle.

2. Run superbee status and inspect okf_upgrade.

3. Move Kind-governed workflow fields from physical status to superbee_progress_status, while continuing to use the logical progress_status interface.

4. Audit ungoverned documents, saved queries, and View code separately; the current finding cannot infer their intended use of status.

5. Decide whether legacy timestamp and # Citations content should be expressed through generated and sources.

6. Change the root okf_version only after all dependent surfaces agree.

7. Run superbee status again and exercise the workflows and Views that depend on the migrated fields.

Stable Superbee does not perform this multi-document edition migration automatically. Continue to use a v0.1 bundle when the audit is incomplete.

Related

Evidence

• Official OKF v0.2 specification at 4bc03b7

• Stable bundle engine

• Stable frontmatter parser

• Stable v0.2 mutation policy

• Stable concept identity and reserved-file rules

• Stable link resolver

• v0.2 read compatibility tests

• v0.2 write contract tests

• Workflow progress compatibility tests

• Stable status implementation

• Stable document-read implementation