nuMetrix
DSL Naming
Conventions
How we name YAML definitions, compiled SQL models, contracts,
and everything in between
March 2026
Motivation
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.
nuMetrix
Act I
The Three Artefact Families
Signals, theses, verdicts — and how each one is named.
Prefixes
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
Perspectives Are a Subtype of Signal
- Perspectives use
signal_idas their identifier field — notperspective_id - Compiled output follows the
signal_findings__pattern, just like regular signals - The
perspective_prefix on thesignal_idvalue 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_*.
nuMetrix
Act II
The Double-Underscore Convention
How compiled SQL model names are built from YAML identifiers.
Pattern
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']}"insignalcompile.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
Signals: One File Per Artefact
signal_*.yaml
18 files
18 files
→
signalcompile.py
→
signal_findings__*.sql
18 files (1:1)
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.
Verdicts
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)
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)
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.
Design
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.
nuMetrix
Act III
Layer Prefixes & Contracts
Medallion layer naming and the contract versioning scheme.
Layers
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.
Contracts
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.
Entities
Entity Names in Contracts
Contract Entity (PascalCase)
BillingEvent
CaseMaterialUsage
Case
Material
Procedure
CaseMaterialUsage
Case
Material
Procedure
dbt Model (snake_case)
gold_billing_events
gold_case_material_usage
gold_cases
gold_materials
gold_procedures
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.
nuMetrix
Act IV
The Full Naming Pipeline
From YAML file to platform union view — following one name through the system.
Signal
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
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
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.
nuMetrix
Act V
Design Decisions
The trade-offs we considered and why we chose this way.
Trade-off
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.
Registries
Registry Naming
Per-Tenant (in models/signals/)
signal_registry.sql
thesis_registry.sql
verdict_registry.sql
thesis_registry.sql
verdict_registry.sql
Platform (in models/platform/)
platform_signal_registry.sql
platform_thesis_registry.sql
platform_verdict_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.
Summary
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
nuMetrix