Frontmatter Schema

The canon has over 400 documents with no authoritative frontmatter schema. Fields, types, and quoting rules have been copied ad-hoc from whatever document an agent finds first. This has produced: unquoted values that parse as wrong types (dates as date objects, tiers as integers, booleans as booleans), inconsistent field presence across documents of the same audience, and silent rendering failures when the site's build system encounters unexpected types.

This document fixes the problem by defining the schema once. Templates (canon/meta/TEMPLATE.md, docs/TEMPLATE.md) define document structure. This document defines field requirements. When they disagree, this document wins.

YAML frontmatter values follow a simple pattern derived from the working corpus: quote strings that contain special characters, leave simple identifiers and native types unquoted.

# Simple identifiers — unquoted
audience: canon
exposure: nav
voice: neutral
stability: semi_stable
type: essay
author: Klappy
slug: my-article-slug
epoch: E0007
status: active

# Integers — unquoted
tier: 2

# Booleans — unquoted
public: true
archived: false

# Dates — unquoted
date: 2026-04-04

# URIs — unquoted
uri: klappy://canon/principles/example

# Strings with special characters — quoted
title: "My Title — With Dashes and Colons: Like This"
subtitle: "Why it matters"
description: "A sentence with punctuation, dashes — and other characters."
hook: "The one-liner that grabs attention."
derives_from: "canon/values/axioms.md, canon/principles/other.md"
complements: "docs/path/to/sibling.md"
governs: "All documents in this scope"

# Arrays — inline with quoted strings
tags: ["canon", "principle", "example"]

The test is simple: if the value is a single word or simple identifier (no spaces, no special characters), leave it unquoted. If it contains spaces, punctuation, or special characters, quote it. Booleans, integers, and dates are always unquoted — the renderer expects native YAML types, not strings.

These eight fields are required on every document in the knowledge base, regardless of audience:

audience: "canon"

Canon documents define program-level constraints.

audience: "docs"

Docs documents define implementation details, planning, and operational guides.

audience: "public"

Public documents include essays, articles, about pages, and website navigation pages. Essays and articles have additional required fields for site rendering.

All public documents:

Additional fields required when type is "essay" or "article":

About pages, indexes, and navigation pages (about/, READMEs, positioning docs) do not need slug, author, type, or social metadata. They render through structural routes, not content templates.

audience: "operators"

Operator documents are tool references and MCP server documentation.

audience: "apocrypha"

Apocrypha documents are system-voice fragments, predocumentaries, and reconstructions.

audience: "odd"

ODD documents define universal philosophy and methodology.

Any document can be archived by adding:

archived: "true"
archived_reason: "E0005.1 — superseded by description"

Archived documents remain in the knowledge base for history but are excluded from active navigation and search prioritization.

target_repo is an optional, cross-cutting field (it applies to documents of any audience) that declares which repository a file belongs to once the klappy.dev knowledge base bifurcates. It is the only routing signal extraction relies on: a later move is git grep target_repo plus copy, never a re-organization.

Values:

• "outcomes-driven-development" — the portable core: universal governance and canon an outside adopter needs.
• "oddkit" — the engine's own documentation and engine/release/telemetry governance.
• "undecided" — contested; resolved deliberately before the file moves. Used for cross-cutting files and genuine judgment calls.
• Absent — stays in klappy.dev (the personal overlay, the default home).

Only files that leave klappy.dev carry the tag; the overlay's own files stay untagged. Non-markdown files cannot carry frontmatter, so their routing is recorded in canon/meta/scope-map.json instead. A malformed value is a merge-gate failure (the validator enum-checks this field), so a bad route never reaches the renderer. Governing document: klappy://docs/repo-bifurcation-and-target-repo-routing.

• Type mismatches. If a boolean field like public is quoted as "false" (a truthy string) instead of false (a boolean), the renderer behaves incorrectly. If an integer field like tier is quoted as "2" instead of 2, type comparisons fail.
• Blank pages in PR previews. The most common symptom of frontmatter errors. Usually caused by quoted booleans/integers that should be native types, missing slug on public essays, or missing type on essays.
• Copying frontmatter from another document. The smell itself. If the source of truth for frontmatter is "whatever document I found first," the schema is not being consulted. Consult this document instead.
• Fields that don't appear in this schema. If you're adding a field that doesn't appear here, either this schema needs updating (propose the addition) or the field is ad-hoc and shouldn't be added.

1. Match the type the renderer expects. Booleans unquoted (true/false), integers unquoted (2), dates unquoted (2026-04-04), simple identifiers unquoted (canon, nav), complex strings quoted ("Title — With Special Characters").
2. Check required fields. Consult the audience-specific table above. If required fields are missing, add them.
3. Consult this document, not other documents. Do not copy frontmatter from another file to fix the problem. This schema is the source of truth.
4. If this schema is incomplete, update it. If a legitimate field is missing from this schema, add it here first, then use it. The schema must stay current with actual usage.

This schema is a preflight and validate checkpoint. When the deliverable is a document, frontmatter compliance is a Definition of Done requirement alongside the Writing Canon checklist.

The schema was derived from corpus analysis of 389 documents on April 4, 2026, and should be maintained as the canon evolves. Fields that appear in fewer than 5% of documents within an audience are not listed unless they serve a specific structural purpose.

• Writing Canon — progressive disclosure and structural requirements for document bodies
• Canon Article Template — structural template for canon documents (consult this schema for field requirements)
• Epistemic Obligation and Document Tiers — what tier values mean
• Definition of Done — completion requirements including frontmatter compliance