This is a complete reading edition of the normative original specification, pinned to repository revision 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. The upstream instant-profile revision is 0b87c52c6ef999286c745e19998fdfcd03d5dbee, SHA-256 26aa5da029278939f914e578107242d9607d4f2dc5fe153272b82f9ed1030101. Navigation and stable section anchors are added for reading; the specification is not revised. The Russian translation is informative.

This is the instant-0b87c52 temporal profile: stale_after is an absolute timestamp. The date profile, pinned upstream at 3fcbb9f828c2f23d109c855ee403c3a4c81f3a96, is a separate revision also called OKF 0.2.

Open Knowledge Format (OKF)

Version 0.2

OKF is an open, human- and agent-friendly format for representing knowledge: the metadata, context, and curated insight that surrounds data and systems. It is designed to be authored by people, generated by agents, exchanged across organizations, and consumed by both.

The format is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.

This document is self-contained: it specifies everything needed to produce and consume OKF v0.2. A summary of what changed from v0.1 is in §13.

1. Motivation

The space of knowledge representation for AI agents is evolving quickly, and many incompatible conventions are emerging. OKF takes the position that knowledge is best represented in commonly accessible, established formats that are:

Increasingly, a knowledge corpus is not authored once and then read: it is continuously written and maintained by agents. When most concepts are machine-generated, a consumer needs answers that a plain markdown-plus-frontmatter convention does not make first-class:

  1. What was this created from, and how was it verified? (provenance)
  2. How much should I trust it? (trust)
  3. Is it still true? (freshness)
  4. Is it the current version? (lifecycle)
  5. Was this number produced the way we said it must be? (attestation)

OKF v0.2 makes provenance, trust, lifecycle, and attestation first-class while keeping the format minimally opinionated. The format is minimally opinionated. It standardizes only the small set of structural conventions needed to make a knowledge corpus self-describing — anything beyond that is left to the producer.

Goals

  1. Define a universal format that producers (people, agents, export pipelines) can write into.
  2. Inform how consumers (agents, UIs, search indexes, deterministic code) should read and traverse it.
  3. Facilitate exchange of knowledge across systems and organizations.
  4. Standardize the small set of frontmatter fields that make an agent-maintained corpus trustable, without prescribing any runtime.

Non-goals

2. Terminology

3. Bundle structure

A bundle is a directory tree of markdown files. The directory structure is independent of the domain: producers organize concepts however makes sense for the knowledge being captured.

path/to/bundle/
  index.md                      # Optional. Directory listing for progressive disclosure.
  log.md                        # Optional. Chronological history of updates.
  <concept>.md                  # A concept at the bundle root.
  <subdirectory>/               # Subdirectories organize concepts into groups.
    index.md
    <concept>.md
    <subdirectory>/
      ...

A bundle MAY be distributed as:

3.1 Reserved filenames

The following filenames have defined meaning at any level of the hierarchy and MUST NOT be used for concept documents:

Filename Purpose
index.md Directory listing. See §8.
log.md Update history. See §9.

All other .md files are concept documents.

Tags remain a first-class concept through the tags frontmatter field (§4.1). OKF does not specify a separate file format for aggregating documents by tag; a consumer that wants a tag-browsing view can synthesize one at consumption time by scanning frontmatter.

4. Concept documents

Every concept is a UTF-8 markdown file with two parts:

  1. A YAML frontmatter block, delimited by --- on its own line at the start of the file and a closing --- on its own line.
  2. A markdown body, containing free-form content.

4.1 Frontmatter

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, ...]          # Optional
# ... trust, lifecycle, provenance, and computation families (see §5, §10)
# ... other producer-defined key/value pairs
---

Required:

type is the only always-required key; a concept carrying just type is fully conformant (§11).

Recommended:

The optional provenance, trust, and lifecycle families (§5) and the computation fields for Attested Computation concepts (§10) may also appear.

Extensions: Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys when round-tripping and MUST NOT reject documents with unrecognized fields.

4.2 Body

The body is standard markdown. Producers SHOULD favor structural markdown (headings, lists, tables, fenced code blocks) over freeform prose, since structure aids both human reading and agent retrieval.

There are no required body sections. The following headings have conventional meaning and SHOULD be used when applicable:

Heading Purpose
# Schema Structured description of an asset’s columns/fields.
# Examples Concrete usage examples, often as fenced code blocks.
# Computation The sanctioned computation of an Attested Computation. See §10.

Per-claim attribution to external sources uses markdown footnotes keyed to sources entries rather than a body citations list (§5.1).

4.3 Example: a concept bound to a resource

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in US dollars.               |
| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

4.4 Example: a concept not bound to a resource

---
type: Playbook
title: "Incident response: data freshness alert"
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
generated: { by: human:ahormati, at: 2026-04-12T09:00:00Z }
---

# Trigger

A freshness alert fires when `orders` lags more than 30 minutes behind its
expected SLA. See the [orders table](/tables/orders.md).

# Steps

1. Check the [ingestion job dashboard](https://example.com/dash).
2. ...

5. Provenance, trust, and lifecycle

These frontmatter families make “where did this come from,” “how much should I trust it,” and “is it still current” answerable from frontmatter. All are optional. Their absence carries meaning: an unverified concept is distinguishable from a verified one, but is never rejected (§11).

Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit UTC offset, for example 2026-06-30T14:00:00Z.

5.1 Provenance: sources

sources records the materials a concept derives from, external or internal to the bundle.

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema
    author: team:ga4-docs
    usage_count: 5000
    last_modified: 2026-05-30T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }

Each sources entry:

Source credibility signals. OKF records objective, per-source signals so a consumer can judge how much to trust a concept by judging the sources it was extracted from. It does not store a credibility score: a score is subjective, unportable across consumers, and goes stale. Credibility is inferred from the signals, the same way trust tiers are (§5.3), not stored. Each signal is optional and lives on a sources entry:

usage_count is a coarse signal. It is comparable at the alive-versus-dead and order-of-magnitude level, and against a source’s own history over time, but not as a precise cross-kind ranking: a scheduled query’s executions and a human’s deliberate dashboard views do not carry equal weight. Consumers SHOULD read it as liveness and trend, not as a score.

Lineage is expressed through links, not a dedicated field. When a resource points at another OKF concept, the derivation edge already exists in the bundle graph (§6), so a consumer MAY recurse into that source’s own sources and let credibility propagate. External leaf sources carry only their intrinsic signals. Deeper lineage (an explicit external derived_from, or data lineage) is out of scope for v0.2.

Per-claim attribution. To attribute a specific claim, use a markdown footnote whose label is a sources[].id:

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema

The footnote label is the join key into sources; consumers resolve attribution through the matching entry, not by parsing the footnote prose. Labels are keyed rather than positional (sources[0]) because agents constantly rewrite these documents: a positional index misattributes silently the moment the list is reordered, whereas a stable id survives reordering.

5.2 Trust: generated and verified

generated records how the current content was produced. verified records who or what has confirmed the content against its sources or resource. They are kept distinct because who wrote a concept need not be who confirmed it.

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }

verified:
  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }

verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }

5.3 Trust tiers

Consumers derive a trust tier from verified, lowest to highest:

A concept with no trust frontmatter is still consumable; consumers MUST NOT reject it (§11). Trust tiers are advisory signals, not access control.

5.4 Lifecycle: status

status: stable        # draft | stable | deprecated

Absent status ⇒ stable.

5.5 Lifecycle: stale_after

stale_after: 2026-09-23T00:00:00Z   # content is stale on/after this instant

Optional. An absolute instant. A concept is stale when now >= stale_after. An absolute instant, not a relative TTL, keeps the staleness decision a plain comparison with no reference to when the concept was read.

6. Cross-linking and paths

Concepts MAY link to other concepts using standard markdown links. Two forms are supported:

A link from concept A to concept B asserts a relationship. The specific kind (parent/child, references, joins-with, depends-on) is conveyed by the surrounding prose, not by the link itself. Consumers that build a graph view typically treat all links as directed edges of an untyped relationship.

Consumers MUST tolerate broken links: a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge.

6.2 Path-valued fields

Several fields name a path or URI: resource, sources[].resource, computation, executor.resource, and attester.resource (§10). A sources[].resource may instead be a scope descriptor (§5.1), in which case it is not a path. Each path-valued field accepts:

6.3 The references/ convention

A references/ subdirectory conventionally mirrors external material, run instructions, or code as first-class concepts within the bundle. Sources, executors, and attesters commonly point into it (for example references/attesters/revenue.py). It is a naming convention, not a requirement.

7. Actor convention

Fields that record an identity (generated.by, verified[].by) use a single actor convention:

Consumers that classify trust (§5.3) key off the human: prefix, so producers MUST use it for hand-authored or human-confirmed content.

8. Index files

An index.md file MAY appear in any directory, including the bundle root. It enumerates the directory’s contents to support progressive 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:

# Section / Group Heading

* [Title 1](relative-url-1) - short description of item 1
* [Title 2](relative-url-2) - short description of item 2

# Another Section

* [Subdirectory](subdir/) - short description of the subdirectory

Entries SHOULD include the description from the linked concept’s 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 history of changes to that scope. The format is a flat list of date-grouped entries, newest first:

# Directory Update Log

## 2026-05-22
* **Update**: Added a BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

## 2026-05-15
* **Initialization**: Created foundational directory structure.

Date headings MUST use ISO 8601 YYYY-MM-DD form. Log entries are prose; the leading bold word (**Update**, **Creation**, **Deprecation**) is a convention, not a requirement.

10. Attested computations concept

An Attested Computation concept carries not just what a value means but a sanctioned way to compute it, so a consumer can confirm the agent ran the blessed computation instead of improvising its own. Provenance (§5.1) answers “where did this claim come from”; attestation answers “was this number produced the way we said it must be.” OKF records the computation and the means to check it; it does not execute anything itself.

10.1 A computation is its own concept

A sanctioned computation is a standalone concept of type: Attested Computation. A concept that needs the value (a Metric, a BigQuery Table) links to it with a normal markdown link (§6). Three properties motivate the standalone concept:

10.2 Contract fields

The contract is the concept’s top-level frontmatter. In addition to the provenance, trust, and lifecycle families (§5), an Attested Computation concept carries:

What sits behind a resource (a Skill, a script, a container) is a packaging choice; OKF fixes the interface, not the packaging (§1).

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy

10.3 The computation

Provide the computation in one of two ways:

runtime: bigquery
computation: references/computations/lib/revenue.sql
parameters:
  - { name: year, type: integer, required: true }

The agent MAY only supply values for the declared parameters; it MUST NOT author or edit the computation. Binding computation with the parameter values into the executable artifact is the consumer’s job, and the attester independently re-derives that same binding to compare against what actually ran. Because the comparison is on the expanded, compiled artifact the receipt carries (executed_sql, compiled_sql), a rewritten query, a swapped computation file, or a mutated dependency fails the check. A typed, parameter-only surface is what makes “did the sanctioned thing run” a mechanical comparison rather than a judgement call.

10.4 Concepts that use a computation

A document is rarely a single computation. An income-statement overview that discusses revenue, profit, and margin stays one readable concept and links to one Attested Computation per figure:

---
type: Metric
title: Revenue
description: Recognized revenue for a fiscal year.
tags: [finance, revenue]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
---

# Definition

Recognized revenue sums `amount` over rows booked to the fiscal year,
computed by [the revenue computation](../computations/revenue.md).

Because each computation is its own concept, revenue can be fresh while profit is past its stale_after, and each attests on its own run. Co-locating them is a directory choice (a computations/ folder with an index.md), not a frontmatter one.

10.5 How a consumer uses it (informative)

This subsection is informative, not normative. The runtime artifacts below are not stored in the bundle.

  1. Discover via type: Attested Computation, a frontmatter signal liftable into index.md; a consumer reaches one directly or by following a link from a concept that uses it.
  2. Load the contract from frontmatter and the computation from the body (or the file named by computation).
  3. Parameterize: the agent supplies values for the declared parameters.
  4. Execute: the executor runs the bound computation and returns a receipt shaped by executor.receipt.
  5. Attest: the consumer runs the attester over the receipt. It confirms provenance (the computation that ran equals computation bound with the claimed parameters, not agent-authored SQL) and fidelity (the displayed value matches the receipt’s authoritative source, re-read by job id rather than taken from the agent’s text).
  6. Gate: refuse to display a failing attestation; warn or refuse when now >= stale_after. On success, surface the verdict (for example a link to the job log) so trust is visible.

10.6 Verification versus attestation

verified (§5.2) and attestation are distinct, and both exist:

A concept with a stale definition can still attest cleanly, and a freshly-verified definition still requires attestation on each run, which is why both are needed.

11. Conformance

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.
  3. Every reserved filename (index.md, log.md) follows the structure in §8 and §9 respectively when present.

When the trust, lifecycle, provenance, or computation families are 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:

12. Versioning

This document specifies OKF version 0.2. Revisions are versioned as <major>.<minor>:

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.

Considered and deferred

The following are intentionally left to a future revision:

13. Changes from v0.1

v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for two deliberate breaking changes called out below because they rename or retire v0.1 fields. A v0.1 bundle is consumable by a v0.2 consumer under the fallbacks noted here.

13.1 Breaking changes

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.

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 unchanged.

Appendix A: Worked example, an income statement

One bundle exercising every family, shown as a v0.1 to v0.2 migration of an income statement with two figures, revenue and gross profit.

v0.1 form

A single doc: both figures in one concept, the SQL in prose an agent can read, ignore, or rewrite, citations a flat list, and the only timestamp is timestamp.

---
type: Metric
title: Income statement (fiscal year)
description: Headline income-statement figures for a fiscal year.
tags: [finance, income-statement]
timestamp: '2026-05-28T22:53:05+00:00'
---

# Definition
The income statement reports revenue and gross profit for a fiscal year.

# Revenue
Recognized revenue sums `amount` over rows booked to the fiscal year:

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = <year>

# Gross profit
Gross profit by segment, per the cost-allocation standard:

    SELECT gross_profit FROM fct_income_statement
    WHERE fiscal_year = <year> AND segment = <segment>

# Citations
- https://wiki.acme/finance/fpa-handbook
- https://wiki.acme/finance/revenue-recognition
- https://wiki.acme/finance/cost-allocation

v0.2 form

The two figures split into attested computations linked from a narrative concept. Every family is populated, and the two computations sit in deliberately different states so one consumer reaches two verdicts.

bundles/finance/
  metrics/income-statement.md      type: Metric  (narrates, links both)
  computations/revenue.md          type: Attested Computation  (runtime: bigquery)
  computations/profit.md           type: Attested Computation  (runtime: dbt)
  references/skills/run-on-bq.md, run-dbt.md
  references/attesters/sql-equality.py, dbt-binding.py

metrics/income-statement.md, the readable doc; trust lives on what it links, not here:

---
type: Metric
title: Income statement (fiscal year)
description: Headline income-statement figures for a fiscal year.
tags: [finance, income-statement]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: fpa-handbook
    resource: https://wiki.acme/finance/fpa-handbook
    title: FP&A reporting handbook
---

# Definition
The income statement reports [revenue](../computations/revenue.md) and
[gross profit](../computations/profit.md) for a fiscal year, per the FP&A
reporting handbook.[^fpa-handbook] Each figure is produced by a sanctioned,
attestable computation; this concept only narrates them.

[^fpa-handbook]: FP&A reporting handbook

computations/revenue.md, BigQuery SQL, human-verified, fresh, and corroborated by a live dashboard source carrying credibility signals:

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
tags: [finance, revenue]
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/sql-equality.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-28T14:00:00Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
    author: team:finance-fpa
    last_modified: 2026-04-02T00:00:00Z
  - id: exec-rev-dash
    resource: dashboards/exec-revenue
    title: Executive revenue dashboard
    author: team:finance-fpa
    usage_count: 5000
    last_modified: 2026-06-18T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

Recognized revenue per the recognition policy,[^rev-policy] corroborated by
the executive revenue dashboard.[^exec-rev-dash]

[^rev-policy]: Revenue recognition policy
[^exec-rev-dash]: Executive revenue dashboard

computations/profit.md, a dbt model, process-verified, and past its stale_after:

---
type: Attested Computation
title: Gross profit for fiscal year
description: Gross profit by segment for a fiscal year, per the cost-allocation standard.
tags: [finance, profit]
status: stable
runtime: dbt
parameters:
  - { name: year, type: integer, required: true }
  - { name: segment, type: string, required: true }
executor:
  resource: references/skills/run-dbt.md
  receipt: [run_id, compiled_sql, result]
attester:
  resource: references/attesters/dbt-binding.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-14T14:00:00Z }
verified: { by: process:finance-nightly, at: 2026-06-12T08:00:00Z }
stale_after: 2026-06-15T00:00:00Z
sources:
  - id: cost-alloc
    resource: https://wiki.acme/finance/cost-allocation
    title: Cost allocation standard
---

# Computation

    SELECT gross_profit
    FROM {{ ref('fct_income_statement') }}
    WHERE fiscal_year = {{ var('year') }}
      AND segment = {{ var('segment') }}

Gross profit by segment per the cost-allocation standard.[^cost-alloc]

[^cost-alloc]: Cost allocation standard