DSL Naming
Conventions

How we name YAML definitions, compiled SQL models, contracts,
and everything in between

March 2026

Why Naming Matters

  • Predictability — Given a YAML filename, you can guess the compiled SQL model name without looking it up
  • Globbing — dbt build --select signal_findings__* does what you’d expect
  • DAG readability — In dbt’s DAG, you can see at a glance what layer and family a model belongs to
  • Union coherence — The union view’s name hints at what its children are called
  • Mechanical renaming — One convention means one search-and-replace when things change
The most important property of a naming convention is consistency. The second most important is that it fails loudly when violated.

The Three Artefact Families

Signals, theses, verdicts — and how each one is named.

Identity Prefixes

Family Prefix YAML Example ID Field
Signal signal_ signal_revenue_leakage.yaml signal_id: signal_revenue_leakage
Perspective perspective_ perspective_material_health.yaml signal_id: perspective_material_health
Thesis thesis_ thesis_revenue_leakage_unbilled.yaml thesis_id: thesis_revenue_leakage_unbilled
Verdict verdict_ verdict_billing_workflow_gap.yaml verdict_id: verdict_billing_workflow_gap
Rule: the ID field must match the filename (without .yaml). Enforced by thesischeck.py and verdictcheck.py at compile time. Signals follow the same convention by practice.

Perspectives Are a Subtype of Signal

  • Perspectives use signal_id as their identifier field — not perspective_id
  • Compiled output follows the signal_findings__ pattern, just like regular signals
  • The perspective_ prefix on the signal_id value is what distinguishes them
Compiled model names signal_findings__signal_revenue_leakage # regular probe signal_findings__signal_duplicate_billing # regular probe signal_findings__perspective_material_health # perspective signal_findings__perspective_billing_quality # perspective
From the dbt DAG’s perspective, perspectives are signals. The prefix is the only signal — and it’s enough for --select signal_findings__perspective_*.

The Double-Underscore Convention

How compiled SQL model names are built from YAML identifiers.

The __ Pattern

Anatomy of a compiled model name signal_findings__signal_revenue_leakage ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^ output type artefact identity (= signal_id from YAML)
  • Left of __ — what kind of table it is: signal_findings, conforming to the findings contract
  • Right of __ — the literal ID from the YAML definition, including its prefix
  • Formula — f"signal_findings__{probe['signal_id']}" in signalcompile.py
The double underscore is a namespace separator. Single underscores appear within names (revenue_leakage). Double underscores separate the output type from the instance identity. No ambiguity.

Signals: One File Per Artefact

signal_*.yaml
18 files
→
signalcompile.py
→
signal_findings__*.sql
18 files (1:1)
dbt/numetrix/models/probes/ signal_findings__signal_revenue_leakage.sql signal_findings__signal_duplicate_billing.sql signal_findings__signal_orphan_billing.sql signal_findings__signal_stale_article.sql signal_findings__perspective_material_health.sql signal_findings__perspective_billing_quality.sql ... (18 models total)
Each signal compiles to its own dbt model. The union view platform_signal_findings aggregates them via UNION ALL BY NAME. Naming invariant: the union view’s prefix matches its children.

Theses & Verdicts: Monolithic Files

Theses
thesis_revenue_leakage.yaml
thesis_stale_catalogue.yaml
thesis_duplicate_billing.yaml
↓ thesiscompile.py
thesis_verdicts.sql (one file)
thesis_registry.sql (one file)
Verdicts
verdict_billing_workflow_gap.yaml
verdict_catalogue_maintenance_lag.yaml
verdict_duplicate_interface_error.yaml
↓ verdictcompile.py
verdict_findings.sql (one file)
verdict_registry.sql (one file)
Unlike signals, theses and verdicts compile N YAML files into one monolithic SQL file. All thesis CTEs are UNION ALL’d inside a single thesis_verdicts.sql. No __ separator because there are no per-artefact files.

Why the Asymmetry?

Signals → One File Each
Signals are independent. Each queries Gold entities directly. No inter-signal dependencies (except perspectives). Adding a signal = adding a file. dbt build --select signal_findings__signal_X rebuilds just one.
Verdicts → Monolithic
Theses reference multiple signal findings tables. Verdicts reference thesis_verdicts + signal findings. A single model with all CTEs lets dbt resolve the full dependency graph in one pass.
The trade-off: monolithic files are harder to selectively rebuild, but they avoid a combinatorial explosion of dbt ref() cross-dependencies. The naming convention adapts to the compilation strategy, not the other way around.

Layer Prefixes & Contracts

Medallion layer naming and the contract versioning scheme.

Layer Prefixes

A material row flows through the pipeline bronze_materials → silver_materials → gold_materials → platform_gold_materials
Prefix Layer Materialization Example
bronze_ Bronze TABLE bronze_cases, bronze_billing_events
silver_ Silver TABLE silver_cases, silver_billing_events
gold_ Gold VIEW gold_cases, gold_taxonomy_closure
platform_gold_ Platform VIEW platform_gold_cases
platform_ Platform (DSL) VIEW platform_signal_findings, platform_thesis_verdicts
The entity name (cases, billing_events, materials) is invariant across all layers. Change the prefix, keep the noun.

Contract Naming

File Version Key YAML Reference Who Uses It
gold_contract.v1.json gold.v1 contract: "gold.v1" Most signals
silver_contract.v1.json silver.v1 contract: "silver.v1" Silver audit signals
signal_contract.v1.json signal.v1 contract: "signal.v1" Perspectives
verdict_contract.v1.json diagnosis.v1 contract: "diagnosis.v1" Verdict compiler
Pattern: {layer}_contract.v{N}.json. The version key inside the JSON uses the short form (gold.v1). YAML definitions reference this short key. Bumping to v2 = new file, old signals still compile against v1.

Entity Names in Contracts

Contract Entity (PascalCase)
BillingEvent
CaseMaterialUsage
Case
Material
Procedure
dbt Model (snake_case)
gold_billing_events
gold_case_material_usage
gold_cases
gold_materials
gold_procedures
Signals reference BillingEvent (PascalCase, domain language). The contract maps it to gold_billing_events (snake_case, dbt convention). resolve_ref() bridges the gap. If a dbt model renames, update one JSON field — all signals recompile correctly.

The Full Naming Pipeline

From YAML file to platform union view — following one name through the system.

Signal: End-to-End

Following a probe through the naming system 1. YAML definition probes/signal_revenue_leakage.yaml signal_id: signal_revenue_leakage # must match filename contract: "gold.v1" # references gold_contract.v1.json 2. Compiled dbt model models/probes/signal_findings__signal_revenue_leakage.sql # one file per probe 3. Per-tenant table (via generate_schema_name) hospital_alpha.signal_findings__signal_revenue_leakage 4. Platform union view platform.platform_signal_findings # UNION ALL BY NAME across tenants 5. Registry entry platform.platform_signal_registry # tri-lingual display text

Thesis: End-to-End

Following a hypothesis through the naming system 1. YAML definition hypotheses/thesis_revenue_leakage_unbilled.yaml thesis_id: thesis_revenue_leakage_unbilled # must match filename (enforced) 2. Compiled dbt model (monolithic — no __ separator) models/probes/thesis_verdicts.sql # all hypotheses in one file # Inside: CTEs named thesis_revenue_leakage_unbilled__evidence, # thesis_revenue_leakage_unbilled__scored, # thesis_revenue_leakage_unbilled__verdict 3. Per-tenant table hospital_alpha.thesis_verdicts # one row per hypothesis 4. Platform union view platform.platform_thesis_verdicts # UNION ALL across tenants

Verdict: End-to-End

Following a diagnosis through the naming system 1. YAML definition diagnoses/verdict_billing_workflow_gap.yaml verdict_id: verdict_billing_workflow_gap # must match filename (enforced) thesis_id: thesis_revenue_leakage_unbilled # must reference existing hypothesis 2. Compiled dbt model (monolithic — no __ separator) models/probes/verdict_findings.sql # all diagnoses in one file 3. Per-tenant table hospital_alpha.verdict_findings # rows only for confirmed hypotheses 4. Platform union view platform.platform_verdict_findings # UNION ALL across tenants
Note the cross-family reference: verdict_id: verdict_billing_workflow_gap points to thesis_id: thesis_revenue_leakage_unbilled. Prefixes (verdict_, thesis_) make the reference direction unambiguous.

Design Decisions

The trade-offs we considered and why we chose this way.

Why {family}__{instance}?

We considered three alternatives for verdict model names:

Option Example Trade-off
Main noun prefix verdict__thesis_X Both families share verdict__*. Union view name diverges from children.
Family prefix thesis_verdicts__thesis_X Consistent with signals. Union view matches children. Verbose but predictable.
Bare ID thesis_X Cleanest, but loses the “this is a verdict” signal in the DAG.
We chose family prefix because the union view’s name (thesis_verdicts) naturally matches its children (thesis_verdicts__thesis_*). --select thesis_verdicts__* does what you’d expect. Same pattern as signals.

Registry Naming

Per-Tenant (in models/signals/)
signal_registry.sql
thesis_registry.sql
verdict_registry.sql
Platform (in models/platform/)
platform_signal_registry.sql
platform_thesis_registry.sql
platform_verdict_registry.sql
Registries contain tri-lingual display text (DE/EN/FR). Content is tenant-independent — identical across all tenants. Platform views read from the first tenant only, unlike findings/verdicts which union across all.

The Complete Naming Map

Family YAML Dir Prefix Compiled SQL Strategy Platform View
Signal probes/ signal_ signal_findings__signal_* 1 file each platform_signal_findings
Perspective probes/ perspective_ signal_findings__perspective_* 1 file each (same union)
Thesis hypotheses/ thesis_ thesis_verdicts monolithic platform_thesis_verdicts
Verdict diagnoses/ verdict_ verdict_findings monolithic platform_verdict_findings
One convention, one search-and-replace. Given any YAML file, you can derive every downstream name mechanically. That’s the whole point.
nuMetrix