Creating a dbt Glossary with Term blocks

[jenna-jordan]

I'd like to propose a new concept for dbt core, which will require the creation of a new jinja macro and accompanying functionality. If this is better suited as an issue, I can submit an issue instead!

The simple idea: term blocks. The big idea: a dbt-style glossary that turns into a concept map (and even a taxonomy), relating the physical dbt models to the overall conceptual model.

I first proposed this idea in this LinkedIn post, and I also brought it up during the dbt Catalog product roundtable at Coalesce 2025, where it seemed other participants agreed with the idea being useful.

While dbt doc blocks are used primarily as a convenience for long, formatted, and/or DRY descriptions, they have the potential to be more. I am proposing "term" blocks so as to not interfere with existing doc block functionality, but it may be preferable to instead re-think doc blocks and expand their functionality - I leave this up for debate.

Doc blocks are primarily used to document column descriptions, but can also be used to document model descriptions, exposure descriptions, etc. Regardless, the idea is that doc blocks are for documenting existing dbt artifacts.

Term blocks would work differently - they would exist independent of dbt artifacts, but could be called (ref'd) in those descriptions/doc blocks. A term block should be able to ref other term blocks, as well. The primary purpose of a term block is to document a concept, or term, such as "customer". While there may be, for example, documented models for dim_customer or documented column descriptions for customer_id, there is currently no way to communicate that these are about the underlying concept "customer" beyond naming conventions. Defining this concept, then ref'ing this concept in the model and column descriptions, provides a way to link the physical table/attribute back to the conceptual model.

Put together, these term blocks would turn into a business glossary. The business glossary is a vital component of enterprise-level data catalogs and data governance functions. By adding these terms to dbt models/columns/exposures, you can produce a map of how these concepts are represented in the data, which could then be visualized in a graph, similar to the lineage DAG.

I see two possible ways for these terms to be represented in a dbt project: (a) one following the doc block pattern, and (b) one following the semantic model pattern.

option A:

# glossary.md
{% term customer %}

An individual or organization who has placed at least one {{ term('order') }}.
 
{% endterm %}

option B:

# glossary.yml
terms:
  - name: customer
    description: An individual or organization who has placed at least one order
    type: concept
    related_terms:
      - name: order
         relationship_type: related
         relationship_description: creates
      - name: person
         relationship_type: narrower
         relationship_description: may be a

Option A should be familiar and relatively simply to implement, but is limited in future potential. Option B is more complex and less familiar (especially for those who do not use the semantic layer), but offers a lot more potential for expanding terms into a full taxonomy. In option A, you can assume some kind of relationship between terms customer and order, while in option B you can fully articulate what that relationship is. Perhaps even both option A and B can be supported, depending on which syntax and set of capabilities the project needs.

I'd recommend looking at SKOS (Simple Knowledge Organization System) as the foundation for implementing option B, and will also point to Jessica Talisman's guide on taxonomies.

I think that supporting this type of feature will be very important to dbt projects in the future, especially given the importance of ontologies/taxonomies to improving the results of LLMs querying data. I'll refer to Juan Sequeda's body of work here, which has inspired dbt Labs in the past. Furthermore, I think that dbt projects are uniquely suited to introducing data teams to this type of knowledge engineering work, and supporting terms in dbt Core and dbt Catalog can go a long way toward making dbt Catalog a fully capable data catalog solution.

[jenna-jordan]

On further thought, I think we can get the best of both worlds from options A and B, by keeping the doc blocks form factor but getting relationship types using args for the jinja function, like so:

# glossary.md
{% term customer %}

An individual {{ term('person', rel_type='narrower') }} or {{ term('organization', rel_type='narrower') }} who has placed at least one {{ term('order', rel_type='related') }}.

{% endterm %}

Where the triple is formed by:

• Subject: the doc block term (customer)
• Relationship: the rel_type argument (narrower)
• Object: the referenced term (person)

[b-per]

Thanks @jenna-jordan !

Is your idea for the glossary to be tightly coupled to models themselves or not?
For example, with customer, how would we tie it to models/tables? By column name matching the term or by adding in in the description section?

I also wonder if the glossary would be the place to add synonyms and whether we should have a first class construct for those.

[jenna-jordan]

The glossary should not be tightly coupled to the models, acting similarly to the doc blocks - you can add doc blocks that are never referenced and that does not cause an error (though I cannot speak for v1.11), you can choose not to use doc blocks, and an error is only triggered when you try to ref a doc block that does not exist.

Likewise, term blocks should be able to be developed independently, with an error only happening when a term block is referenced but does not exist. Term blocks should be able to be referenced inside of other term blocks, inside doc blocks, and inside any description field.

For example, a model referencing a term block would look like:

# dim_customer.yml

models:
  - name: dim_customers
    description: "This mart contains 1 record for each {{ term('customer') }}."
    columns:
      - name: customer_id
        description: "Unique identifier for a {{ term('customer') }}"

When rendered in dbt docs or dbt Catalog, those term blocks should resolve to just "customer", with a hyperlink. Ideally the description of customer from the term block should display on hover, while a click would bring the user through to the term "customer" inside the glossary. An entirely new space would be needed for the Glossary inside dbt docs/ dbt Catalog.

[jenna-jordan]

and yes, the glossary would definitely be a great place to include synonyms! I think a taxonomy logic would include the synonym relationship, and I'll point everyone over to read Jessica Talisman's work in this area (see: the Ontology Pipeline, alt link)

[jenna-jordan]

Suggested Reading:

• Knowledge Graph Lite, Part I
• Knowledge Graph Lite, Part II
• Knowledge Graph Lite, Part III

Note: some of these may be behind a paywall. If you are unable to access and interested in reading, please contact either myself or Jessica Talisman.

Lightweight ontologies are agile: they can be quickly prototyped, tested, and adapted as understanding evolves. This scaffolding approach helps teams learn together, gradually maturing their knowledge model before locking in heavy constraints that accompany lower, more complex ontologies. SKOS is a fabulous ontology model for getting the ontology feet wet, a welcome primer for ontology modeling. With all of the head scratching around how to build ontologies and even, what is an ontology, SKOS helps to teach ontology logic through the ontological structuring taxonomies and thesauri.
Just as machines appreciate the logical discipline introduced by relationship constraints and definitions, human modelers benefit from the limitations presented by SKOS’s inability to model more complex relationship types. This is the very essence of ontology modeling, as building ontologies requires focus and discipline. SKOS exists as ontology training wheels, a way to model a shared understanding by way of a simplified domain model.
A glossary, data catalog, taxonomy and thesaurus are all excellent candidates for SKOS modeling. Constrain the use cases, start with what exists within any given system, model with SKOS and iterate, until your data asset can stand on its own as a rich, disambiguated SKOS ontology model.
Experiment with your SKOS model, use it for Retrieval Augmented Generation (RAG), train your AI model on SKOS and measure to see how AI output improves. Operationalize SKOS early and often, to provide a feedback loop for iterative modeling, until the shared vocabulary model provides enough context, enough meaning, to deliver meaningful results.

• Knowledge Graph Lite, Part II - Support Iterative Development

[jenna-jordan]

Some existing resources on representing SKOS in YAML:

Research paper: Streamlining Vocabulary Conversion to SKOS: A YAML-based Approach to Facilitate Participation in the Semantic Web

• accompanying repo: https://gitlab.hrz.tu-chemnitz.de/vsr/yaml2skos-conversion
• supplementary data: https://zenodo.org/records/10652216

skout: A YAML-based tree-format for SKOS concept schemes