Declaring resource properties

Overview

While configurations tell dbt how to build something in your warehouse (for example, whether a model should be a table or view, or which SQL to use when running a snapshot), resource properties are used to declare things about your dbt project or data warehouse.

For example, you can use resource properties to:

• Describe models, snapshots, seed files, and their columns
• Assert "truths" about a model, in the form of tests, e.g. "this id column is unique"
• Apply tags to resources
• Define existing tables contains raw data as sources
• Assert the expected "freshness" of this raw data

In dbt, these properties are declared in .yml files, in the same directory as your resources. There's a few quirks for backwards compatibility reasons:

Resource	Default directories	Defined by
models	models/	source-paths
sources	models/	source-paths
seeds	data/ or models/	data-paths or source-paths
snapshots	snapshots/ or models/	snapshot-paths or source-paths
analyses	analyses/ or models/	analysis-paths or source-paths
macros	macros/ or models/	macro-paths or source-paths

You can name these files whatever_you_want.yml and nest them arbitrarily deeply in subfolders within each directory.

info

schema.yml files

Previous versions of the docs referred to these as schema.yml files — we've moved away from that terminology since the word schema is used to mean other things when talking about databases, and people often thought that you had to name these files schema.yml.

(Of course, you're still free to name your files schema.yml)

Example

Here's an example that defines both sources and models for a project:

models/jaffle_shop.yml

version: 2

sources:
  - name: raw_jaffle_shop
    description: A replica of the postgres database used to power the jaffle_shop app.
    tables:
      - name: customers
        columns:
          - name: id
            description: Primary key of the table
            tests:
              - unique
              - not_null

      - name: orders
        columns:
          - name: id
            description: Primary key of the table
            tests:
              - unique
              - not_null

          - name: user_id
            description: Foreign key to customers

          - name: status
            tests:
              - accepted_values:
                  values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']


models:
  - name: stg_jaffle_shop__customers
    columns:
      - name: customer_id
        tests:
          - unique
          - not_null

  - name: stg_jaffle_shop__orders
    columns:
      - name: order_id
        tests:
          - unique
          - not_null
      - name: status
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']

Related documentation

You can find an exhaustive list of each property for a resource in the following docs:

• Model Properties
• Source Properties
• Seed Properties
• Snapshot Properties
• Analysis Properties
• Macro Properties

FAQs

 Does my `.yml` file containing tests and descriptions need to be named `schema.yml`?

No! You can name this file whatever you want (including whatever_you_want.yml), so long as:

• The file is in your models/ directory¹
• The file has .yml extension

Check out the docs for more information.

¹If you're declaring properties for seeds, snapshots, or macros, you can also place this file in the related directory — data/, snapshots/ and macros/ respectively.

 If I can name these files whatever I'd like, what should I name them?

It's up to you! Here's a few options:

• Default to the existing terminology: schema.yml (though this does make it hard to find the right file over time)
• Use the same name as your directory (assuming you're using sensible names for your directories)
• If you test and document one model (or seed, snapshot, macro etc.) per file, you can give it the same name as the model (or seed, snapshot, macro etc.)

Choose what works for your team. We have more recommendations in our guide on structuring dbt project.

 Should I use separate files to declare resource properties, or one large file?

It's up to you:

• Some folks find it useful to have one file per model (or source / snapshot / seed etc)
• Some find is useful to have one per directory, documenting and testing multiple models in one file

Choose what works for your team. We have more recommendations in our guide on structuring dbt project.

 Can I add tests and descriptions in a config block?

No — properties (including tests and descriptions) must be declared in separate .yml files, rather than in config blocks.

Configurations:

• tell dbt how to build something in your warehouse (for example, whether a model should be a table or view, or which SQL to use when running a snapshot)
• are defined in your dbt_project.yml file or a config block in a .sql file.

Properties:

• are used to declare things about your dbt project or data warehouse.
• are defined in separate .yml files

For now, these things are separate to each other, but in the future, we may choose to co-locate them in the same file.

 Why do model and source yml files always start with `version: 2`?

Once upon a time, the structure of these .yml files was very different (s/o to anyone who was using dbt back then!). Adding version: 2 allowed us to make this structure more extensible.

Currently, Version 2 is the only supported version for these files. We kept version: around as a required key so that in the future, if we need to introduce a new structure for these files, we'll be able to do this more easily.

 Can I use a yaml file extension?

No. At present, dbt will only search for files with a .yml file extension. In a future release of dbt, dbt will also search for files with a .yaml file extension.

Troubleshooting common errors

Invalid test config given in [model name]

This error occurs when your .yml file does not conform to the structure expected by dbt. A full error message might look like:

* Invalid test config given in models/schema.yml near {'namee': 'event', ...}
  Invalid arguments passed to "UnparsedNodeUpdate" instance: 'name' is a required property, Additional properties are not allowed ('namee' was unexpected)

While verbose, an error like this should help you track down the issue. Here, the name field was provided as namee by accident. To fix this error, ensure that your .yml conforms to the expected structure described in this guide.

Invalid syntax in your schema.yml file

If your .yml file is not valid yaml, then dbt will show you an error like this:

Runtime Error
  Syntax error near line 6
  ------------------------------
  5  |   - name: events
  6  |     description; "A table containing clickstream events from the marketing website"
  7  |

  Raw Error:
  ------------------------------
  while scanning a simple key
    in "<unicode string>", line 6, column 5:
          description; "A table containing clickstream events from the marketing website"
          ^

This error occurred because a semicolon (;) was accidentally used instead of a colon (:) after the description field. To resolve issues like this, find the .yml file referenced in the error message and fix any syntax errors present in the file. There are online yaml validators that can be helpful here, but please be mindful of submitting sensitive information to third-party applications!