Skip to content
LOKF

Contributing

Contributions are welcome — a new concept type, a mapping fix, a documentation improvement, or a bug report.

The single source of truth

Section titled “The single source of truth”

LOKF is defined once in lokf.yaml, a LinkML schema. The JSON-LD context, JSON Schema, SHACL shapes, and OWL ontology are generated from it — never hand-edit them.

File Hand-edit?
lokf.yaml ✅ the schema
SPEC.md, examples/…/*.md, web/… ✅ prose, examples, docs
lokf.context.jsonld, lokf.schema.json, lokf.shacl.ttl, lokf.owl.ttl, examples/*.nt ⚙️ generated

Set up

Section titled “Set up”
Terminal window
git clone https://github.com/nicholsn/lokf
cd lokf
uv sync

Make a change

Section titled “Make a change”

  1. Edit the source: lokf.yaml for the vocabulary, src/lokf/ for the toolkit, examples/ for the reference bundle, or web/ for these docs.

  2. When adding a type or field, map it to an established public ontology term (schema.org, DCAT, PROV-O, SKOS, W3C ORG, …) rather than minting a new term — reuse is the whole point of LOKF.

  3. Regenerate and re-validate everything:

    Terminal window
    just build     # regenerate artifacts + re-validate the reference bundle
    just test      # run the test suite

  4. Commit the regenerated artifacts alongside your schema change, so the generated files never drift from lokf.yaml.

Open a pull request

Section titled “Open a pull request”
  • just build and just test must pass.
  • Regenerated artifacts are committed.
  • Describe the change and the reasoning; if you touched the vocabulary, note which public terms you reused and why.

Responsible AI use

Section titled “Responsible AI use”

LOKF is built openly with AI assistance, and we ask contributors to use these tools responsibly. The essentials:

  • You own what you submit. Regardless of what tools helped, you are the author — understand it, verify it, and be ready to defend it in review.
  • No AI co-authorship. AI is never credited as a commit author or co-author; the human running the tool is solely responsible.
  • Disclose when it matters. If you propose a change in code or schema you don’t fully understand, say that AI suggested it so reviewers can weigh it appropriately.
  • Humans own discussion. AI can help you draft, but must not autonomously post to issues or discussions.

The full policy is the AI Covenant, adapted from the LinkML AI Covenant.

License

Section titled “License”

Contributions follow the project’s two-license split (inbound = outbound):

  • The software — the lokf toolkit, the tests, and the build tooling — is licensed under the Apache License 2.0.
  • The specification and vocabulary — SPEC.md, the LinkML schema lokf.yaml, and the artifacts generated from it — are licensed under CC-BY-4.0.

The published package declares Apache-2.0; the CC-BY-4.0 license: value you will see inside lokf.yaml and its generated headers is the schema’s own license, not the package’s.