Part 11. Data validation: validation.md
In SDD, validation is not the phrase "the data is correct." It is a set of facts. In a data project, a fact must link the specification, SQL, and evidence. If a fact cannot be executed by a command, an SQL query, or a manual reviewer step, it is not ready yet.
Example validation facts
### F1 — Customer 360 grain
- Command: `dbt test --profiles-dir . --select mart_customer_360`
- Expectation: `customer_id` is unique and not_null.
- Status: accepted.
### F2 — PII did not leak into mart
- Command: `dbt test --profiles-dir . --select assert_customer_360_no_direct_pii`
- Expectation: the test returns 0 rows.
- Status: accepted.Automated and manual facts
Automated facts are triggered by a command. Manual facts require reading a change or business confirmation. Both types are needed. dbt does not know that "active customer" is defined correctly unless it is written down in the specification.
A good manual fact:
The reviewer confirmed that adding `product_code` would change the grain and is
out of scope for this phase.A bad manual fact:
Looks fine.Where to store validation
In the tutorial example, validation notes live in specs/validation/. This is not
necessarily the only place, but the rule is: validation.md must be versioned and readable after /clear. If a fact lives only in chat, it cannot serve as release evidence.
Qwen prompt
Create a draft validation.md for mart_customer_360.
Use specs/models/mart_customer_360.md, ODCS, ODPS, and models/schema.yml.
Do not modify dbt models.Minimum output
A minimum validation.md for a mart must contain:
- one fact about grain;
- one fact about PII;
- one fact about required contract fields;
- one fact about lineage or the list of input models;
- one manual fact: the change does not modify contract fields without approval.
If a fact cannot be verified, rewrite it as a command, an SQL query, a dbt test, or a reviewer step.
Breakdown for the reader
validation.md is the place where the tutorial deliberately becomes strict. As long as a fact has no command, SQL query, or manual reviewer step, it remains a wish. The phrase "the data is correct" protects nothing: an agent may consider correctness to mean the absence of execution errors, an analyst may consider it to mean the absence of nulls, a product owner may consider it to mean that the grain is preserved. A validation fact removes that ambiguity.
Not every fact has to be automated. In data there are decisions that require reading the change and understanding the contract. For example, dbt can prove that customer_id is unique, but it cannot decide whether adding product_code to Customer 360 is acceptable. Such a fact is better left manual and explicitly assigned to a reviewer. Manual does not mean weak; it becomes weak only when it does not specify what exactly to read and what conclusion to draw.
A good validation note links several layers: the model specification, ODCS, models/schema.yml, singular tests, and the reviewer report. If one of the layers changes, validation.md should show which facts need to be revisited. This makes a data change resemble an engineering process rather than a collection of scattered SQL patches.
The reader should get used to writing validation.md before SQL. It feels awkward only the first time. After that, validation facts start helping: they limit the size of the solution, suggest which tests are needed, and give the reviewer a ready-made rubric. If validation.md is written after SQL, that file often turns into a justification of what was already done.
Practice
Take one weak item like "check data quality" and rewrite it in
three forms: a dbt command, an SQL/singular test, and a manual reviewer fact.
Typical mistake
Writing "check data quality." That is not a fact. A fact sounds like this: "customer_id is unique in mart_customer_360, the command `dbt test --select mart_customer_360` returns exit code 0".
Review questions
- How does a validation fact differ from a wish?
- Which facts cannot be fully automated?
- Why should a reviewer read validation.md before a change?