lokf 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lokf-0.1.0/.github/workflows/docs.yml +50 -0
- lokf-0.1.0/.github/workflows/publish.yml +51 -0
- lokf-0.1.0/.gitignore +24 -0
- lokf-0.1.0/.python-version +1 -0
- lokf-0.1.0/LICENSE +26 -0
- lokf-0.1.0/PKG-INFO +187 -0
- lokf-0.1.0/README.md +155 -0
- lokf-0.1.0/SPEC.md +422 -0
- lokf-0.1.0/docs/assets/js/cytoscape.min.js +32 -0
- lokf-0.1.0/docs/examples.md +69 -0
- lokf-0.1.0/docs/getting-started.md +82 -0
- lokf-0.1.0/docs/graph.md +338 -0
- lokf-0.1.0/docs/guide/concepts.md +66 -0
- lokf-0.1.0/docs/guide/markdown-to-rdf.md +63 -0
- lokf-0.1.0/docs/guide/relationships.md +41 -0
- lokf-0.1.0/docs/guide/types.md +66 -0
- lokf-0.1.0/docs/guide/validation.md +53 -0
- lokf-0.1.0/docs/hooks/lokf_hooks.py +97 -0
- lokf-0.1.0/docs/index.md +93 -0
- lokf-0.1.0/docs/reference/api.md +58 -0
- lokf-0.1.0/docs/reference/artifacts.md +52 -0
- lokf-0.1.0/docs/specification.md +1 -0
- lokf-0.1.0/docs/toolkit/agents.md +64 -0
- lokf-0.1.0/docs/toolkit/convert.md +80 -0
- lokf-0.1.0/docs/toolkit/index.md +144 -0
- lokf-0.1.0/docs/toolkit/mcp.md +87 -0
- lokf-0.1.0/docs/toolkit/proposer.md +161 -0
- lokf-0.1.0/docs/toolkit/query.md +101 -0
- lokf-0.1.0/docs/toolkit/serve.md +49 -0
- lokf-0.1.0/docs/toolkit/tutorial.md +297 -0
- lokf-0.1.0/examples/acme-knowledge/datasets/events.md +14 -0
- lokf-0.1.0/examples/acme-knowledge/glossary/active-user.md +17 -0
- lokf-0.1.0/examples/acme-knowledge/index.md +34 -0
- lokf-0.1.0/examples/acme-knowledge/log.md +7 -0
- lokf-0.1.0/examples/acme-knowledge/metrics/weekly-active-users.md +42 -0
- lokf-0.1.0/examples/acme-knowledge/playbooks/data-freshness-incident.md +23 -0
- lokf-0.1.0/examples/acme-knowledge/services/analytics-api.md +18 -0
- lokf-0.1.0/examples/acme-knowledge/tables/user-events.md +36 -0
- lokf-0.1.0/examples/acme-knowledge.nt +86 -0
- lokf-0.1.0/examples/weekly-active-users.nt +22 -0
- lokf-0.1.0/justfile +40 -0
- lokf-0.1.0/lokf.context.jsonld +267 -0
- lokf-0.1.0/lokf.owl.ttl +1190 -0
- lokf-0.1.0/lokf.schema.json +2894 -0
- lokf-0.1.0/lokf.shacl.ttl +1682 -0
- lokf-0.1.0/lokf.yaml +806 -0
- lokf-0.1.0/mkdocs.yml +127 -0
- lokf-0.1.0/pyproject.toml +65 -0
- lokf-0.1.0/src/lokf/__init__.py +20 -0
- lokf-0.1.0/src/lokf/agentskills.py +58 -0
- lokf-0.1.0/src/lokf/build.py +155 -0
- lokf-0.1.0/src/lokf/cli.py +276 -0
- lokf-0.1.0/src/lokf/data/lokf.context.jsonld +267 -0
- lokf-0.1.0/src/lokf/data/lokf.yaml +806 -0
- lokf-0.1.0/src/lokf/export.py +173 -0
- lokf-0.1.0/src/lokf/mcp_server.py +200 -0
- lokf-0.1.0/src/lokf/model.py +126 -0
- lokf-0.1.0/src/lokf/parse.py +43 -0
- lokf-0.1.0/src/lokf/propose.py +344 -0
- lokf-0.1.0/src/lokf/rdf.py +125 -0
- lokf-0.1.0/src/lokf/schema.py +192 -0
- lokf-0.1.0/src/lokf/server.py +215 -0
- lokf-0.1.0/src/lokf/skills/author-concept/SKILL.md +126 -0
- lokf-0.1.0/src/lokf/skills/build-knowledge-base/SKILL.md +118 -0
- lokf-0.1.0/src/lokf/skills/enrich-relations/SKILL.md +95 -0
- lokf-0.1.0/src/lokf/skills/publish-graph/SKILL.md +85 -0
- lokf-0.1.0/src/lokf/skills/query-knowledge-base/SKILL.md +99 -0
- lokf-0.1.0/src/lokf/static/cytoscape.min.js +32 -0
- lokf-0.1.0/src/lokf/store.py +207 -0
- lokf-0.1.0/tests/test_cli.py +114 -0
- lokf-0.1.0/tests/test_export.py +178 -0
- lokf-0.1.0/tests/test_hooks.py +23 -0
- lokf-0.1.0/tests/test_mcp.py +137 -0
- lokf-0.1.0/tests/test_model.py +62 -0
- lokf-0.1.0/tests/test_propose.py +270 -0
- lokf-0.1.0/tests/test_rdf.py +75 -0
- lokf-0.1.0/tests/test_review_fixes.py +119 -0
- lokf-0.1.0/tests/test_schema.py +87 -0
- lokf-0.1.0/tests/test_security.py +70 -0
- lokf-0.1.0/tests/test_server.py +142 -0
- lokf-0.1.0/tests/test_skills.py +57 -0
- lokf-0.1.0/tests/test_store.py +106 -0
- lokf-0.1.0/tests/test_vendored.py +16 -0
- lokf-0.1.0/uv.lock +2459 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
name: docs
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
permissions: {}
|
|
9
|
+
|
|
10
|
+
# Cancel superseded PR builds, but never a production Pages deploy mid-flight.
|
|
11
|
+
concurrency:
|
|
12
|
+
group: docs-${{ github.ref }}
|
|
13
|
+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
build:
|
|
17
|
+
runs-on: ubuntu-latest
|
|
18
|
+
permissions:
|
|
19
|
+
contents: read
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v4
|
|
22
|
+
with:
|
|
23
|
+
fetch-depth: 0 # full history for git-revision-date-localized
|
|
24
|
+
|
|
25
|
+
- uses: astral-sh/setup-uv@v5
|
|
26
|
+
with:
|
|
27
|
+
enable-cache: true
|
|
28
|
+
|
|
29
|
+
- name: Build site (strict)
|
|
30
|
+
# --only-group: the docs build doesn't need the project or its runtime
|
|
31
|
+
# deps (mkdocstrings reads src/ statically) — 37 packages instead of 107
|
|
32
|
+
run: uv run --locked --only-group docs mkdocs build --strict
|
|
33
|
+
|
|
34
|
+
- uses: actions/upload-pages-artifact@v3
|
|
35
|
+
with:
|
|
36
|
+
path: site
|
|
37
|
+
|
|
38
|
+
deploy:
|
|
39
|
+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
|
|
40
|
+
needs: build
|
|
41
|
+
runs-on: ubuntu-latest
|
|
42
|
+
permissions:
|
|
43
|
+
pages: write
|
|
44
|
+
id-token: write
|
|
45
|
+
environment:
|
|
46
|
+
name: github-pages
|
|
47
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
48
|
+
steps:
|
|
49
|
+
- uses: actions/deploy-pages@v4
|
|
50
|
+
id: deployment
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: publish
|
|
2
|
+
|
|
3
|
+
# Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is
|
|
4
|
+
# published — no API token is stored. Configure the trusted publisher once on
|
|
5
|
+
# PyPI: project "lokf", owner "nicholsn", repo "lokf", workflow "publish.yml",
|
|
6
|
+
# environment "pypi".
|
|
7
|
+
on:
|
|
8
|
+
release:
|
|
9
|
+
types: [published]
|
|
10
|
+
workflow_dispatch:
|
|
11
|
+
|
|
12
|
+
permissions: {}
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
build:
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
permissions:
|
|
18
|
+
contents: read
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v4
|
|
21
|
+
- uses: astral-sh/setup-uv@v5
|
|
22
|
+
with:
|
|
23
|
+
enable-cache: true
|
|
24
|
+
|
|
25
|
+
- name: Test (gate the release)
|
|
26
|
+
run: uv run --group dev pytest -q
|
|
27
|
+
|
|
28
|
+
- name: Build sdist + wheel
|
|
29
|
+
run: uv build
|
|
30
|
+
|
|
31
|
+
- uses: actions/upload-artifact@v4
|
|
32
|
+
with:
|
|
33
|
+
name: dist
|
|
34
|
+
path: dist/
|
|
35
|
+
|
|
36
|
+
publish:
|
|
37
|
+
needs: build
|
|
38
|
+
runs-on: ubuntu-latest
|
|
39
|
+
environment:
|
|
40
|
+
name: pypi
|
|
41
|
+
url: https://pypi.org/project/lokf/
|
|
42
|
+
permissions:
|
|
43
|
+
id-token: write # OIDC token for Trusted Publishing
|
|
44
|
+
steps:
|
|
45
|
+
- uses: actions/download-artifact@v4
|
|
46
|
+
with:
|
|
47
|
+
name: dist
|
|
48
|
+
path: dist/
|
|
49
|
+
|
|
50
|
+
- name: Publish to PyPI
|
|
51
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
lokf-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
.venv/
|
|
5
|
+
venv/
|
|
6
|
+
|
|
7
|
+
# LinkML / build scratch
|
|
8
|
+
*.err
|
|
9
|
+
lokf.context.base.jsonld
|
|
10
|
+
|
|
11
|
+
# Regenerated by lokf-build (src/lokf/build.py); kept out of source control
|
|
12
|
+
examples/*.bundle.json
|
|
13
|
+
examples/*.bundle.yaml
|
|
14
|
+
|
|
15
|
+
# Git bundle export
|
|
16
|
+
*.bundle
|
|
17
|
+
|
|
18
|
+
# OS / editor cruft
|
|
19
|
+
.DS_Store
|
|
20
|
+
.fuse_hidden*
|
|
21
|
+
*.swp
|
|
22
|
+
|
|
23
|
+
# MkDocs build output
|
|
24
|
+
site/
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.12
|
lokf-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
Linked Open Knowledge Format (LOKF)
|
|
2
|
+
Copyright (c) 2026 Nolan Nichols
|
|
3
|
+
|
|
4
|
+
This work — the LOKF specification, the LinkML schema, the generated artifacts,
|
|
5
|
+
and the examples — is licensed under the Creative Commons Attribution 4.0
|
|
6
|
+
International License (CC BY 4.0).
|
|
7
|
+
|
|
8
|
+
You are free to:
|
|
9
|
+
Share — copy and redistribute the material in any medium or format.
|
|
10
|
+
Adapt — remix, transform, and build upon the material for any purpose,
|
|
11
|
+
even commercially.
|
|
12
|
+
|
|
13
|
+
Under the following terms:
|
|
14
|
+
Attribution — You must give appropriate credit, provide a link to the license,
|
|
15
|
+
and indicate if changes were made. You may do so in any reasonable manner, but
|
|
16
|
+
not in any way that suggests the licensor endorses you or your use.
|
|
17
|
+
|
|
18
|
+
No additional restrictions — You may not apply legal terms or technological
|
|
19
|
+
measures that legally restrict others from doing anything the license permits.
|
|
20
|
+
|
|
21
|
+
Full legal code: https://creativecommons.org/licenses/by/4.0/legalcode
|
|
22
|
+
Human-readable summary: https://creativecommons.org/licenses/by/4.0/
|
|
23
|
+
|
|
24
|
+
"Open Knowledge Format" and "OKF" refer to the format published by Google Cloud
|
|
25
|
+
(github.com/GoogleCloudPlatform/knowledge-catalog). LOKF is an independent,
|
|
26
|
+
unaffiliated profile built upon it.
|
lokf-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: lokf
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Linked Open Knowledge Format (LOKF) — a semantic profile of Google's Open Knowledge Format, defined once in LinkML
|
|
5
|
+
Project-URL: Documentation, https://www.nolan-nichols.com/lokf/
|
|
6
|
+
Project-URL: Repository, https://github.com/nicholsn/lokf
|
|
7
|
+
Project-URL: Issues, https://github.com/nicholsn/lokf/issues
|
|
8
|
+
Author: Nolan Nichols
|
|
9
|
+
License-Expression: CC-BY-4.0
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: dcat,json-ld,knowledge-graph,linkml,mcp,okf,prov,rdf,sparql
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Information Technology
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Classifier: Topic :: Text Processing :: Markup
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: mcp>=1.2
|
|
24
|
+
Requires-Dist: pyoxigraph>=0.4
|
|
25
|
+
Requires-Dist: pyyaml>=6.0
|
|
26
|
+
Requires-Dist: rdflib>=7.0
|
|
27
|
+
Requires-Dist: ruamel-yaml>=0.18
|
|
28
|
+
Requires-Dist: typer>=0.15
|
|
29
|
+
Provides-Extra: build
|
|
30
|
+
Requires-Dist: linkml>=1.8.5; extra == 'build'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# Linked Open Knowledge Format (LOKF) — v0.1
|
|
34
|
+
|
|
35
|
+
A **semantic profile of Google's Open Knowledge Format (OKF)**. LOKF keeps OKF's
|
|
36
|
+
markdown-plus-frontmatter authoring model but binds every concept, field, and
|
|
37
|
+
relationship to **schema.org, W3C DCAT, and W3C PROV-O**, so a bundle of markdown
|
|
38
|
+
files is *also* valid **JSON-LD** that expands losslessly to **RDF**. The format is
|
|
39
|
+
defined once in **LinkML**; the JSON-LD context, JSON Schema, SHACL shapes, and OWL
|
|
40
|
+
ontology are all generated from that single source.
|
|
41
|
+
|
|
42
|
+
> One sentence: *write OKF markdown, get a queryable knowledge graph for free.*
|
|
43
|
+
|
|
44
|
+
**Documentation:** <https://www.nolan-nichols.com/lokf/>
|
|
45
|
+
|
|
46
|
+
## Why
|
|
47
|
+
|
|
48
|
+
OKF v0.1 is deliberately minimal — the only required field is `type`, links are
|
|
49
|
+
untyped, and there's no shared vocabulary. LOKF adds exactly three things while
|
|
50
|
+
keeping OKF's ergonomics:
|
|
51
|
+
|
|
52
|
+
1. **Shared meaning** — types and fields map to public ontology terms.
|
|
53
|
+
2. **Typed relationships** — `dependsOn`, `derivedFrom`, `isPartOf`, … each pinned
|
|
54
|
+
to an RDF predicate, instead of one untyped markdown link.
|
|
55
|
+
3. **A real graph** — the same bundle is queryable with SPARQL, validatable with
|
|
56
|
+
SHACL, and reason-able with OWL.
|
|
57
|
+
|
|
58
|
+
It stays **bidirectionally compatible**: every LOKF bundle is a valid OKF bundle,
|
|
59
|
+
and every OKF bundle is valid LOKF with default mappings.
|
|
60
|
+
|
|
61
|
+
## Files
|
|
62
|
+
|
|
63
|
+
| Path | What it is | Hand-edited? |
|
|
64
|
+
|------|------------|:---:|
|
|
65
|
+
| `lokf.yaml` | **The LinkML schema — the single source of truth.** | ✅ edit this |
|
|
66
|
+
| `SPEC.md` | The human-readable specification. | ✅ |
|
|
67
|
+
| `lokf.context.jsonld` | Generated JSON-LD `@context` (+ `type`→`@type`, `id`→`@id` aliases). Attach to concepts to get Linked Data. | ⚙️ generated |
|
|
68
|
+
| `lokf.schema.json` | Generated JSON Schema — validates frontmatter / bundles. | ⚙️ generated |
|
|
69
|
+
| `lokf.shacl.ttl` | Generated SHACL shapes — validates the RDF graph. | ⚙️ generated |
|
|
70
|
+
| `lokf.owl.ttl` | Generated OWL ontology — reasoning & alignment. | ⚙️ generated |
|
|
71
|
+
| `examples/acme-knowledge/` | A conformant 6-concept reference bundle. | ✅ |
|
|
72
|
+
| `examples/*.nt` | RDF triples produced from the example frontmatter. | ⚙️ generated |
|
|
73
|
+
|
|
74
|
+
## Anatomy of a LOKF concept
|
|
75
|
+
|
|
76
|
+
`metrics/weekly-active-users.md` — ordinary OKF markdown; every key has a defined
|
|
77
|
+
RDF meaning:
|
|
78
|
+
|
|
79
|
+
<!-- --8<-- [start:concept-glance] -->
|
|
80
|
+
```markdown title="metrics/weekly-active-users.md"
|
|
81
|
+
---
|
|
82
|
+
type: Metric # -> rdf:type lokf:Metric
|
|
83
|
+
id: https://acme.example/knowledge/metrics/weekly-active-users # -> @id (subject)
|
|
84
|
+
title: Weekly Active Users # -> schema:name
|
|
85
|
+
unit: users # -> schema:unitText
|
|
86
|
+
timestamp: 2026-06-30T12:00:00Z # -> schema:dateModified
|
|
87
|
+
derivedFrom: [ .../tables/user-events ] # -> prov:wasDerivedFrom
|
|
88
|
+
dependsOn: [ .../glossary/active-user ] # -> dcterms:requires
|
|
89
|
+
measures: [ .../glossary/active-user ] # -> lokf:measures
|
|
90
|
+
---
|
|
91
|
+
# Definition
|
|
92
|
+
Distinct users with a qualifying event in a trailing 7-day window.
|
|
93
|
+
```
|
|
94
|
+
<!-- --8<-- [end:concept-glance] -->
|
|
95
|
+
|
|
96
|
+
Attach `lokf.context.jsonld` and this expands to RDF triples using
|
|
97
|
+
`schema:`, `prov:`, `dcterms:`, and `lokf:` predicates — no separate file.
|
|
98
|
+
|
|
99
|
+
## Regenerate the artifacts
|
|
100
|
+
|
|
101
|
+
Everything downstream of `lokf.yaml` is generated. One command reproduces every
|
|
102
|
+
artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
uv sync
|
|
106
|
+
just build # == uv run lokf-build
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Or run the individual generators by hand:
|
|
110
|
+
|
|
111
|
+
<!-- --8<-- [start:gen-commands] -->
|
|
112
|
+
```bash
|
|
113
|
+
# JSON-LD context (aliased type->@type, id->@id for authoring)
|
|
114
|
+
uv run gen-jsonld-context lokf.yaml > lokf.context.base.jsonld
|
|
115
|
+
uv run gen-json-schema lokf.yaml > lokf.schema.json
|
|
116
|
+
uv run gen-shacl lokf.yaml > lokf.shacl.ttl
|
|
117
|
+
uv run gen-owl lokf.yaml > lokf.owl.ttl
|
|
118
|
+
```
|
|
119
|
+
<!-- --8<-- [end:gen-commands] -->
|
|
120
|
+
|
|
121
|
+
The published `lokf.context.jsonld` is the generated context with two standard
|
|
122
|
+
JSON-LD keyword aliases applied so unmodified OKF frontmatter is valid Linked Data:
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
import json
|
|
126
|
+
c = json.load(open("lokf.context.base.jsonld"))
|
|
127
|
+
c["@context"]["type"] = "@type" # OKF's required field designates the RDF class
|
|
128
|
+
c["@context"]["id"] = "@id" # the concept IRI is the RDF subject
|
|
129
|
+
json.dump(c, open("lokf.context.jsonld", "w"), indent=2)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Validate a bundle
|
|
133
|
+
|
|
134
|
+
<!-- --8<-- [start:validate-bundle] -->
|
|
135
|
+
```bash
|
|
136
|
+
# `just build` assembles examples/acme-knowledge.bundle.json from the markdown, then:
|
|
137
|
+
uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
|
|
138
|
+
# -> No issues found
|
|
139
|
+
|
|
140
|
+
# Or validate a single concept against its class
|
|
141
|
+
uv run linkml-validate -s lokf.yaml -C Metric metric.json
|
|
142
|
+
```
|
|
143
|
+
<!-- --8<-- [end:validate-bundle] -->
|
|
144
|
+
|
|
145
|
+
## Markdown → RDF in one command
|
|
146
|
+
|
|
147
|
+
The `lokf` CLI projects a concept — or a whole bundle directory — straight to
|
|
148
|
+
RDF. No context wiring, no glue code:
|
|
149
|
+
|
|
150
|
+
<!-- --8<-- [start:quickstart-rdf] -->
|
|
151
|
+
```bash
|
|
152
|
+
# a single concept -> Turtle on stdout
|
|
153
|
+
uv run lokf convert examples/acme-knowledge/metrics/weekly-active-users.md --format ttl
|
|
154
|
+
|
|
155
|
+
# the same thing behind the just recipe
|
|
156
|
+
just gen-rdf-turtle examples/acme-knowledge/metrics/weekly-active-users.md
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`--format` also takes `nt`, `jsonld`, `xml`, `n3`, and `trig`; `--output FILE`
|
|
160
|
+
writes to disk instead of stdout. Point `convert` at the bundle directory
|
|
161
|
+
(`examples/acme-knowledge`) to project all six concepts at once.
|
|
162
|
+
|
|
163
|
+
Prefer to stay in Python? `lokf.rdf.serialize` is the same projection the CLI
|
|
164
|
+
calls:
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
from lokf import rdf
|
|
168
|
+
|
|
169
|
+
# a concept file, or the bundle directory — either resolves IRIs correctly
|
|
170
|
+
print(rdf.serialize("examples/acme-knowledge/metrics/weekly-active-users.md", "ttl"))
|
|
171
|
+
```
|
|
172
|
+
<!-- --8<-- [end:quickstart-rdf] -->
|
|
173
|
+
|
|
174
|
+
This is the whole thesis: OKF authoring in, RDF knowledge graph out.
|
|
175
|
+
|
|
176
|
+
## Status
|
|
177
|
+
|
|
178
|
+
LOKF v0.1 is a **draft profile** and is **not affiliated with or endorsed by
|
|
179
|
+
Google**. "Open Knowledge Format" / "OKF" refer to the format published by Google
|
|
180
|
+
Cloud (`github.com/GoogleCloudPlatform/knowledge-catalog`); LOKF extends it under
|
|
181
|
+
its open terms.
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
CC-BY-4.0 — see [`LICENSE`](https://github.com/nicholsn/lokf/blob/main/LICENSE).
|
|
186
|
+
It's a spec + vocabulary; if you'd rather put the scripts under a code license,
|
|
187
|
+
swap in MIT or Apache-2.0.
|
lokf-0.1.0/README.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Linked Open Knowledge Format (LOKF) — v0.1
|
|
2
|
+
|
|
3
|
+
A **semantic profile of Google's Open Knowledge Format (OKF)**. LOKF keeps OKF's
|
|
4
|
+
markdown-plus-frontmatter authoring model but binds every concept, field, and
|
|
5
|
+
relationship to **schema.org, W3C DCAT, and W3C PROV-O**, so a bundle of markdown
|
|
6
|
+
files is *also* valid **JSON-LD** that expands losslessly to **RDF**. The format is
|
|
7
|
+
defined once in **LinkML**; the JSON-LD context, JSON Schema, SHACL shapes, and OWL
|
|
8
|
+
ontology are all generated from that single source.
|
|
9
|
+
|
|
10
|
+
> One sentence: *write OKF markdown, get a queryable knowledge graph for free.*
|
|
11
|
+
|
|
12
|
+
**Documentation:** <https://www.nolan-nichols.com/lokf/>
|
|
13
|
+
|
|
14
|
+
## Why
|
|
15
|
+
|
|
16
|
+
OKF v0.1 is deliberately minimal — the only required field is `type`, links are
|
|
17
|
+
untyped, and there's no shared vocabulary. LOKF adds exactly three things while
|
|
18
|
+
keeping OKF's ergonomics:
|
|
19
|
+
|
|
20
|
+
1. **Shared meaning** — types and fields map to public ontology terms.
|
|
21
|
+
2. **Typed relationships** — `dependsOn`, `derivedFrom`, `isPartOf`, … each pinned
|
|
22
|
+
to an RDF predicate, instead of one untyped markdown link.
|
|
23
|
+
3. **A real graph** — the same bundle is queryable with SPARQL, validatable with
|
|
24
|
+
SHACL, and reason-able with OWL.
|
|
25
|
+
|
|
26
|
+
It stays **bidirectionally compatible**: every LOKF bundle is a valid OKF bundle,
|
|
27
|
+
and every OKF bundle is valid LOKF with default mappings.
|
|
28
|
+
|
|
29
|
+
## Files
|
|
30
|
+
|
|
31
|
+
| Path | What it is | Hand-edited? |
|
|
32
|
+
|------|------------|:---:|
|
|
33
|
+
| `lokf.yaml` | **The LinkML schema — the single source of truth.** | ✅ edit this |
|
|
34
|
+
| `SPEC.md` | The human-readable specification. | ✅ |
|
|
35
|
+
| `lokf.context.jsonld` | Generated JSON-LD `@context` (+ `type`→`@type`, `id`→`@id` aliases). Attach to concepts to get Linked Data. | ⚙️ generated |
|
|
36
|
+
| `lokf.schema.json` | Generated JSON Schema — validates frontmatter / bundles. | ⚙️ generated |
|
|
37
|
+
| `lokf.shacl.ttl` | Generated SHACL shapes — validates the RDF graph. | ⚙️ generated |
|
|
38
|
+
| `lokf.owl.ttl` | Generated OWL ontology — reasoning & alignment. | ⚙️ generated |
|
|
39
|
+
| `examples/acme-knowledge/` | A conformant 6-concept reference bundle. | ✅ |
|
|
40
|
+
| `examples/*.nt` | RDF triples produced from the example frontmatter. | ⚙️ generated |
|
|
41
|
+
|
|
42
|
+
## Anatomy of a LOKF concept
|
|
43
|
+
|
|
44
|
+
`metrics/weekly-active-users.md` — ordinary OKF markdown; every key has a defined
|
|
45
|
+
RDF meaning:
|
|
46
|
+
|
|
47
|
+
<!-- --8<-- [start:concept-glance] -->
|
|
48
|
+
```markdown title="metrics/weekly-active-users.md"
|
|
49
|
+
---
|
|
50
|
+
type: Metric # -> rdf:type lokf:Metric
|
|
51
|
+
id: https://acme.example/knowledge/metrics/weekly-active-users # -> @id (subject)
|
|
52
|
+
title: Weekly Active Users # -> schema:name
|
|
53
|
+
unit: users # -> schema:unitText
|
|
54
|
+
timestamp: 2026-06-30T12:00:00Z # -> schema:dateModified
|
|
55
|
+
derivedFrom: [ .../tables/user-events ] # -> prov:wasDerivedFrom
|
|
56
|
+
dependsOn: [ .../glossary/active-user ] # -> dcterms:requires
|
|
57
|
+
measures: [ .../glossary/active-user ] # -> lokf:measures
|
|
58
|
+
---
|
|
59
|
+
# Definition
|
|
60
|
+
Distinct users with a qualifying event in a trailing 7-day window.
|
|
61
|
+
```
|
|
62
|
+
<!-- --8<-- [end:concept-glance] -->
|
|
63
|
+
|
|
64
|
+
Attach `lokf.context.jsonld` and this expands to RDF triples using
|
|
65
|
+
`schema:`, `prov:`, `dcterms:`, and `lokf:` predicates — no separate file.
|
|
66
|
+
|
|
67
|
+
## Regenerate the artifacts
|
|
68
|
+
|
|
69
|
+
Everything downstream of `lokf.yaml` is generated. One command reproduces every
|
|
70
|
+
artifact, re-assembles the reference bundle, re-validates it, and re-emits the RDF:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
uv sync
|
|
74
|
+
just build # == uv run lokf-build
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or run the individual generators by hand:
|
|
78
|
+
|
|
79
|
+
<!-- --8<-- [start:gen-commands] -->
|
|
80
|
+
```bash
|
|
81
|
+
# JSON-LD context (aliased type->@type, id->@id for authoring)
|
|
82
|
+
uv run gen-jsonld-context lokf.yaml > lokf.context.base.jsonld
|
|
83
|
+
uv run gen-json-schema lokf.yaml > lokf.schema.json
|
|
84
|
+
uv run gen-shacl lokf.yaml > lokf.shacl.ttl
|
|
85
|
+
uv run gen-owl lokf.yaml > lokf.owl.ttl
|
|
86
|
+
```
|
|
87
|
+
<!-- --8<-- [end:gen-commands] -->
|
|
88
|
+
|
|
89
|
+
The published `lokf.context.jsonld` is the generated context with two standard
|
|
90
|
+
JSON-LD keyword aliases applied so unmodified OKF frontmatter is valid Linked Data:
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
import json
|
|
94
|
+
c = json.load(open("lokf.context.base.jsonld"))
|
|
95
|
+
c["@context"]["type"] = "@type" # OKF's required field designates the RDF class
|
|
96
|
+
c["@context"]["id"] = "@id" # the concept IRI is the RDF subject
|
|
97
|
+
json.dump(c, open("lokf.context.jsonld", "w"), indent=2)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Validate a bundle
|
|
101
|
+
|
|
102
|
+
<!-- --8<-- [start:validate-bundle] -->
|
|
103
|
+
```bash
|
|
104
|
+
# `just build` assembles examples/acme-knowledge.bundle.json from the markdown, then:
|
|
105
|
+
uv run linkml-validate -s lokf.yaml -C KnowledgeBundle examples/acme-knowledge.bundle.json
|
|
106
|
+
# -> No issues found
|
|
107
|
+
|
|
108
|
+
# Or validate a single concept against its class
|
|
109
|
+
uv run linkml-validate -s lokf.yaml -C Metric metric.json
|
|
110
|
+
```
|
|
111
|
+
<!-- --8<-- [end:validate-bundle] -->
|
|
112
|
+
|
|
113
|
+
## Markdown → RDF in one command
|
|
114
|
+
|
|
115
|
+
The `lokf` CLI projects a concept — or a whole bundle directory — straight to
|
|
116
|
+
RDF. No context wiring, no glue code:
|
|
117
|
+
|
|
118
|
+
<!-- --8<-- [start:quickstart-rdf] -->
|
|
119
|
+
```bash
|
|
120
|
+
# a single concept -> Turtle on stdout
|
|
121
|
+
uv run lokf convert examples/acme-knowledge/metrics/weekly-active-users.md --format ttl
|
|
122
|
+
|
|
123
|
+
# the same thing behind the just recipe
|
|
124
|
+
just gen-rdf-turtle examples/acme-knowledge/metrics/weekly-active-users.md
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`--format` also takes `nt`, `jsonld`, `xml`, `n3`, and `trig`; `--output FILE`
|
|
128
|
+
writes to disk instead of stdout. Point `convert` at the bundle directory
|
|
129
|
+
(`examples/acme-knowledge`) to project all six concepts at once.
|
|
130
|
+
|
|
131
|
+
Prefer to stay in Python? `lokf.rdf.serialize` is the same projection the CLI
|
|
132
|
+
calls:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from lokf import rdf
|
|
136
|
+
|
|
137
|
+
# a concept file, or the bundle directory — either resolves IRIs correctly
|
|
138
|
+
print(rdf.serialize("examples/acme-knowledge/metrics/weekly-active-users.md", "ttl"))
|
|
139
|
+
```
|
|
140
|
+
<!-- --8<-- [end:quickstart-rdf] -->
|
|
141
|
+
|
|
142
|
+
This is the whole thesis: OKF authoring in, RDF knowledge graph out.
|
|
143
|
+
|
|
144
|
+
## Status
|
|
145
|
+
|
|
146
|
+
LOKF v0.1 is a **draft profile** and is **not affiliated with or endorsed by
|
|
147
|
+
Google**. "Open Knowledge Format" / "OKF" refer to the format published by Google
|
|
148
|
+
Cloud (`github.com/GoogleCloudPlatform/knowledge-catalog`); LOKF extends it under
|
|
149
|
+
its open terms.
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
CC-BY-4.0 — see [`LICENSE`](https://github.com/nicholsn/lokf/blob/main/LICENSE).
|
|
154
|
+
It's a spec + vocabulary; if you'd rather put the scripts under a code license,
|
|
155
|
+
swap in MIT or Apache-2.0.
|