Getting started

Everything downstream of lokf.yaml — the JSON-LD context, JSON Schema, SHACL shapes, and OWL ontology — is generated. One command reproduces every artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF.

Prerequisites

• uv — Python package and project manager
• just — task runner (optional; every recipe is a one-line uv run … you can also type directly)

Install

git clone https://github.com/nicholsn/lokf.git
cd lokf
uv sync

uv sync creates a virtual environment with LinkML, rdflib, and PyYAML pinned by uv.lock, and installs the lokf package with its lokf-build console script.

Regenerate the artifacts

just

just build

uv

uv run lokf-build

The build:

1. runs the four LinkML generators against lokf.yaml,
2. publishes the authoring context (aliasing type → @type and id → @id),
3. assembles examples/acme-knowledge/ into a single bundle document,
4. validates the bundle against the schema, and
5. projects it to RDF (examples/*.nt).

You can also 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

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

See Validation for the JSON Schema / SHACL split.

Markdown → RDF in one command

The lokf convert command projects a concept — or the whole bundle — to RDF directly from the checkout you just cloned:

# 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 six 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. The Convert page covers every format and flag, and the mechanics of the projection are in Markdown to RDF.

Work on the docs

just

just docs        # live-reloading dev server
just docs-build  # strict build, exactly as CI runs it

npm

cd web && npm install && npm run dev    # live-reloading dev server
cd web && npm ci && npm run build       # strict build, exactly as CI runs it

The docs site is an Astro Starlight project in web/; the graph data and API reference are generated from the lokf package by a prebuild step.