StackMap
Subscribe
Explore / vault-ld
The-Knowledge-Graph-Guys

vault-ld

An open spec for Markdown vaults as linked data: YAML-LD frontmatter plus a shared @context makes notes an RDF graph, with reference scripts that round-trip vault to Turtle and back.

224 22 Python Apache-2.0updated 1 months ago
knowledge-graphs
View on GitHubDispute this mapping →
Curator's take

Read it if you keep an Obsidian-style vault and also own RDF ontologies: it makes a note and an OWL class the same kind of object, so business semantics land inside the wiki your team already edits while the ontology gains a human-readable surface. The roundtrip is the real claim — Turtle in, Markdown editing, Turtle out, with anything unmappable flagged rather than silently dropped. Set expectations: this is a specification plus two reference Python scripts (`vault_to_rdf.py`, `rdf_to_vault.py`) and an example vault — no UI, no server, no query engine — and blank nodes and language tags sit outside what the format can express.

Mapped by ShipWithAI editors · links verified
README.md
Vault-LD logo

Vault-LD

An open format for knowledge that two very different readers can share at once:
a person editing notes, and a machine reasoning over a graph.

CI Release Docs License GitHub stars Issues Contributions welcome

Specification · Docs site · Example vault · Contributing

RDF in the Vault

Karpathy's "LLM wiki" idea points at something real: a directory of plain Markdown notes is one of the most powerful ways to work with LLMs. It is readable by you, chunkable by a model, and diffable in git, with no database required. The YAML frontmatter at the centre of this approach carries a hidden pattern: it can map onto YAML-LD (JSON-LD with a YAML serialization). Resolve that frontmatter through one shared context and your notes stop being tagged text. They become linked data.

This matters for anyone already invested in RDF-based ontologies. Your business semantics (your classes, properties, and controlled vocabularies) drop straight into the wiki your team already uses, much as schema.org gave web pages a shared vocabulary without asking authors to leave HTML. The benefit runs both ways: business semantics arrive inside the wiki, and the ontology gains a human-friendly surface, where classes and properties can be read and edited as notes rather than as raw Turtle.

Both directions work because of the roundtrip. Since the frontmatter is YAML-LD, a note and an ontology definition are the same kind of object, and either can be projected losslessly to RDF and back. An ontology can enter as Turtle, be edited as Markdown, and leave as Turtle again, or the reverse, with no canonical "real" form privileged over the other.

Vault-LD

What's here

  • SPEC.md: the normative reference. It defines how frontmatter becomes a knowledge graph (§4) and how any RDF graph round-trips through the vault format with full fidelity (§5), along with terminology, directory structure, conformance criteria, and a compatibility profile for lifting OKF-style Markdown bundles into linked data (Appendix B).
  • Vault-LD Example/: a complete, copyable vault that demonstrates every rule in the spec. It holds one ontology (Culinary), one controlled vocabulary (Difficulty Levels), and one instance (hummus). Its root context.jsonld composes the Culinary ontology's own context, showing how multiple contexts compose (SPEC §4.2).
  • scripts/vault_to_rdf.py: a

Continue your stack

What teams reach for next — and why each earns a place beside vault-ld. Ranked by curator confidence.