Skip to content

Validation

Two independent, generated validators are available — one before RDF projection, one after.

flowchart LR
    A["Concept frontmatter<br/>(YAML/JSON)"] -- "lokf.schema.json<br/>(JSON Schema)" --> B["valid documents"]
    B -- "+ context, expand" --> C[("RDF graph")]
    C -- "lokf.shacl.ttl<br/>(SHACL shapes)" --> D["valid graph"]

lokf.schema.json validates a concept’s frontmatter, or a whole bundle serialized against the KnowledgeBundle root:

lokf validate does the assembly for you — point it at any bundle directory and it resolves the schema itself (a local lokf.yaml, else the copy inside the installed package):

Terminal window
lokf validate knowledge
# -> OK — 2 concepts in knowledge validate against KnowledgeBundle.

A project with a domain vocabulary declares it once, in the pyproject.toml that pins lokf, and every command that reads the bundle uses it when no --schema is passed: validate, convert, query, serve, export and the MCP server. The verdict then names the file, so a run against core LOKF alone is never mistaken for one against the domain’s:

[tool.lokf]
schema = "domain.yaml" # relative to this file
Terminal window
lokf validate knowledge
# -> OK — 2 concepts in knowledge validate against KnowledgeBundle (domain.yaml).

The nearest pyproject.toml with a [tool.lokf] table above the bundle decides, so the file is the bundle’s project’s wherever the command runs from; --schema still wins. A declared file that does not exist is an error, never a fall-back to core.

It validates through LinkML, which the lean core install leaves out, so install the build extra to use it:

Terminal window
uv pip install 'lokf[build]' # in a project
uvx --from 'lokf[build]' lokf validate knowledge # one-off, no install

Or drive the validator directly, against an already-assembled bundle document or a single concept:

Terminal window
# Whole bundle (assembled by `just build`)
uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
# -> No issues found
# Single concept against its class
uv run linkml-validate -s lokf.yaml -C Metric metric.json

Both validators are closed-world: a concept naming a type or a frontmatter key the schema does not declare fails. A bundle’s own types and keys go in a domain vocabulary, passed as --schema; convert, query and serve take the same flag.

Schema validation sees one concept at a time, so two things escape it. Two files declaring one id each validate and then merge into one subject in the graph; --check-ids fails that. A relation target is just a string, so a stale or invented IRI passes; --check-refs resolves every typed-relation target in the bundle’s own namespace, a relative ref or an IRI under base_iri, and leaves external resources alone. A local resource, on a concept, a source or an exclusion, is also just a string. --check-resources checks that each one names a file or directory inside the resource root, and accepts a pattern such as docs/*.svg when it matches there. The root is the nearest enclosing Git root, else the bundle’s parent, or --root; a path that escapes it is refused, and a URL is never fetched. A source’s excerpt is the passage the concept rests on, and nothing else holds it to its source: --check-excerpts finds each one in its local resource, whitespace collapsed and case folded, punctuation kept, with ... joining at most two spans in source order inside one heading section. All four are opt-in, so the default verdict stays the schema’s.

Terminal window
lokf validate knowledge --schema domain.yaml --check-ids --check-refs --check-resources --check-excerpts

A cross-file check runs without a flag, as a warning. A source id mints one node that every concept citing it shares, so two concepts that give it different excerpts each validate, and --shacl then fails on the node, which may hold one. lokf validate names the id and the files; the warning does not fail validation.

lokf.shacl.ttl validates the RDF graph after projection, catching cardinality, datatype, and range violations at the triple level. --shacl runs it in the same command once every other pass has succeeded. It needs the shacl extra, which brings the build extra with it:

Terminal window
uv pip install 'lokf[shacl]'
lokf validate knowledge --shacl
# -> OK — 2 concepts in knowledge validate against KnowledgeBundle. RDF conforms to SHACL shapes.

With a domain vocabulary, from --schema or [tool.lokf], the shapes are built from it as well, so a domain class’s own ranges are checked too.

A bundle is LOKF v0.2 conformant if:

  1. It is a conformant OKF v0.2 bundle: every non-reserved .md file has parseable YAML frontmatter with a non-empty type.
  2. Every type value that names a LOKF class is used consistently with that class’s mappings; unknown types are permitted and treated as lokf:Concept.
  3. The bundle-root index.md declares base_iri and context if the bundle is to be consumed as Linked Data. (A bundle without them is still LOKF-conformant, but is consumed as plain OKF.)
  4. Typed relation fields, when present, use the predicates the spec defines.
  5. When the trust, lifecycle, provenance, or computation families are present, they follow OKF v0.2 §5–§10. A consumer MUST read a bare verified mapping as a one-element list, and MUST NOT reject a concept for omitting any optional family.

The normative text lives in the specification.