YAML Formatting Options for dbt Descriptions

dbt’s YAML description field accepts four syntaxes: inline string, folded scalar, literal scalar, and doc block. Each renders differently, interacts differently with whitespace, and has different readability tradeoffs in a schema YAML file.

Inline String

The simplest option. Works for short, single-line descriptions that fit comfortably on one line:

- name: mrt__core__orders
  description: "One row per completed Shopify order, excluding test transactions."

Quotes are optional for simple text, but including them is good practice — they prevent YAML from misinterpreting colons, special characters, or values that look like booleans. Keep inline descriptions under 100 characters. Once they wrap in your editor, readability breaks down and you should switch to a scalar block.

Inline strings are the right call for base model descriptions where the grain and source are simple and well understood, and for column descriptions on self-explanatory columns where you’re mainly adding units or a brief clarification.

Folded Scalar (>)

The folded scalar collapses newlines into spaces. You can wrap long descriptions across multiple lines in your editor while the description renders as a single continuous paragraph:

- name: mrt__marketing__customer_ltv
  description: >
    Customer lifetime value calculations using a 3-year rolling window
    and discounted cash flow methodology (10% annual discount rate).
    One row per customer. Excludes customers with no completed orders.
    Sources: Shopify orders via base__shopify__orders and Stripe
    payments via base__stripe__payments.

That renders as: “Customer lifetime value calculations using a 3-year rolling window and discounted cash flow methodology (10% annual discount rate). One row per customer. Excludes customers with no completed orders. Sources: Shopify orders via base__shopify__orders and Stripe payments via base__stripe__payments.”

The line breaks in the YAML are purely for editor readability — they don’t appear in the rendered description. This is the right default for most model descriptions. It lets you write descriptions that are long enough to be useful without turning your schema YAML into a wall of text.

One gotcha: blank lines do become paragraph breaks. If you leave an empty line inside a folded scalar block, you get two paragraphs. That’s usually not what you want. If you want paragraphs, use the literal scalar instead.

Literal Scalar (|)

The literal scalar preserves line breaks exactly as written. This is useful when you want deliberate paragraph separation or when you’re using Markdown formatting:

- name: mrt__marketing__customer_ltv
  description: |
    Customer lifetime value calculations.

    **Business context:** Used by the retention marketing team to identify
    high-value customers for targeted campaigns.

    **Technical details:** Uses a 3-year rolling window and discounted cash
    flow methodology with 10% annual discount rate.

The blank lines render as paragraph breaks, and the Markdown bold (**) renders in the dbt docs site. This is the right choice when:

• You want to separate a business context section from a technical section
• You’re documenting a complex mart model where the audience split (analysts vs engineers) warrants different sections
• You’re using Markdown tables or lists inside the description

The tradeoff is that literal scalars make YAML files longer and harder to scan. Reserve them for mart model descriptions where the additional structure earns its keep. Staging model descriptions rarely need this level of structure.

One important note on Markdown rendering: the dbt docs site renders Markdown in descriptions, but persist_docs strips all Markdown formatting. If you enable persist_docs to push descriptions to warehouse comments, your bold headers become plain text. Write descriptions that make sense both ways if you use both features.

Doc Blocks ({{ doc() }})

Doc blocks reference description content defined in a separate .md file. This is the most powerful option and the most effort to set up:

columns:
  - name: customer__id
    description: "{{ doc('customer__id') }}"

The doc block lives in a .md file within your resource paths:

{% docs customer__id %}
Unique customer identifier from the Shopify source system. Primary key in
mrt__core__customers, foreign key in order and transaction models.
{% enddocs %}

Doc blocks are the right choice when:

• The same column appears in multiple models — define the description once, reference it everywhere, change it in one place
• A model-level description is long enough that having it in YAML clutters the schema file
• You want to use full Markdown capabilities (the doc block can contain tables, headers, and formatting that would be awkward inside a YAML scalar)

The full capabilities, naming conventions, file organization patterns, and limitations of doc blocks are covered in dbt Doc Block Syntax and Reuse Patterns and dbt Doc Block File Organization.

Choosing the Right Option

The rule of thumb: inline strings for simple columns, folded scalars for most model descriptions, literal scalars when structure matters, doc blocks when reuse or length demands it. Many teams end up with a mix — inline for columns at the staging layer, folded scalars for mart model descriptions, doc blocks for shared column definitions like IDs and timestamps.

The formatting choice doesn’t affect what gets rendered in the dbt docs site — any of these can produce good documentation. What it affects is how easy it is to read and maintain the YAML files themselves, which is where your team will spend most of their time with descriptions.