Data & Analytics
A successful dbt parse can still lose documentation lineage
Audit manifest doc block references before switching a documentation pipeline to the dbt v2 parser.
November 10, 2026
A parser migration can pass and still degrade the metadata contract. In dbt issue 17025, --use-v2-parser leaves doc_blocks empty on nodes and columns in manifest.json. The rendered descriptions and top-level docs entries still appear, so a basic documentation page check does not expose the missing relationship.
Compare artifacts, not screenshots
Run the same project through both parsers with partial parsing disabled and separate target paths. Inspect a model and column whose description uses doc(), plus one plain-text description. Compare their doc_blocks arrays and rendered text. The issue gives a minimal reproduction with exactly that control case.
dbt's manifest reference explains that the artifact is used by documentation and state consumers, and includes a top-level docs dictionary. A downstream governance tool may need the source-block link even when a human can read the resolved description.
Gate the parser rollout
List consumers that read doc_blocks: lineage, documentation quality checks, ownership reports or internal catalog enrichment. Compare expected references for a representative set before and after the flag. If only rendered descriptions are needed, the impact may be low; if source-block lineage is required, hold the rollout or implement a documented temporary extraction.
Record the parser version with each artifact. A valid JSON schema only proves the field exists, not that its values are complete.
Adovo’s view
Metadata is an interface between teams. A field that silently becomes empty can break trust without breaking a build. Treat artifact parity as a migration test, especially when the visible page still looks fine.
