Knowledge Graph Ontology Specification

Template Overview

A personal knowledge base scales smoothly only when governed by consistent data modeling principles. When note schemas, frontmatter keys, and link types vary wildly, automated search and knowledge synthesis break down. The Knowledge Graph Ontology Specification defines entity schemas, valid predicate types, tag rules, and validation constraints in plain Markdown.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Ontology Spec: [Vault Name / Personal Knowledge Base]"
date_ratified: [YYYY-MM-DD]
ontology_architect: "[[Your Name]]"
ontology_version: "v2.0"
governed_entity_types: 6
governed_predicates: 8
tags: [pkm, ontology, knowledge-graph, data-modeling, architecture]
---

# Knowledge Graph Ontology Specification — [Vault Name]

## 1. Ontology Scope & Architectural Principles
- **Core Purpose:** Standardize YAML frontmatter schemas, note classifications, and relationship semantics across the personal vault.
- **Guiding Principle:** **Minimalism Over Complexity.** Define only the entity types and predicates that genuinely improve searchability and synthesis.

## 2. Canonical Entity Types & Frontmatter Schemas

### Entity 1: `concept` (Atomic Evergreen Notes)
- **Definition:** An enduring idea, mental model, or synthesized claim expressed in the author's own words.
- **Required Frontmatter Schema:**
```yaml
type: concept
maturity: seedling | budding | evergreen
primary_moc: "[[Map of Content]]"
tags: [list, of, domain, tags]

Entity 2: source (External Literature & Media)

• Definition: External books, papers, podcasts, or lectures from which excerpts are drawn.
• Required Frontmatter Schema:

type: source
source_type: book | paper | podcast | lecture
author: "[[Author Name]]"
publication_year: integer
tags: [source, literature]

Entity 3: person (Collaborators, Scholars, Mentors)

• Definition: Individuals referenced across meetings, papers, or correspondence.
• Required Frontmatter Schema:

type: person
organization: string
relationship: colleague | advisor | author
tags: [person, network]

3. Allowed Semantic Link Predicates

When connecting notes with typed relationships, use only the following controlled predicates:

Predicate	Meaning / Direction	Valid Source -> Target	Example Usage
supports	Source provides empirical/theoretical backing for Target	source -> concept	[[Paper X]] supports [[Evergreen Y]]
contradicts	Source refutes or challenges Target	source -> concept	[[Experiment A]] contradicts [[Theory B]]
refines	Source narrows or clarifies Target	concept -> concept	[[Concept A]] refines [[Concept B]]
authored_by	Source created by Person	source -> person	[[The Shallows]] authored_by [[Nicholas Carr]]
subtopic_of	Source is a component of Target	concept -> moc	[[SIMD]] subtopic_of [[Computer Architecture MOC]]

4. Tagging Syntax Rules & Forbidden Practices

• Rule 1 (Lower-case Kebab): All tags must be lower-case with hyphens (e.g., #deep-work, NOT #DeepWork or #deep_work).
• Rule 2 (No Plural Duplication): Use singular form only (e.g., #template, NOT #templates).
• Rule 3 (Tags vs Links): Use Tags for broad genres (#pkm, #systems-programming); use Wikilinks ([[...]]) for specific concepts and people.

5. Automated Validation & Linter Constraints

[!IMPORTANT] Linter Rule Notes missing the type: frontmatter key or containing unregistered tags will be flagged during the weekly automated vault health scan (scripts/lint_vault.py).

6. Action Items

• Run vault audit script to migrate legacy notes to v2.0 ontology.
• Update template scaffolds to reflect standardized schemas.

## Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

```markdown
---
title: "Ontology: Engineering Knowledge Vault v2"
date_ratified: 2026-10-06
ontology_architect: "[[Marcus Vance]]"
ontology_version: "v2.0"
tags: [ontology, knowledge-graph]
---

# Knowledge Graph Ontology Specification — Engineering Vault v2

## 1. Overview
Marcus Vance defined a strict 5-entity schema (Concept, Source, Decision, Person, Project) for the engineering team vault.

## 2. Impact
Eliminated 142 redundant tags and standardized wikilink predicates, enabling instant SQL queries across 12,000 vault notes via embedded SQLite.

When to Use and When to Avoid

When to Use

• Use when scaling a personal or team vault beyond 500 notes to prevent structural chaos.
• Use to establish clear conventions before building automated vault scripts or plugins.
• Use to maintain consistency across multidisciplinary research files.

When to Avoid

• Avoid over-engineering complex ontologies on day one when you have fewer than 50 notes.
• Avoid introducing dozens of obscure predicates that you will never remember to use.

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Analyze the existing vault frontmatter metadata, tags, and note structures:
1. Define a concise set of canonical entity types with standardized YAML frontmatter schemas.
2. Establish a controlled list of semantic link predicates (supports, contradicts, refines).
3. Formulate a complete Knowledge Graph Ontology Specification in Markdown with tagging rules.

Your data remains securely on your Mac with zero cloud exposure.