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 six things while keeping
OKF's ergonomics:
- Shared meaning - types and fields map to public ontology terms.
- Typed relationships -
dependsOn,derivedFrom,isPartOf, … each pinned to an RDF predicate, instead of one untyped markdown link. - A real graph - the same bundle is queryable with SPARQL, validatable with SHACL, and reason-able with OWL.
- Queryable trust - OKF v0.2's provenance, trust, and lifecycle frontmatter (
sources,usage_window,generated,verified,status,stale_after) and theAttestedComputationtype, 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. - Domain schemas - a project's own types and keys, declared in a LinkML schema that
imports: [lokf]. The same validator checks them (lokf validate --schema),--check-refsresolves their relations, andconvert,queryandserve --schemaproject them under their own IRIs. The core vocabulary stays small; a domain extends it without forking it. See SPEC §6.2. - Documentation modes - an optional
genrefacet (andTutorial/Explanationtypes) aligns each concept's prose to the four Diátaxis modes, on an axis orthogonal totype.
It stays bidirectionally compatible: every LOKF bundle is a valid OKF bundle, and every OKF bundle is valid LOKF with default mappings — with or without its domain schema.
Files
| Path | What it is | Hand-edited? |
|---|---|---|
lokf.yaml |
The LinkML schema — the single source of truth. | ✅ edit this |
SPEC.md |
The human-readable specification. | ✅ |
lokf.context.jsonld |
Generated JSON-LD @context (+ type→@type, id→@id aliases). Attach to concepts to get Linked Data. |
⚙️ generated |
lokf.schema.json |
Generated JSON Schema — validates frontmatter / bundles. | ⚙️ generated |
lokf.shacl.ttl |
Generated SHACL shapes — validates the RDF graph. | ⚙️ generated |
lokf.owl.ttl |
Generated OWL ontology — reasoning & alignment. | ⚙️ generated |
lokf.sql |
Generated relational schema — CREATE TABLE DDL (FKs for typed relations). |
⚙️ generated |
src/lokf/datamodel.py |
Generated Python bindings — from lokf.datamodel import Metric. |
⚙️ generated |
examples/acme-knowledge/ |
A conformant 8-concept reference bundle. | ✅ |
examples/*.nt |
RDF triples produced from the example frontmatter. | ⚙️ generated |
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
The individual generators produce raw LinkML artifacts. Use lokf-build to
apply the authoring-context and SHACL adjustments and synchronize packaged copies:
# 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 lokf-build # includes SHACL adapted to the authoring RDF projection
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
To also validate the projected graph, install lokf[shacl] and run:
lokf validate knowledge --shacl
lokf validate knowledge --shacl --schema domain.yaml
The command checks nested values, local relation ranges, and RDF node kinds.
It recognizes Concept inheritance and mixins, and leaves external referenced
IRIs unverified without fetching them. Explicit concept IDs remain local even
outside the bundle namespace. Domain shapes are generated from the selected
schema. The shipped shapes use distinct shape identifiers for classes sharing
an RDF class, and validate the authoring projection (type is rdf:type,
optional enums are literals, and provenance objects can be untyped).
For direct Python graph checks, lokf.shacl.validate_graph(graph, shapes, base_iri, concept_iris) applies the same local/external policy and embedded
class hierarchy. The unmodified artifact assumes referenced classes are known;
a standalone SHACL engine must supply that hierarchy as ontology data and
choose its own external-reference policy. JSON Schema retains closed-field and
per-field cardinality checks where multiple authoring fields share one predicate.
Validation is closed-world (SPEC §9): a project-specific type or key needs a domain schema that imports: [lokf] (SPEC §6.2), passed via lokf validate --schema. Pass the same file to lokf convert, query or serve with --schema to project its types and keys under their own IRIs. A published LinkML vocabulary becomes such a schema's import with lokf adapt VOCAB.yaml; examples/biolink/ does this for biolink-model.
Schema validation sees one concept at a time, so two files declaring one id (a sync client's conflict copy is the usual way) pass and then merge into one subject in the graph; --check-ids catches that. It cannot tell a live relation target from a fabricated one either - both are valid strings. --check-refs adds that pass:
uv run lokf validate examples/acme-knowledge --check-refs
# -> OK — 8 concepts ... All in-namespace relation targets resolve.
It checks every typed-relation target naming the bundle's own namespace —
a relative ref, or an IRI under base_iri. External resources are left alone,
since slots like definedBy and source are defined as taking one.
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.9.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.
The installed package includes lokf/data/lokf.schema.json and
lokf/data/lokf.shacl.ttl, synchronized by lokf-build. Python hosts can read
these with importlib.resources.files("lokf").joinpath("data", filename);
non-Python clients can use the same versioned artifacts from the repository.
Metadata
Release files for lokf 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lokf-0.9.0.tar.gz | 721.3 kB | With provenance | Details for lokf-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lokf-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for lokf-0.9.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / lokf-0.9.0.tar.gz
| Download URL | lokf-0.9.0.tar.gz |
|---|---|
| Size | 721.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f7c2106f818600a40584569eb4d390c1de68c86085ce8df727d612a0ac0f4b3
|
|
BLAKE2b-256 checksum How to use checksums |
187e6fbfe6515951bb90965b3189587df943d3a6caef69ff1de037efef8a9ed6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logRelease files / lokf-0.9.0-py3-none-any.whl
| Download URL | lokf-0.9.0-py3-none-any.whl |
|---|---|
| Size | 349.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a873562c432da49bf078c2f94845efe64bc7ec2d99518aab06f82b3092ac2d6a
|
|
BLAKE2b-256 checksum How to use checksums |
74c61866aaceb834d8796ec1e24b12a35f95d4dd649635a9bad859627d6212a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logSecurity for lokf 0.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for lokf-0.9.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.