Documentation · rule model-undocumented
dbt models with no description
A Metacenta review checks this under the rule Models carry a description. Everything below applies whether or not you ever commission one.
What this rule checks
This rule flags every dbt model whose description is empty in its schema YAML. A description written in a {% docs %} block and referenced with {{ doc() }} counts.
Why it matters
Without a description, a reader can only learn what a model means by reading its SQL. Most will not, so each team works out its own meaning, and the definitions drift apart. We rate the finding higher on a final model in a marts folder, because more people read those.
How to fix it
Document the models. Add a description: to the model's schema YAML. Say what one row is, what the model is for, and anything a reader would get wrong without being told.
Before:
models:
- name: fct_orders
After:
models:
- name: fct_orders
description: >
One row per completed order. Excludes test orders and
orders refunded in full within 24 hours.
When it is fine to leave
An intermediate model that only one other model reads, whose name already says what it does, can go without. Describe the models people query, and the ones others build on.
What we need to check it
manifest.json alone, which dbt parse writes.
Published rules it corresponds to
dbt_project_evaluator, rule fct_undocumented_models. Ours checks the same condition and threshold.
dbt_project_evaluator, rule fct_undocumented_public_models. Ours checks everything it flags, and more. dbt raises this only for models declaring access: public; this check raises it for every undocumented model, so it covers that rule and more. Deliberately NOT a second check — a public model would then appear twice on the worklist for one missing description.
This means our check corresponds to their rule. It does not mean the publisher reviewed or endorses it.