Sources & provenance

OKF defines two, coexisting ways to record where a claim came from.

# Citations (v0.1, required when citing)

Official OKF specification requirement

When a concept's body makes claims based on external material, those sources MUST be listed under a # Citations heading at the end of the document, numbered.

# Citations

[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/...)
[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)

A claim in the body references an entry with a bare [1] marker. Citation links may be absolute URLs, bundle-relative paths, or paths within a references/ subdirectory that mirrors external material as first-class OKF concepts.

sources: + footnotes (v0.2 trust layer)

v0.2 adds an optional, richer alternative: a sources: frontmatter array, joined to claims in the body via matching identifiers and Markdown footnotes.

---
type: Metric
sources:
  - id: docs
    resource: https://example.com/docs
    title: Documentation
    last_modified: "2026-07-25"
---

This statement came from the source.[^docs]

[^docs]: Documentation

The footnote reference [^docs] matches the source id: docs. The Provenance Inspector checks both mechanisms in both directions — citation numbers against # Citations entries, and footnotes against sources[].id.

OKF Tools recommendation

Missing provenance is a quality observation, never an OKF conformance error. A concept with no sources or citations is still valid OKF — it's just less trustworthy for downstream consumers, which is why the Trust Analyzer and Provenance Inspector are separate, optional layers.

What gets flagged

A [N] reference in the body with no matching # Citations entry, or vice versa.
A footnote citing a source ID that isn't declared in frontmatter, or vice versa.
Duplicate source IDs or duplicate citation numbers within one concept.
Invalid last_modified dates or malformed usage_window values.