Leji decision record frontmatter

Validates the YAML frontmatter of a decision record. The markdown body carries context, decision, and consequences in prose.

Canonical $id: https://leji.org/schemas/v1.0/decision-record.schema.json
Raw file: decision-record.schema.json

Fields

# id string required

Stable identifier for this decision, e.g. "adopt-leji".

Pattern ^[a-z0-9]+(-[a-z0-9]+)*$

# title string required

Short title of the decision.

# status "proposed" · "accepted" · "superseded" · "deprecated" · "rejected" required

Lifecycle status of the decision.

# date string required

ISO 8601 date the decision was made or last changed status.

Pattern ^\d{4}-\d{2}-\d{2}$

# deciders array of strings

People who made the decision.

# supersedes string

id of the record this decision replaces.

# supersededBy string

id of the record that replaced this one.

# affectedPaths array of strings

Repository-root-relative paths the decision affects.

# affectedCategories array of "domain" · "system" · "practice" · "governance" · "decisions"

Content categories the decision affects.

# links array of strings

Optional outbound references, e.g. to related decisions or issues.

Schema and example

Schema Example · 0001-adopt-leji.md

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://leji.org/schemas/v1.0/decision-record.schema.json",
  "title": "Leji decision record frontmatter",
  "description": "Validates the YAML frontmatter of a decision record. The markdown body carries context, decision, and consequences in prose.",
  "type": "object",
  "required": [
    "id",
    "title",
    "status",
    "date"
  ],
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Stable identifier for this decision, e.g. \"adopt-leji\".",
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
    },
    "title": {
      "description": "Short title of the decision.",
      "type": "string",
      "minLength": 1
    },
    "status": {
      "description": "Lifecycle status of the decision.",
      "enum": [
        "proposed",
        "accepted",
        "superseded",
        "deprecated",
        "rejected"
      ]
    },
    "date": {
      "description": "ISO 8601 date the decision was made or last changed status.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "deciders": {
      "description": "People who made the decision.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "supersedes": {
      "type": "string",
      "description": "id of the record this decision replaces."
    },
    "supersededBy": {
      "type": "string",
      "description": "id of the record that replaced this one."
    },
    "affectedPaths": {
      "description": "Repository-root-relative paths the decision affects.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
      }
    },
    "affectedCategories": {
      "description": "Content categories the decision affects.",
      "type": "array",
      "items": {
        "enum": [
          "domain",
          "system",
          "practice",
          "governance",
          "decisions"
        ]
      }
    },
    "links": {
      "description": "Optional outbound references, e.g. to related decisions or issues.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

A conforming decision record. This schema validates the YAML frontmatter; the markdown body carries context, decision, and consequences.

---
id: adopt-leji
title: Adopt the Leji context layer
status: accepted
date: 2026-06-10
deciders:
  - Jo Lee
affectedCategories:
  - governance
---

# Adopt the Leji context layer

## Context

Engineering knowledge lived in heads, chat threads, and three diverging tool config files. Agents produced code that didn't match our invariants because the invariants weren't written anywhere a tool could read.

## Decision

Adopt Leji at the `indexed` level: manifest, boot profile, domain and system content, decision records, generated index, machine changelog.

## Consequences

Vendor config files become one-line redirects. Context fixes ride the same PRs as the work that surfaces them. Jo owns the context layer.

← All schemas