Favor long-lived data formats (markdown + frontmatter)
Status: open/published
Draft. Stub for user to flesh out. Captured under M-0000.
Summary
Section titled “Summary”- Substrate is plain text under git: markdown with YAML frontmatter.
- Tool churn is constant; data outlives the tool. Plain text + git is the longest-lived substrate short of paper.
- No bidirectional DB sync; markdown is canonical, not a backup of some other source of truth.
- Authoring typically through an API wrapper with code-based validators; direct manipulation also allowed.
Statement
Section titled “Statement”The substrate of sdlc’s data model is text under git. Specifically markdown with YAML frontmatter. Schemas layer over that substrate; validators enforce structure; tooling queries and indexes. The underlying file remains a plain text document that can easily be consumed by human or LLM.
- allows evolutionary progression from loose narratively defined data to more tightly defined data structures (via frontmatter schemas)
- easy for tooling (bash)
- free UI for review and editing by humans during early high churn phases (like Obsidian)
- lives with and complements existing SDLC tools, namely git and GitHub
The core insight: tool churn is constant; the data outlives the tool. Bespoke binary formats, database schemas, and SaaS-shaped state all couple the data to a specific runtime; plain text + git is the longest-lived substrate available short of paper.
How it applies
Section titled “How it applies”- Every entity in sdlc is a markdown file with YAML frontmatter
- Tooling that builds caches, indices, or rendered views derives them from the markdown
- no bidirectional db syncing (for now)
- authoring is typically mediated through an API wrapper, but also allows direct manipulation and relies on code-based validators
- will project the data as needed via the API wrapper
- in-body structure will also be enforced as a data model over the entity document evolves
Examples
Section titled “Examples”- Every entity in sdlc lives as a markdown file with YAML frontmatter under git.
plugin/validators/validate_frontmatter.tsreads markdown directly; no database, no parallel cache to keep in sync.docs/dashboard.baseis a thin YAML view config over the markdown corpus; Obsidian computes the table at open-time.- GitHub PRs review individual markdown files; no proprietary review format to translate to.
Implications
Section titled “Implications”Connects to P-0005-schema-over-prose: Loose narrative in body is where unstructured data can start. As schema solidifies, markdown structure validations and migrations to and expansion of frontmatter fields will occur.
This principle derives from P-0003-pragmatic-architecture. At some point, where product needs dictate, this principle may be deprecated.