PGM 0.4.0 Public Draft

Property graphs.
In Markdown.

The PGM Public Draft extends Open Knowledge Format (OKF) with semantic relationships. Describe how your concepts relate, with properties on every connection, all in ordinary Markdown.

Explore the demoRead the specification
Built onOKF 0.2CommonMark 0.31.2YAML 1.2.2
people/ada-lovelace.md
plain Markdown
---
type: Person
title: Ada Lovelace
---

# Ada Lovelace

[Analytical Engine](../work/analytical-engine.md "{type: contributed_to, from: 1842, to: 1843, role: \"analysis and exposition\"}")
The meaning of this connectionExplore it
contributed_toPersonAda LovelaceWorkAnalyticalEngine
role
analysis and exposition
from → to
1842 → 1843

PGM adds property graph semantics, not syntax

Human-readable first. Machine-actionable too.

Open-source graph viewer · Ada Demo Vault

What did Ada contribute, and when?

Start with the connection between Ada and the Analytical Engine. Its role and dates describe the contribution. Open Ada’s note to find the Markdown link behind it, then explore the other connections.

Ada → Analytical EngineLook for contributed_to in the relationship properties below.

Loading Ada’s graph…

Ada Demo Vault · 46 concepts · 124 relationships · CC BY-SA 4.0 · Property Graph Markdown contributors

Try it in Obsidian.

Download the plugin and the complete Demo Vault to explore these relationships in your own workspace.

Plugin + Demo VaultInstallation instructions

A semantic extension of OKF

Keep the documents. Gain the property graph

OKF defines the Knowledge Bundle, Concepts, and Concept Links. PGM adds their property graph meaning. Every PGM bundle remains an OKF bundle, readable without PGM support.

The foundationOpen Knowledge Format 0.2

Concepts · Concept IDs · Concept Links

Adds graph semantics
The semantic extensionPGM Public Draft

Nodes · Relationships · Properties

01

Concepts become nodes

Each OKF Concept becomes a Node. Its Concept ID stays the node identity, and YAML frontmatter becomes node properties.

--- type: Person title: Ada Lovelace ---
02

Links become relationships

Each existing OKF Concept Link becomes a directed Relationship, from the current Concept to its target. Repeated links remain separate relationships.

[Analytical Engine](../work/analytical-engine.md "{type: contributed_to, from: 1842, to: 1843, role: \"analysis and exposition\"}")
03

YAML carries properties

A YAML flow map in the normal link title carries complete edge properties. The type value is additionally exposed as the graph element type.

typecontributed_toroleanalysis and expositionfrom1842to1843

Reference implementation included

From Markdown to portable data.

The same authored relationship can travel to another tool. The pgmark reference processor exports the full graph as JSON, preserving direction, types, and properties. This excerpt shows Ada’s contribution exactly as it appears in the export.

Core TCK + integration tests Language-neutral TCK Python 3.10–3.14
Download the reference processor
ada.graph.json · relationship excerpt
{
  "source": "people/ada-lovelace",
  "target": "work/analytical-engine",
  "type": "contributed_to",
  "properties": ["pgm-yaml", "v1", ["mapping", [
    [["string","from"],["number","1842"]],
    [["string","role"],["string","analysis and exposition"]],
    [["string","to"],["number","1843"]],
    [["string","type"],["string","contributed_to"]]
  ]]]
}

The exchange format tags values so numbers and text retain their types.

Download the complete JSON
Reproduce this export

Requires Python 3.10–3.14. Download the processor with the canonical Demo Vault, then open a terminal in the folder containing the ZIP.

Download processor + Demo Vault
Command platform
python3 -m zipfile -e pgm-reference-processor-0.4.0a1.zip .
cd pgm-reference-processor-0.4.0a1
python3 -m venv .venv
.venv/bin/python -m pip install --constraint parser/constraints.txt .
.venv/bin/pgmark validate demo-vault
.venv/bin/pgmark parse demo-vault --format json > ada.graph.json

Expected: 46 nodes, 124 relationships, 0 warnings. The export is saved as ada.graph.json.

Open-source Obsidian viewer

Your notes, one connection further.

A deliberately quiet, read-only viewer for PGM 0.4.0 vaults. Open the graph, find a Concept, follow a Relationship, return to the Markdown.

Read-only by design No account or telemetry No runtime network
Download plugin 0.1.1 + Demo VaultDemo Vault only View source
Install in Obsidian
  1. Extract the ZIP. Use your own vault, or open the included example-vault folder as a vault in Obsidian.
  2. Copy main.js, manifest.json, and styles.css into .obsidian/plugins/pgm-viewer/ inside your vault.
  3. Restart Obsidian, enable community plugins, and enable PGM Viewer.
  4. Choose Open PGM viewer from the command palette.

Requires Obsidian 1.5.12 or later. Editing stays in the Markdown editor.

contributed_toPersonAda LovelaceWorkAnalyticalEngine
role
analysis and exposition
from → to
1842 → 1843
Demo Vault is part of the PGM specification

Review-ready by design

Understand PGM in 15 minutes.

Start with the core mapping, inspect one real graph, then verify the behavior in code. The draft is intentionally open for implementation feedback.

01Read the core mappingNodes, relationship occurrences, properties, and types.5 min02Inspect Ada’s graphThe complete 46-Concept Demo Vault, rendered from the reference parser output.3 min03Run the reference parserValidate and export deterministic JSON or Cypher.5 min04Scan the conformance testsExecutable edge cases and a language-neutral Core TCK.2 min

Public draft · open source

A small standard should invite scrutiny.

Try the examples in your own tools, read the specification, and bring edge cases. Interoperability reports and implementation feedback are welcome.

Try the Demo VaultShare feedback