Bundles & concepts

LOKF keeps OKF’s authoring model intact: a knowledge bundle is a directory tree of markdown files, each file describing one concept with a small YAML frontmatter block. Everything here is readable with cat and diffable in git.

Bundle structure

Identical to OKF §3. index.md and log.md remain reserved; distribution as a git repo is recommended. LOKF adds optional keys to the bundle-root index.md frontmatter — the one place OKF already permits frontmatter in an index:

index.md (bundle root)

---
lokf_version: "0.2"          # LOKF version this bundle targets
okf_version: "0.2"           # OKF version it remains compatible with
base_iri: https://acme.example/knowledge/     # resolves Concept IDs to Concept IRIs
context: https://w3id.org/lokf/context.jsonld # the @context to attach to concepts
title: Acme Knowledge Bundle
description: Canonical, agent-readable knowledge for Acme's data org.
license: https://creativecommons.org/licenses/by/4.0/
publisher:
  type: Organization
  id: https://acme.example
  name: Acme Corp
---

Plain OKF consumers are unaffected

A consumer that ignores these keys sees a perfectly ordinary OKF bundle. A semantic consumer uses base_iri + context to lift the whole bundle into RDF.

Concept documents

Every concept is a UTF-8 markdown file: a YAML frontmatter block followed by a markdown body, exactly as in OKF. LOKF specifies what the frontmatter keys mean by mapping each to an RDF property.

Core frontmatter fields

type is the only required field (as in OKF). All others are optional.

Field	OKF	RDF property (slot_uri)	Range	Notes
type	✅	rdf:type (via @type)	class	Required. Names a LOKF class (§6).
id		@id (subject)	IRI	Concept IRI. Defaults to base_iri + Concept ID.
title	✅	schema:name	string	close: dcterms:title, rdfs:label
description	✅	schema:description	string	close: dcterms:description
resource	✅	schema:url	IRI	The underlying asset. close: dcat:landingPage, prov:specializationOf
tags	✅	schema:keywords	string*	close: dcat:keyword
timestamp	✅	schema:dateModified	dateTime	exact: dcterms:modified. Superseded in v0.2 by generated.at (§5.4); consumers MAY fall back.
created		schema:dateCreated	dateTime	exact: dcterms:created
version		schema:version	string
license		schema:license	IRI
author		schema:author	Agent*	close: dcterms:creator, prov:wasAttributedTo
genre		schema:genre	enum	Diátaxis documentation mode of the body (§6.1). DiataxisMode: tutorial | how-to | reference | explanation.
body	✅	schema:text	string	The markdown after the frontmatter.
citations		schema:citation	Citation*	Superseded in v0.2 by sources (§5.4); still parsed for v0.1 docs.
additionalType		schema:additionalType	string	The producer’s type when it names no LOKF class (§8). Written by the RDF projection, not by authors.

(* = multivalued.)

Permissive by design

Producers MAY add any other keys; consumers MUST preserve unknown keys and MUST NOT reject documents that carry them (OKF §4.1). Missing optional fields, unknown type values, and broken cross-links MUST NOT cause rejection either.

Trust, provenance, and lifecycle (OKF v0.2)

OKF v0.2 adds optional frontmatter families answering “where did this come from”, “how much should I trust it”, and “is it still current”. LOKF binds each to a formal vocabulary, so a trust signal is queryable RDF rather than YAML a consumer has to interpret:

Field	OKF v0.2	RDF property (slot_uri)	Range	Notes
sources	✅	schema:isBasedOn	Source*	close: dcterms:source, prov:wasDerivedFrom (primary IRI is owned by derivedFrom).
usage_window	✅	lokf:usageWindow	UsageWindow	{from, to} → dcat:startDate/dcat:endDate on a dcterms:PeriodOfTime. Sibling of sources; a Source entry MAY override.
generated	✅	prov:wasGeneratedBy	Generation	{by, at} → prov:wasAssociatedWith + prov:endedAtTime on a prov:Activity. Supersedes timestamp.
verified	✅	lokf:verified	Verification*	Each {by, at} a lokf:Verification (⊑ prov:Activity). A bare mapping MUST be read as a one-element list.
status	✅	schema:creativeWorkStatus	enum	draft | stable | deprecated; absent ⇒ stable. Enum meanings: ADMS status IRIs.
stale_after	✅	schema:expires	dateTime	The instant from which the concept is stale (OKF §5.5). A bare YYYY-MM-DD means that day at 00:00:00Z.

All of them are optional, and their absence carries meaning: an unverified concept is distinguishable, never rejected. generated supersedes timestamp, and sources supersedes citations; both older fields are still parsed. See SPEC §5.4 for the Source entry fields and the attested-computation contract.

Body

Unchanged from OKF §4.2. Standard markdown, structural headings preferred. The conventional headings # Schema, # Examples, and # Citations retain their OKF meaning (v0.2 adds # Computation). The body is mapped to schema:text in the RDF projection.

Next

• Give links meaning with typed relationships.
• Pick the right class from the type vocabulary.