Enforcing ISO-11179 Healthcare Naming Standards in dbt Projects

Why Naming Standards Break Down in dbt Projects

dbt solves a lot of problems in healthcare data pipelines — lineage, testing, documentation, modular SQL. But it does not solve the one problem that quietly corrupts every warehouse over time: inconsistent column naming.

✅

Free Tool

Check these column names against healthcare naming standards →

The pattern is always the same. The first staging models are built carefully — claim_id, member_id, admit_dt. Then a new engineer joins and builds a pharmacy model using prescription_id, fill_date, and member_key. Six months later, a third team builds clinical models with patientId, encounterDate, and memberIdentifier. Each set of names is internally consistent. None of them are consistent with each other.

By the time the data warehouse is two years old, dbt docs generate produces a catalog where the same concept — a member's date of birth — exists as dob, birth_date, mbr_birth_dt, member_dob, and patient_date_of_birth in different models. Downstream BI tools break when models are joined. HIPAA audits become expensive because PHI column identification requires manual review.

The fix is not documentation. It is a standard enforced at build time.

ISO-11179 defines exactly how to name a data element so the name itself communicates the entity, the property, and the data type — without opening a data dictionary. The dbt-healthcare-standards package brings that standard into your dbt project as macros and schema tests.

---

What ISO-11179 Means for Healthcare Column Names

ISO/IEC 11179 Part 5 defines a three-part structure for every data element name:

object_class + property + representation_class ───────────────────────────────────────────────── patient birth dt → patient_birth_dt claim allowed_charge amt → claim_allowed_charge_amt provider npi id → provider_npi_id member medicare ind → member_medicare_ind

The object class is the entity the column belongs to: patient, claim, member, provider, encounter, pharmacy. The property is what is being measured or described: birth, paid, admit, discharge, npi. The representation class is a mandatory suffix that signals the data type: _dt for a date, _amt for a monetary amount, _cd for a code, _id for an identifier, _ind for a boolean indicator.

When every engineer follows this structure, you can read a SELECT list and immediately know what each column is, what type it holds, and which entity it belongs to — without hover-tooltips, without dbt docs, without asking the original author.

Healthcare adopted ISO-11179 because it was already implicit in how EDI transactions (X12 837 loop segments), FHIR resources, and CMS reporting specifications are organized. Formalizing it in your dbt project makes that implicit standard explicit and machine-enforceable.

The complete reference dictionary of 100,000+ healthcare terms and their standard abbreviations is available free at mdatool.com/glossary.

---

Installing dbt-healthcare-standards

Add the package to your packages.yml:

packages:
  - git: "https://github.com/smudvar/dbt-healthcare-standards"
    revision: v0.1.0

Then install it:

dbt deps

Requires dbt >= 1.3.0. Works with Snowflake, Databricks, BigQuery, Redshift, and DuckDB adapters.

---

Macro 1: validate_healthcare_naming

validate_healthcare_naming(column_name) accepts a column name and returns a list of violation strings. An empty list means the name is compliant.

-- In a macro, operation, or dbt test:
{% set issues = validate_healthcare_naming("patientDOB") %}
-- → ["Must be snake_case...", "Missing ISO-11179 representation-class suffix..."]

{% set issues = validate_healthcare_naming("patient_birth_dt") %}
-- → []  ✓ valid

{% set issues = validate_healthcare_naming("paid_amount") %}
-- → ["Missing ISO-11179 representation-class suffix. Approved suffixes: _id, _cd, _dt, ..."]

The validator checks five rules:

1. snake_case only — lowercase letters, digits, underscores; must start with a letter
2. No double underscores — claim__id is not valid
3. Minimum length of 4 characters
4. Must end with an approved representation suffix — _id, _cd, _dt, _ts, _nm, _amt, _qty, _cnt, _pct, _ind, _txt, _nbr, _yr, _mo, _addr, _url, _src, _key
5. No banned generic tokens — _value, _data, _info, _detail are rejected because they add no meaning

---

Macro 2: generate_healthcare_column_name

generate_healthcare_column_name(entity, property, representation) builds a compliant name from its three semantic parts and validates the representation class before returning.

{{ generate_healthcare_column_name("patient", "date of birth", "dt") }}
-- → patient_date_of_birth_dt

{{ generate_healthcare_column_name("claim", "total charge", "amt") }}
-- → claim_total_charge_amt

{{ generate_healthcare_column_name("provider", "npi", "id") }}
-- → provider_npi_id

{{ generate_healthcare_column_name("member", "medicare eligible", "ind") }}
-- → member_medicare_eligible_ind

{{ generate_healthcare_column_name("encounter", "admit", "dt") }}
-- → encounter_admit_dt

Pass an invalid representation class and the macro raises a compiler error listing every approved class — so the mistake surfaces at dbt compile time, not in production.

The healthcare_column_ref alias works identically and reads more naturally inside SELECT statements:

select
  {{ healthcare_column_ref("claim", "id", "id") }}           as claim_id,
  {{ healthcare_column_ref("claim", "admit", "dt") }}        as claim_admit_dt,
  {{ healthcare_column_ref("claim", "allowed", "amt") }}     as claim_allowed_amt,
  {{ healthcare_column_ref("member", "id", "id") }}          as member_id
from {{ source('raw', 'claims') }}

---

Macro 3: assert_healthcare_naming (Schema Test)

This is the most useful macro for enforcement. Add it as a model-level test in schema.yml and it will raise a compiler error listing every non-compliant column name when dbt test runs:

models:
  - name: stg_claims
    tests:
      - dbt_healthcare_standards.assert_healthcare_naming:
          exclude:
            - _fivetran_synced
            - _loaded_at
            - _dbt_source_relation

  - name: stg_members
    tests:
      - dbt_healthcare_standards.assert_healthcare_naming

  - name: stg_providers
    tests:
      - dbt_healthcare_standards.assert_healthcare_naming

When a column fails, the error output looks like this:

Healthcare naming violations found in stg_claims: • patientDOB: Must be snake_case (lowercase letters, digits, underscores only) • patientDOB: Missing ISO-11179 representation-class suffix... • paid_amount: Missing ISO-11179 representation-class suffix. Approved: _id, _cd, _dt, _amt ... • ClaimStatus: Must be snake_case... Full ISO-11179 reference: https://www.mdatool.com/glossary

The error links directly to the mdatool glossary, so the engineer fixing the violation can immediately look up the standard abbreviation.

---

A Real Staging Model

Here is a complete stg_claims.sql built with compliant names:

-- models/staging/stg_claims.sql
select
    -- identifiers
    claim_id,
    member_id,
    rendering_provider_npi_id,

    -- dates (always _dt, never "date" or "DATE")
    claim_service_from_dt,
    claim_service_to_dt,
    claim_admit_dt,
    claim_discharge_dt,

    -- diagnosis codes (_cd = code representation)
    primary_diagnosis_cd,
    admitting_diagnosis_cd,
    secondary_diagnosis_cd_1,
    secondary_diagnosis_cd_2,

    -- financials (_amt = monetary amount in USD)
    claim_total_charge_amt,
    claim_allowed_amt,
    claim_paid_amt,
    member_copay_amt,
    member_coinsurance_pct,  -- _pct = percentage

    -- boolean indicators (_ind = true/false, not "flag" or "is_")
    inpatient_ind,
    emergency_ind,
    coordination_of_benefits_ind,

    -- reference codes and counts
    claim_status_cd,
    claim_type_cd,
    claim_line_cnt,          -- _cnt = integer count

    -- metadata
    data_src,                -- _src = source system
    created_ts,              -- _ts = timestamp with time
    updated_ts

from {{ source('raw', 'claims') }}

Every column tells you its entity, its property, and its data type — before you run a single query or open dbt docs.

---

Representation Class Reference

The full term list — including standard abbreviations for every entity prefix (claims, member, pharmacy, provider, clinical, quality) — is at mdatool.com/glossary.

---

Frequently Asked Questions

What is ISO-11179 naming convention?

ISO/IEC 11179 Part 5 is an international standard for naming data elements. It defines a three-part structure — object class + property + representation class — that makes column names self-documenting. In healthcare, this means claim_paid_amt is unambiguously a monetary paid amount on a claim, patient_birth_dt is a date-typed birth date for a patient entity, and provider_npi_id is the NPI identifier for a provider. No data dictionary required to decode the name. The complete reference for healthcare-specific terms and abbreviations is at mdatool.com/glossary.

How do I install dbt-healthcare-standards?

Add it to your packages.yml file:

packages:
  - git: "https://github.com/smudvar/dbt-healthcare-standards"
    revision: v0.1.0

Then run dbt deps. The package requires dbt >= 1.3.0 and works with any SQL adapter (Snowflake, BigQuery, Databricks, Redshift, DuckDB). Once installed, the macros validate_healthcare_naming, generate_healthcare_column_name, and assert_healthcare_naming are available in your project immediately.

What healthcare domains does it cover?

The package enforces naming standards across all major healthcare data domains: claims and adjudication, member enrollment and eligibility, provider credentialing and NPI data, pharmacy and NDC codes, clinical encounters and diagnosis coding, and quality measures including HCC and HEDIS. The representation class suffix list covers every data type that appears in healthcare pipelines — monetary amounts, dates, timestamps, codes, identifiers, indicators, counts, percentages, and free text. The full domain-specific term reference is at mdatool.com/glossary, which has 100,000+ standardized healthcare terms organized by domain.

📊

Free Tool

Calculate RAF scores with our free HCC Calculator →

How does it integrate with mdatool?

The assert_healthcare_naming macro references mdatool.com/glossary directly in its error messages — when a column fails validation, the engineer sees the violation and a link to the full reference. mdatool's Naming Auditor and Name Generator use the same ISO-11179 standard as this package, so terms generated by those tools will pass the dbt schema tests. The mdatool DDL Converter also outputs ISO-11179 compliant names when translating schemas between Snowflake, BigQuery, and Databricks.