Data Modeling Standard¶
Separate raw inputs from derived data¶
Every product must maintain a clear boundary between data the customer enters (raw input) and data the product computes from it (derived/calculated). This boundary should be visible structurally (different tabs or clearly separated areas — see workbook-architecture-standard.md) and visually (see workbook-visual-design-standard.md). A derived value should never be editable in a way that silently overrides the calculation that produced it.
Use a data dictionary¶
Every product should maintain a data dictionary — a document (within
products/<slug>/) listing every input and key derived field: its name, meaning, data
type, valid range/format, source (customer-entered vs. calculated vs. reference
data), and where it lives in the workbook. This follows the pattern established in the
product template's data-dictionary.md. A data dictionary makes it possible for
someone other than the original builder (including an AI agent doing later
maintenance) to understand the product's data model without reverse-engineering
formulas.
Avoid duplicated data entry points¶
A given piece of information should be entered by the customer in exactly one place. If a value is needed in more than one part of the workbook, it should be entered once and referenced (via formula, named range, or structured reference) everywhere else it's needed — never re-entered. Duplicated entry points create silent data-integrity risks: if a customer updates one copy and not the other, the product produces inconsistent results without any warning.
Practical guidance¶
- Reference data (lookup tables, constants) should live in a dedicated Reference Data area, not be scattered across calculation or input tabs.
- When a derived value is used as an input to a further calculation, it should still be treated as derived (protected, visually distinct) — it does not become an "input" just because another formula depends on it.
- Where a product later needs a data dictionary but the product's specification doesn't exist yet, creating the data dictionary is part of the Definition stage of the product artifact lifecycle (see ../architecture/product-artifact-lifecycle.md), not something deferred to after build.