TmdlSAFE

Power BI AI skills and Power BI agents for Claude Code and GitHub Copilot: a plugin marketplace of Power BI skills, subagents, and hooks for semantic models, DAX, TMDL, reports, and AI dashboards. Includes Microsoft Fabric skills and Fabric agents. Weekly updates.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: tmdl
description: Direct TMDL file authoring and BIM-to-TMDL conversion for semantic models in PBIP projects. Automatically invoke when the user asks to "edit TMDL", "add a measure in TMDL", "TMDL syntax", "fix formatString", "fix summarizeBy", "TMDL indentation", "convert BIM to TMDL", "add a column description", "create a calculated column in TMDL", or mentions .tmdl file editing or BIM-to-TMDL migration.
---

# TMDL Authoring

Expert guidance for authoring and editing TMDL (Tabular Model Definition Language) files directly in PBIP projects.

> **This skill is a last resort.** Direct TMDL file editing lacks the validation, atomicity, and DAX query capabilities of the Tabular Editor CLI, Power BI MCP server, or the `connect-pbid` skill (TOM via PowerShell). Use those tools when available. TMDL editing is appropriate when:
>
> - Working with PBIP files in a Git repo without Power BI Desktop open
> - No Tabular Editor CLI or MCP server is installed
> - Making quick text-level fixes (descriptions, format strings, display folders) where a full tool chain is overkill
>
> Direct TMDL editing does not validate DAX syntax, check referential integrity, or verify that property values are valid. Errors will only surface when the model is next loaded in Power BI Desktop or deployed via XMLA. Use the **`pbip-validator`** agent to check TMDL files for syntax issues, indentation errors, and referential integrity before opening in PBI Desktop.

## When to Use This Skill

Activate only when the Tabular Editor CLI, Power BI MCP server, or `connect-pbid` skill are not available, and tasks involve:

- Editing `.tmdl` files directly (measures, columns, tables, relationships)
- Adding or modifying measure definitions in TMDL
- Adding descriptions to columns, measures, or tables
- Fixing `summarizeBy` or `formatString` values
- Understanding TMDL syntax rules (indentation, quoting, property ordering)
- Writing multi-line DAX in TMDL format
- Understanding the difference between `///` descriptions and `//` comments

## Critical

- **`///` (triple-slash) sets the `Description` property** on the object that immediately follows it. A `///` line must be immediately followed by a declaration (`measure`, `column`, `table`, etc.); never by a blank line or another `///`. Use `//` for regular comments.
- **Indentation is semantic.** TMDL uses whitespace indentation where depth equals nesting level ([TMDL spec — Indentation](https://learn.microsoft.com/en-us/analysis-services/tmdl/tmdl-overview#indentation)). PBIP files use a single tab per level because Power BI Desktop and the TOM `TmdlSerializer` default to `IndentationMode.Tabs`. Spaces are also valid (`IndentationMode.Spaces`, default 4 per level), but be consistent within a file; mixed or incorrect indentation will break the model. Properties of a table are indented one level; properties of a column (which belongs to a table) are indented two levels.
- **Name quoting rules:** Only quote names that contain spaces, special characters, or start with a digit. Simple names and underscore-prefixed names are unquoted. See the Name Quoting section for details.
- **M expressions and tables share a namespace.** A name declared by `expression <name>` in `expressions.tmdl` and a name declared by `table <name>` in `tables/*.tmdl` collide; Power BI Desktop fails the load with `'duplicate member <name>'`. Pick distinct names; the conventional fix is to suffix the M expression with ` Query` or ` Source` and have partitions reference it via `source = #"<Name> Query"`. `validate_pbip.py` enforces this as an ERROR.

## TMDL File Types

| File | Contents | Location |
|------|----------|----------|
| `model.tmdl` | Model configuration, `ref table` entries, query groups, annotations | `definition/` |
| `database.tmdl` | Compatibility level, model ID | `definition/` |
| `relationships.tmdl` | All relationships between tables | `definition/` |
| `expressions.tmdl` | Shared M expressions and parameters | `definition/` |
| `functions.tmdl` | DAX user-defined functions (reusable parameterized DAX) | `definition/` |
| `roles/<RoleName>.tmdl` | One file per security role (RLS filters, role members, OLS) | `definition/roles/` |
| `perspectives/<Name>.tmdl` | One file per perspective (object membership) | `definition/perspectives/` |
| `dataSources.tmdl` | Legacy data source definitions (if present) | `definition/` |
| `tables/<Name>.tmdl` | Table definition with columns, measures, hierarchies, partitions | `definition/tables/` |
| `cultures/<locale>.tmdl` | Linguistic metadata and translations | `definition/cultures/` |

## Object Nesting Rules

Objects must be nested inside their correct parent. The validator enforces these rules:

| Object | Allowed Parent(s) |
|--------|-------------------|
| `column`, `measure`, `hierarchy`, `partition`, `calculationGroup` | `table` |
| `level` | `hierarchy` |
| `calculationItem` | `calculationGroup` |
| `tablePermission` | `role` |
| `columnPermission` | `tablePermission` |
| `perspectiveTable` | `perspective` |
| `perspectiveColumn`, `perspectiveMeasure`, `perspectiveHierarchy` | `perspectiveTable` |
| `linguisticMetadata`, `translation` | `cultureInfo` |
| `dataAccessOptions` | `model` |
| `formatStringDefinition` | `measure`, `calculationItem` |
| `detailRowsDefinition` | `measure`, `table` |
| `alternateOf` | `column` |
| `member` | `role` |
| `annotation`, `extendedProperty` | any object (including `queryGroup`, `function`, `member`) |
| `ref` | `model`, `table` |

Root-level objects (indent 0 only): `model`, `database`, `table`, `relationship`, `role`, `cultureInfo`, `perspective`, `dataSource`, `expression`, `queryGroup`, `function`.

## Syntax Rules

### Indentation

TMDL uses **whitespace indentation** where depth equals nesting level. PBIP files use a single tab per level (the TOM `TmdlSerializer` default), so all examples below use tabs:

```tmdl
table Product                              // depth 0: top-level declaration
	lineageTag:

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.