Standardize Naming Conventions

Standardize Naming Conventions

Interactive workflow for auditing and standardizing naming conventions in Power BI semantic models stored as TMDL files. Ensures tables, columns, measures, and display folders follow human-readable, consistent, business-aligned naming standards.

Primary Workflow

Phase 1: Discover the Model

Locate the TMDL files. Ask the user for the path to the .SemanticModel/definition/ directory if not obvious from context. Then scan the model structure:

# Count tables and get an overview
ls <path>/tables/*.tmdl

Read all table TMDL files to build a complete picture of current naming patterns. Focus on:

• Table names (check for DIM_, FACT_, or other technical prefixes)
• Measure names (check for abbreviations, programming conventions, inconsistent syntax)
• Column names (check for CamelCase, snake_case, abbreviations)
• Display folder structure (check for organization and consistency)
• Presence of descriptions (/// comments)

Phase 2: Understand Business Context

CRITICAL: Do not rename anything without understanding the business terminology.

Use AskUserQuestion to gather context:

1. Business terminology: "What terminology does your organization use for key metrics? For example, do you call it Revenue, Turnover, Sales, or Gross Sales?" 2. Existing conventions: "Do you have any documented naming conventions or standards already?" 3. Period conventions: "How do you typically refer to prior periods? (e.g., 1YP, PY, Prior Year, Last Year)" 4. Unit conventions: "How do you typically express units in measure names? (e.g., parentheses like (%), (Value), (Quantity))" 5. Downstream impact: "Are there downstream reports connected to this model that would need visual rebinding after renaming?"

Adapt the naming rules to the user's business context. The rules in references/naming-rules.md are defaults -- override them when the user's organization has established conventions.

Phase 3: Audit and Report

Before making changes, produce an audit report. Present a markdown table showing each proposed rename:

| Object Type | Current Name | Proposed Name | Issues Found |
|-------------|-------------|---------------|-------------|
| Table | FACT_Invoices | Invoices | Technical prefix |
| Measure | NetSls | Net Sales | CamelCase, abbreviation |
| Column | shp_dt | Ship Date | snake_case, abbreviation |

Group findings by issue type:

• Programming conventions: CamelCase, snake_case, UPPER_CASE
• Abbreviations/acronyms: Shortened or opaque names
• Inconsistent syntax: Mixed period, unit, or aggregation patterns
• Technical prefixes: DIM_, FACT_, STG_ on tables
• Missing descriptions: Objects without /// docstrings
• Disorganized folders: Missing or flat display folder hierarchy

Ask the user to confirm or adjust the proposed renames before proceeding.

Phase 4: Apply Changes

After user approval, edit the TMDL files. For each table file:

1. Rename the table (if needed): Change the table declaration 2. Rename measures: Change measure names in their declarations. IMPORTANT: Also update all internal DAX references to renamed measures using [Old Name] -> [New Name] patterns across ALL table files in the model 3. Rename columns: Change column names in their declarations. IMPORTANT: Also update DAX references using 'Table'[Old Column] -> 'Table'[New Column] across ALL table files 4. Reorganize display folders: Add or restructure displayFolder: properties 5. Add descriptions: Add /// comments for measures and columns that lack them 6. Update relationship references: Check relationships.tmdl for renamed tables/columns

Cross-file reference updates are critical. When renaming a measure or column, search the entire definition/ directory for all references:

# Find all references to a renamed measure
rg "OldMeasureName" <path>/definition/tables/
rg "OldMeasureName" <path>/definition/relationships.tmdl

Phase 5: Validate

After applying changes, verify: 1. All TMDL files still parse correctly (no syntax errors) 2. No orphaned references to old names remain in any file 3. Display folders are consistent across tables 4. Descriptions are present on all visible measures and columns

Run a final search to check for any missed references:

# Check for any remaining old names
rg -n "old_name_pattern" <path>/definition/

Naming Convention Rules

Consult references/naming-rules.md for the complete rule set including:

• Human-readable name requirements
• Abbreviation and acronym rules
• Technical prefix rules
• Aggregation, unit, and period syntax standards
• Display folder organization patterns
• Measure name construction order: [Aggregation] [Base Name] [Period] ([Unit])
• Column naming patterns

Key Anti-Patterns to Detect

Quick-reference checklist for the most common issues:

Downstream Report Impact

WARNING: Renaming model objects breaks downstream report visuals that reference those fields. After renaming:

1. Identify all connected reports (.pbir files or Power BI Service reports) 2. Rebind visuals to use the new field names 3. This can be done manually in Power BI Desktop, or programmatically by editing the visual.json files in PBIR format

Always warn the user about this before applying renames. If downstream reports exist, consider:

• Making a backup of the model before changes
• Planning a rebinding session after the rename
• Using a C# script in Tabular Editor to batch-rename with rebinding

Additional Resources

Reference Files

• `references/naming-rules.md` -- Complete naming convention rules with detection patterns, anti-pattern tables, and the measure name construction order

Fetching Docs

To retrieve current semantic model and TMDL reference docs, use microsoft_docs_search + microsoft_docs_fetch (MCP) if available, otherwise mslearn search + mslearn fetch (CLI). Search based on the user's request and run multiple searches as needed to ensure sufficient context before proceeding.

Naming Convention Rules Reference

Rules for standardizing naming conventions in Power BI semantic models (TMDL format). These rules are derived from common best practices and should be adapted to each organization's business terminology.

Core Principle

Names must align with the business terminology used by people in the organization. Never assume terminology -- always confirm with the user or infer from existing patterns in the model. The model should be an authoritative source of truth for terminology.

Rule Categories

1. Human-Readable Names (No Programming Conventions)

Rule: All table, column, and measure names must use standard casing with spaces. No CamelCase, snake_case, UPPER_CASE, or other programming conventions.

Detection patterns in TMDL:

• measure [a-z]+_[a-z]+ -- snake_case measures
• measure [A-Z][a-z]+[A-Z] -- CamelCase measures
• measure [A-Z_]{4,} -- UPPER_CASE measures
• Same patterns for column declarations

2. No Abbreviations or Acronyms

Rule: Spell out full words. Exceptions only for universally understood abbreviations (MTD, YTD, QTD) or standard business acronyms that are defined in descriptions.

Detection patterns:

• Names shorter than 5 characters that aren't common words
• Names containing periods followed by spaces (abbreviation dots): \w+\.\s
• Names with vowels removed: consecutive consonants of 3+ characters
• Single-letter or two-letter words that aren't prepositions/articles

3. No Technical Prefixes

Rule: Do not use DIM_, FACT_, or similar technical prefixes on table names. Use Tabular Editor's Table Groups annotation to organize tables into Dimension/Fact categories instead.

Exception: Field parameters can use FP_ prefix and calculation groups can use CG_ prefix when not exposed to end users or the AI schema. Technical tables like __Measures or __Formatting can use underscore prefixes.

Detection patterns:

• table (DIM|FACT|dim|fact|STG|stg|RAW|raw)_ -- technical prefixes

4. No Excessive Symbols or Special Characters

Rule: Avoid emojis, excessive dollar signs, Unicode decorations, or other non-standard characters in names.

Detection patterns:

• Names containing $, # (except # in count measures like # Customers)
• Names containing emoji Unicode ranges
• Names with repeated special characters

5. Consistent Aggregation Syntax

Rule: Choose one convention for time aggregations and apply it uniformly throughout the model.

Recommended convention: Use standard abbreviations as suffixes, wrapped in nothing or minimal syntax:

• MTD (Month to Date)
• QTD (Quarter to Date)
• YTD (Year to Date)
• Weekly Average, Daily Average (for rolling)

Placement: Aggregation follows the base measure name:

• Turnover MTD
• Budget QTD
• Net Sales YTD

6. Consistent Unit Syntax

Rule: Choose one convention for units and apply it uniformly. Use parentheses for units.

Recommended convention: Measure Name (Unit) where unit is one of:

• Currency symbol or code in parentheses when needed: (EUR), (USD)
• (%) for percentages
• (Quantity) for quantity measures
• (Value) for monetary value (default, sometimes omitted)
• (Units) or (pcs) for piece counts

7. Consistent Period Syntax

Rule: Choose one convention for time period comparisons and apply it uniformly.

Recommended convention: Use nYP (n-Year Prior) format:

• 1YP = 1 Year Prior (previous year)
• 2YP = 2 Years Prior
• 1MP = 1 Month Prior (if needed)

Placement: Period follows the base measure name but precedes unit:

• Turnover 1YP
• Net Sales 2YP
• Selling Margin 1YP (%)

8. Consistent Comparison Syntax

Rule: For measures that compare actuals to targets or prior periods, use vs. syntax with the target/period and unit.

Recommended convention: Base Measure vs. Target (Unit)

• Turnover vs 1YP (%) -- percentage variance to prior year
• Budget MTD vs. Turnover (delta) -- absolute variance using delta symbol or word
• Forecast vs. Turnover (%) -- percentage variance to forecast

Use the delta symbol or abbreviation consistently:

• Either always (delta) or always the delta symbol
• Either always vs. (with period) or always vs (without)

9. Display Folder Organization

Rule: Use numbered prefixes for display folders to control sort order. Organize into a logical hierarchy.

Recommended structure for fact tables:

0. Measures\
    1. Value\
        i. Total
        ii. 1YP
        iii. 2YP
    2. Quantity
    3. Lines
1. Facts
2. Degenerate Dimensions
3. Keys\
    Dates

Recommended structure for dimension tables:

1. [Primary Hierarchy Name]
2. [Attributes]
3. Managers
4. Keys

10. Descriptions

Rule: All visible measures and columns should have descriptions (TMDL /// comments). Descriptions should explain:

• What the measure calculates
• Any business context needed to interpret it
• How to use it (for measures that require filter context, like field parameters)
• Definition of acronyms used in the name

Example:

/// Net orders exclude cancellation document types
measure 'Net Orders' =

11. Synonyms (Prep for AI)

When using "Prep your data for AI" or setting synonyms:

• Only list real synonyms that people in the organization use
• Consider multilingual synonyms for international organizations
• Synonyms primarily benefit AI/agent queries

Measure Name Construction Order

The full name of a measure should follow this consistent construction:

[Aggregation] [Base Name] [Period] ([Unit])

Examples:

• Turnover (base only)
• Turnover (Quantity) (base + unit)
• Turnover 1YP (base + period)
• Turnover 1YP (Quantity) (base + period + unit)
• MTD Turnover 1YP (aggregation + base + period)
• Turnover vs 1YP (%) (base + comparison + unit)
• MTD Turnover vs 1YP (%) (aggregation + base + comparison + unit)

Column Name Rules

Columns generally follow simpler rules: 1. Use full, human-readable names with spaces 2. Use standard casing (not snake_case or CamelCase) 3. Avoid abbreviations 4. Hidden key columns can use [Table Name] Key pattern 5. Group into display folders by purpose (Hierarchy, Attributes, Keys, Facts)