Schema over prose; model everything that can be modeled

Status: open/published

Summary

Every entity is a schema-validated artifact, not just prose; the frontmatter contract is parsed once and consumed by tooling.
Prose is reserved for parts requiring human judgment (Why, Rationale, History) and where explicit rigid modeling is not feasible; behavior-driving parts are structured.
Prerequisite to determinism: deterministic workflows read schema-structured inputs reliably; they cannot reliably parse prose.
Schema modeling is a direction, not a binary state.

Statement

Every entity of the system (every concept the system tracks, acts on, or reasons about) is modeled as a schema-validated artifact, not as prose alone. The default form for definition is a schema with a frontmatter contract; prose is what the schema can’t yet capture, not the substrate the system runs on.

Why

Prose is unstructured. A reader (human or agent) parsing a prose-defined product specification has to derive the same information every time, with the same risk of getting it wrong. The cost compounds: a system whose substance lives in prose can’t be validated, queried, or aggregated by tooling. Every operation has to re-extract its inputs from natural language.

Schema-modeled artifacts collapse that cost. The frontmatter contract is parsed once by tooling; downstream consumers (validators, sort scripts, query engines, eval harnesses) work against structured data. Prose is reserved for the parts that require human judgment to read (the Why, the Rationale, the History); the parts that drive behavior are explicit, structured, and verifiable.

This is a stronger claim than “use frontmatter where convenient.” It asserts that schema modeling is the target end state for all entities. Anything not yet modeled is either (a) not yet understood well enough to schema-fy (in which case modeling it is the next step), or (b) genuinely unmodelable (rare), in which case the prose shape is itself a structured artifact (e.g. a skill body’s section shape).

How it applies

Every entity ships its full definition surface (S-0005-entity-definition-contract), of which the schema is the load-bearing piece.
Every artifact under docs/planning/ and plugin/lib/model/entities/ is schema-validated at write time (plugin/validators/).
The Capability tree (C-0001 et al) is schema-validated under the Capability entity; it’s not just prose docs that describe capabilities. The distinction matters because the schema lets tooling derive the contains relationship from parent_key, enforce cycle-freeness, render the tree, etc.
Decisions that haven’t crystallized into a schema yet (e.g. parts of the D-0003-datamodel-categorization ADR) live as prose ADRs because the decision form is still in flux. The principle accepts that ADRs start as prose; it asks the next-step question (“what schema comes out of this ADR?”) early.

Examples

plugin/lib/model/entities/task/schema.json and plugin/lib/model/entities/milestone/schema.json: the frontmatter contracts that drive sort, validation, and dashboards.
S0005 entity definition contract: a Standard about what every entity must ship (a schema about schemas).
plugin/validators/validate_frontmatter.ts: pure consumer of the schemas; recognition by type, no per-entity branching.
docs/dashboard.base: an Obsidian view derived directly from schema-modeled frontmatter (need_human_review), zero hand-maintained list.

Implications

The ideal will be impossible: some concepts will resist clean modeling. The principle says try anyway; the gap between “what we model” and “what we ought to model” is itself useful data about the system’s maturity.
Tooling investment pays off compoundingly. Once an entity is schema-modeled, every new operation against it is cheaper and more reliable: validators, queries, eval harnesses, status dashboards, all work uniformly. Prose-shaped entities don’t get this benefit.
P-0001-prefer-deterministic-over-llm’s natural progression compresses the LLM’s role as workflows mature. Schema modeling is the substrate that makes that compression possible: a deterministic workflow can read schema-structured inputs; it can’t reliably parse prose. Schema-over-prose is prerequisite to deterministic-over-LLM, not just adjacent to it.
The Planning-meta entities (ADR, Standard, Principle, Milestone, Epic, Backlog) being schema-modeled is itself an instance of this principle. The planning artifacts of sdlc are themselves sdlc’s data.

Notes

Schema modeling is a direction, not a binary state. Some entities will always have more prose than others; lean toward schema whenever it’s plausible.

← Back to Principles