Docs › KGL format

KGL format reference

KGL (Knowledge Graph Language) is a plain text file format for storing structured knowledge graphs. Files are human-readable, diff cleanly in git, and can be read and edited with any text editor.

Package: The KGL parser lives in the kgl-lang PyPI package. Graxeon Core consumes it but does not own the format spec.

File structure

A .kgl file contains one or more nodes separated by blank lines. Each node starts with a header block followed by an optional body section. 

@node Article
@type Article
@field title: The Transformer Paper
@field author: Vaswani et al.
@field published: 2017-06-12
@tag ai, transformers
@link Concept/Transformer Architecture
---
The *Attention Is All You Need* paper introduced the Transformer architecture,
which replaced recurrent networks with self-attention mechanisms.

Key contributions:
- Multi-head self-attention
- Positional encodings
- Encoder-decoder structure

Node anatomy

@node

The node's unique name within the collection. Required. Names are used as identifiers for linking — they must be unique within a file and across the collection. 

@node Attention Is All You Need

@type

One or more type names from the collection's schema. A node can have multiple types (one per @type line). Types determine which schema fields are expected. 

@type Article
@type ResearchPaper

@field

A structured key-value field. The key is the field name; the value is everything after the colon and leading space. Fields can hold any string value — Graxeon Studio renders them according to the field type defined in the schema. 

@field title: The Transformer Paper
@field published: 2017-06-12
@field open_access: true

Asset-backed fields (images, videos, files) use the graxeon-asset:// URI scheme:

@field cover_image: graxeon-asset://abc123def456

@tag

A comma-separated list of tags. Tags are used for filtering and discovery. 

@tag ai, transformers, nlp, 2017

@link

A relationship to another node. Links are Collection/Node name or just Node name (same collection). Multiple links use multiple @link lines. 

@link Concept/Transformer Architecture
@link Person/Ashish Vaswani
@link Venue/NeurIPS 2017

Body section

After a --- separator, the rest of the node is the body — free-form Markdown text. The body is rendered as rich text in Studio and Explorer. 

---
## Summary

The paper that started the modern NLP revolution. It showed that...

- Point one
- Point two

Complete example

@node Transformer Architecture
@type Concept
@field domain: Machine Learning
@field first_described: 2017
@field complexity: High
@tag architecture, attention, nlp
@link Article/Attention Is All You Need
@link Person/Ashish Vaswani
---
The Transformer is a sequence-to-sequence model that relies entirely
on attention mechanisms, dispensing with recurrence and convolutions.

### Components

- **Multi-head attention** — parallel attention heads over different representation subspaces
- **Feed-forward layers** — position-wise fully connected layers
- **Positional encoding** — injected sine/cosine signals since there is no recurrence

### Impact

Transformers became the foundation of BERT, GPT, and virtually every
state-of-the-art NLP model from 2018 onward.

Multiple nodes per file

A single .kgl file may contain multiple nodes. Nodes are separated by one or more blank lines after the body ends. Studio writes all nodes in a collection into a small number of files for efficiency. 

@node Node One
@type Thing
@field x: 1

@node Node Two
@type Thing
@field x: 2
---
Body text for node two.

Schema fields

Studio supports the following field types. The type is stored in the schema, not in the .kgl file itself — all field values are stored as strings and interpreted at render time.

Previous ← Getting started
Next Studio guide →