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"]
JSON Schema — before projection
Section titled “JSON Schema — before projection”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):
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 filelokf 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:
uv pip install 'lokf[build]' # in a projectuvx --from 'lokf[build]' lokf validate knowledge # one-off, no installOr drive the validator directly, against an already-assembled bundle document or a single concept:
# 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 classuv run linkml-validate -s lokf.yaml -C Metric metric.jsonClosed-world, and four more passes
Section titled “Closed-world, and four more passes”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.
lokf validate knowledge --schema domain.yaml --check-ids --check-refs --check-resources --check-excerptsA 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.
SHACL — after projection
Section titled “SHACL — after projection”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:
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.
Conformance in brief
Section titled “Conformance in brief”A bundle is LOKF v0.2 conformant if:
- It is a conformant OKF v0.2 bundle: every non-reserved
.mdfile has parseable YAML frontmatter with a non-emptytype. - Every
typevalue that names a LOKF class is used consistently with that class’s mappings; unknown types are permitted and treated aslokf:Concept. - The bundle-root
index.mddeclaresbase_iriandcontextif the bundle is to be consumed as Linked Data. (A bundle without them is still LOKF-conformant, but is consumed as plain OKF.) - Typed relation fields, when present, use the predicates the spec defines.
- When the trust, lifecycle, provenance, or computation families are present,
they follow OKF v0.2 §5–§10. A consumer MUST read a bare
verifiedmapping as a one-element list, and MUST NOT reject a concept for omitting any optional family.
The normative text lives in the specification.