kgl-lang 0.1.0

Knowledge Graph Language — parser, linter, and query engine

KGL — Knowledge Graph Language

A plain-text file format for building file-system-based knowledge graphs. KGL makes relationships between information first-class citizens — not an afterthought bolted onto a document format.

@Person Alice Nguyen
joined: 2021-03-15
#backend #python

[mentors] → people/diana.kgl#Diana Park
    started: 2023-06
    focus: "backend systems and code review"

→ projects/search-revamp.kgl
~> teams/platform.kgl

No database. No graph engine. Just files, folders, and links — readable by humans and navigable by AI.

---

Why KGL?

Existing formats optimise for data (JSON, CSV) or documents (Markdown, XML). Neither treats relationships as structural. KGL is built around the idea that how things connect is as important as what things are.

• File-system as graph — folders are namespaces, files are nodes, links are edges
• AI-readable by design — hard links (→) signal "follow this", soft links (~>) signal "background context"
• Human-writable — plain text, no tooling required to create or read
• Schema-optional — works without a schema, richer with one
• Git-native — plain text means free version history for your entire knowledge graph

---

Documentation

Document	Description
Syntax Reference	All primitives, field types, and link semantics
Schema	_schema.kgl files, inheritance, and validation warnings
Graph Model	Data structures and relationships

---

Quick start

1. Create your first file

# people/alice.kgl

@Person Alice Nguyen
role: Senior Engineer
joined: 2021-03-15
#backend #python

→ projects/search-revamp.kgl

2. Link to related files

# projects/search-revamp.kgl

@Project Search Revamp
status: in-progress
deadline: 2025-08-01

[staffed-by] → people/alice.kgl#Alice Nguyen
    role: lead engineer
    since: 2024-11-01

3. Add a schema (optional)

# _schema.kgl

@NodeType Person
    joined!: date
    role?:   text

@RelType staffed-by
    from:   Project → Person
    role!:  text
    since!: date

That's it. Your knowledge graph lives in the file system. Query it with grep, traverse it with any file-reading tool, or load it into a graph database via the OpenCypher exporter.

---

File format at a glance

Nodes

@Type Name
@Type|Type Name

A file can contain multiple nodes. Each @Type declaration starts a new node; everything below it belongs to that node until the next @Type.

Fields

key: value
key: "multi word value"

Tags

#tag #another-tag

Links

Syntax	Meaning
→ file.kgl	Hard link — strong relationship, follow for full context
→ file.kgl#Node Name	Hard link to a specific node inside a file
~> file.kgl	Soft link — background context, optional
[rel] → file.kgl	Named relationship
[rel|rel] → file.kgl	Multi-type relationship

Relationship properties

[employs] → people/alice.kgl#Alice Nguyen
    role: lead engineer
    since: 2024-11-01

Indented lines immediately after a link are properties of that relationship. They are scoped to the relationship, not the node.

Free text body

---
Prose goes here. Not parsed as fields.
Useful for context, notes, and nuance that fields can't capture.

---

Schema

A _schema.kgl file defines node types, required fields, and allowed relationships. Schema is warning-only — files without required fields are valid but flagged by a linter.

Place _schema.kgl at the graph root for global rules, and in any subfolder to extend or tighten the global schema for that folder.

---

File extension

.kgl — stands for Knowledge Graph Language.

---

Status

Early design stage. Contributions and feedback welcome.

---

License

MIT