Schema over prose; model everything that can be modeled
State: open/published
Summary
Section titled “Summary”- Every entity is a schema-validated artifact, not prose alone; the frontmatter contract is parsed once and consumed by tooling.
- Prose is for what needs human judgment (Why, Rationale, History) and for what cannot yet be modeled; the parts that drive behavior are structured.
- Schema is the prerequisite to determinism: a deterministic workflow reads structured inputs reliably and cannot reliably parse prose.
- Schema modeling is a direction, not a binary state.
Statement
Section titled “Statement”Every entity of the system (every concept it tracks, acts on, or reasons about) is modeled as a schema-validated artifact, not as prose alone. The default form of a definition is a schema with a frontmatter contract. Prose holds what the schema cannot yet capture; it is not the substrate the system runs on.
Prose is unstructured. A reader, human or agent, parsing a prose specification derives the same information every time, with the same risk of getting it wrong. A system whose substance lives in prose cannot be validated, queried, or aggregated by tooling; every operation re-extracts its inputs from natural language.
Schema-modeled artifacts collapse that cost. The frontmatter contract is parsed once; validators, sort scripts, query engines, and eval harnesses work against structured data. Prose is reserved for what needs human judgment to read (Why, Rationale, History); what drives behavior is explicit and verifiable.
This is stronger than “use frontmatter where convenient”. Schema modeling is the target end state for all entities. Anything not yet modeled is either not yet understood well enough to model, in which case modeling it is the next step, or genuinely unmodelable, which is rare, in which case the prose shape itself is structured (a skill body’s section shape, for example).
How it applies
Section titled “How it applies”- Every entity ships its full definition surface (S-0005-entity-definition-contract); the schema is the load-bearing piece.
- Every artifact under
docs/planning/is validated at write time against the schemas undersolutions/ontological/lib/model/entities/(sdlc entities validate). - The Capability tree (C-0001 and siblings) is schema-validated under the Capability entity, not prose that describes capabilities.
- A decision that has not crystallized into a schema (parts of D-0003-datamodel-categorization, for example) lives as a prose Decision because its form is still in flux. Decisions start as prose; ask “what schema comes out of this?” early.
Examples
Section titled “Examples”solutions/ontological/lib/model/entities/task/schema.tsand the milestone schema beside it: the frontmatter contracts that drive sort, validation, and dashboards.- S-0005-entity-definition-contract: a Standard about what every entity must ship, a schema about schemas.
sdlc entities validate: a pure consumer of the schemas, recognizing entities by type with no per-entity branching.docs/dashboard.base: an Obsidian view derived from schema-modeled frontmatter (need_human_review), with no hand-maintained list.
Implications
Section titled “Implications”- Some concepts will resist clean modeling. Try anyway, and lean toward schema whenever it is plausible; the gap between what is modeled and what ought to be is itself data about the system’s maturity.
- Tooling investment compounds. Once an entity is schema-modeled, every new operation against it (validators, queries, eval harnesses, dashboards) is cheaper and works uniformly. Prose-shaped entities get none of this.
- Schema-over-prose is prerequisite to P-0001-prefer-deterministic-over-llm, not adjacent to it: a deterministic workflow can read structured inputs and cannot reliably parse prose.
- The planning entities (Decision, Standard, Principle, Milestone, Epic, Backlog) being schema-modeled is itself an instance of this principle. SDLC’s planning artifacts are SDLC’s own data.