Linked Open Knowledge Format (LOKF)

A semantic profile of Google's Open Knowledge Format (OKF) v0.2. LOKF keeps OKF's markdown-plus-frontmatter authoring model but binds every concept, field, and relationship to schema.org, W3C DCAT, and W3C PROV-O, so a bundle of markdown files is also valid JSON-LD that expands losslessly to RDF. The format is defined once in LinkML; the JSON-LD context, JSON Schema, SHACL shapes, and OWL ontology are all generated from that single source.

One sentence: write OKF markdown, get a queryable knowledge graph for free.

Documentation: https://lokf.nolan-nichols.com/

Why

OKF is deliberately minimal — the only required field is type, links are untyped, and there's no shared vocabulary. LOKF adds five things while keeping OKF's ergonomics:

1. Shared meaning — types and fields map to public ontology terms.
2. Typed relationships — dependsOn, derivedFrom, isPartOf, … each pinned to an RDF predicate, instead of one untyped markdown link.
3. A real graph — the same bundle is queryable with SPARQL, validatable with SHACL, and reason-able with OWL.
4. Documentation modes - an optional genre facet (and Tutorial/Explanation types) aligns each concept's prose to the four Diátaxis modes, on an axis orthogonal to type.
5. Queryable trust — OKF v0.2's provenance, trust, and lifecycle frontmatter (sources, usage_window, generated, verified, status, stale_after) and the AttestedComputation type, each bound to PROV-O / schema.org, so "where did this come from and should I trust it" is a SPARQL query rather than YAML an agent has to interpret. See SPEC §5.4.

It stays bidirectionally compatible: every LOKF bundle is a valid OKF bundle, and every OKF bundle is valid LOKF with default mappings.

Files

Anatomy of a LOKF concept

metrics/weekly-active-users.md — ordinary OKF markdown; every key has a defined RDF meaning:

---
type: Metric                                    # -> rdf:type lokf:Metric
id: https://acme.example/knowledge/metrics/weekly-active-users   # -> @id (subject)
title: Weekly Active Users                       # -> schema:name
unit: users                                      # -> schema:unitText
generated:                                       # -> prov:wasGeneratedBy
  by: human:jsmith@acme                          #    prov:wasAssociatedWith
  at: 2026-06-30T12:00:00Z                       #    prov:endedAtTime
status: stable                                   # -> schema:creativeWorkStatus
derivedFrom: [ .../tables/user-events ]          # -> prov:wasDerivedFrom
dependsOn:   [ .../glossary/active-user ]        # -> dcterms:requires
measures:    [ .../glossary/active-user ]        # -> lokf:measures
---
# Definition
Distinct users with a qualifying event in a trailing 7-day window.

Attach lokf.context.jsonld and this expands to RDF triples using schema:, prov:, dcterms:, and lokf: predicates — no separate file.

Regenerate the artifacts

Everything downstream of lokf.yaml is generated. One command reproduces every artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF:

uv sync
just build      # == uv run lokf-build

Or run the individual generators by hand:

# JSON-LD context (aliased type->@type, id->@id for authoring)
uv run gen-jsonld-context lokf.yaml > lokf.context.base.jsonld
uv run gen-json-schema     lokf.yaml > lokf.schema.json
uv run gen-shacl           lokf.yaml > lokf.shacl.ttl
uv run gen-owl             lokf.yaml > lokf.owl.ttl

The published lokf.context.jsonld is the generated context with two standard JSON-LD keyword aliases applied so unmodified OKF frontmatter is valid Linked Data:

import json
c = json.load(open("lokf.context.base.jsonld"))
c["@context"]["type"] = "@type"   # OKF's required field designates the RDF class
c["@context"]["id"]   = "@id"     # the concept IRI is the RDF subject
json.dump(c, open("lokf.context.jsonld", "w"), indent=2)

Validate a bundle

# `just build` assembles examples/acme-knowledge.bundle.json from the markdown, then:
uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
# -> No issues found

# Or validate a single concept against its class
uv run linkml-validate -s lokf.yaml -C Metric metric.json

Markdown → RDF in one command

The lokf CLI projects a concept — or a whole bundle directory — straight to RDF. No context wiring, no glue code:

# a single concept -> Turtle on stdout
uv run lokf convert examples/acme-knowledge/metrics/weekly-active-users.md --format ttl

# the same thing behind the just recipe
just gen-rdf-turtle examples/acme-knowledge/metrics/weekly-active-users.md

--format also takes nt, jsonld, xml, n3, and trig; --output FILE writes to disk instead of stdout. Point convert at the bundle directory (examples/acme-knowledge) to project all eight concepts at once.

Prefer to stay in Python? lokf.rdf.serialize is the same projection the CLI calls:

from lokf import rdf

# a concept file, or the bundle directory — either resolves IRIs correctly
print(rdf.serialize("examples/acme-knowledge/metrics/weekly-active-users.md", "ttl"))

This is the whole thesis: OKF authoring in, RDF knowledge graph out.

Two projections: a graph and tables

Because LOKF is defined once in LinkML, a well-modeled bundle projects two ways — the literal knowledge graph and the abstract one (well-modeled, linked data you can put in tables):

• A graph — markdown → JSON-LD → RDF, queryable with SPARQL, validatable with SHACL, reason-able with OWL (shown above).
• Tables — the same schema generates typed Python bindings (src/lokf/datamodel.py) and a relational schema (lokf.sql — one table per type, foreign keys for the typed relations). So the same well-modeled data is either a queryable graph or a set of linked tables: DataFrames to analyze, SQL to persist, a lakehouse to scale.

from lokf.datamodel import Metric

Metric(id="https://acme.example/knowledge/metrics/wau",
       type="Metric", title="Weekly Active Users", unit="users")

lokf tables projects a whole bundle to linked tables — one per type plus a relations edge table (needs lokf[tables]):

lokf tables examples/acme-knowledge --format parquet  --output build/tables
lokf tables examples/acme-knowledge --format bigquery --location gs://bucket/lokf

Start your own

lokf new my-kb scaffolds a complete knowledge-base repo — a starter bundle, a full Astro site with concept pages and the interactive graph browser (/graph, plus graph.jsonld), a GitHub Pages workflow, a justfile, and the bundled agent skills — so you (or an AI agent) can go from an idea to a published, queryable knowledge graph:

lokf new my-kb --title "My Knowledge Base"
cd my-kb && just setup && just dev

See the scaffold docs.

Status

LOKF v0.2 is a draft profile and is not affiliated with or endorsed by Google. The format version tracks OKF's <major>.<minor> scheme; the LinkML schema and the lokf package carry their own version (currently 0.5.0) so the toolkit can ship fixes without implying a format change — see SPEC §12. "Open Knowledge Format" / "OKF" refer to the format published by Google Cloud (github.com/GoogleCloudPlatform/knowledge-catalog); LOKF extends it under its open terms.

AI assistance

LOKF is developed openly and with substantial AI assistance (Claude) — including the toolkit, the LinkML schema, the documentation, and this README. Nolan Nichols reviews and takes full responsibility for everything committed. Per the project's AI Covenant, AI is a tool, not a co-author: it is never credited in commit messages, and every contribution is owned and defended by a human. See CONTRIBUTING.md to get involved.

License

The software — the lokf toolkit in src/, the tests, and the build tooling — is licensed under the Apache License 2.0. See LICENSE and NOTICE.

The specification and vocabulary — SPEC.md, the LinkML schema lokf.yaml, and the artifacts generated from it (lokf.context.jsonld, lokf.schema.json, lokf.shacl.ttl, lokf.owl.ttl, lokf.sql) — are licensed under CC-BY-4.0.

src/lokf/datamodel.py is generated too, but it is Python that ships in the package, so it is Apache-2.0 like the rest of src/. Its header comment — and lokf.owl.ttl's dcterms:license — transcribe lokf.yaml's own license: key, so wherever CC-BY-4.0 appears inside a generated file it is the schema's license, not the package's. The published package declares Apache-2.0, which is the license of the code you install.