I have an issue trying to document a model

I have a dbt.project.yml file. The file looks like this :

'# Name your project! Project names should contain only lowercase characters
'# and underscores. A good package name should reflect your organization’s
'# name or the intended use of these models
name: ‘edw’
version: ‘1.0.0’
config-version: 2

'# This setting configures which “profile” dbt uses for this project.
profile: ‘edw’

'# These configurations specify where dbt should look for different types of files.
'# The model-paths config, for example, states that models in this project can be
'# found in the “models/” directory. You probably won’t need to change these!
model-paths: [“models”]
analysis-paths: [“analyses”]
test-paths: [“tests”]
seed-paths: [“seeds”]
macro-paths: [“macros”]
snapshot-paths: [“snapshots”]

clean-targets: # directories to be removed by dbt clean

  • “target”
  • “dbt_packages”

'# Configuring models
'# Full documentation: Model configurations | dbt Developer Hub

'# In this example config, we tell dbt to build all models in the example/
'# directory as views. These settings can be overridden in the individual model
'# files using the {{ config(...) }} macro.
name: ReRead_Source_File
description: This is just a random description.
'# Config indicated by + and applies to all files under models/example/
+materialized: view

I can run dbt debug, dbt build, dbt run, dbt docs generate and dbt docs serve, but for the model ReRead_Source_File the description states : “The model is not currently documented”.

I have tried creating a .YML file for the model in the same folder as the model. Still no joy.
Basically, I am clueless as to how to add something as basic as a description.

Clearly debug thinks my file is OK, but I am not putting the description in the right place. Hopefully an easy one for those that have more than a couple of days experience. I am only learning - so ignore the naming etc - just trying to see how things hang together.

Note I put a ’ in front of each # has then it displayed better in this post than without - but it is not in the file on the system

I have also tried putting this in the model :

{{ config(description=‘Does this work’) }}

select * from {{ ref(‘Projects_Type1_and_2’) }}

Just an update. I have found if I create a file in the models folder which looks like this it works :

version: 2


  • name: ReRead_Source_File
    description: Hello World

Should that work if I put it in the project.yml file at the root level of the project - or does it have to be in the models folder. I suppose I have this working - but am unsure as to whether I have in the correct place, or the only place.



I added another model and now after removing it get the following error :

The schema file at models\Descriptions.yml is invalid because the value of ‘models’ is not a list

What does this mean?

Model documentation is handled in the model’s yml file (like in your third message), not the dbt_project.yml file.

The jaffle_shop repo may be helpful to you - the folder I linked has two models (customers, orders) that are both documented in schema.yml. The error you’re getting sounds like a misconfiguration of the values under models:. Would expect something like:

version: 2

   - name: ReRead_Source_file
     description: model description

   - name: second_model
     description: model description

The schema.yml file in that repo should also show you how to document the columns in those models. Hope this helps!

Thanks Lisa. May have had some strange characters in my schema.yml file - so started again and working as expected. Thanks