Using TMDL to Drive Power BI Report Design

February 1, 2026

TL;DR: TMDL is the text-based definition of your Power BI semantic model — tables, columns, measures, and relationships expressed as readable markup. When you give an AI model access to your TMDL, it can reason about your data structure and suggest which visuals make sense, what dimensions to filter by, and how to arrange the layout. This article explains what TMDL is, where it comes from, and how to use it as input for layout design.

What TMDL Is

TMDL stands for Tabular Model Definition Language. It's a structured text format that describes everything in a Power BI semantic model: tables, columns, measures, hierarchies, relationships, calculation groups, and perspectives. The TMDL overview on Microsoft Learn is the authoritative reference for the format specification.

A TMDL excerpt looks like this:

table Sales
  partition Sales = m
    mode: import
    source =
      let
        Source = ...
      in Source

  measure 'Total Revenue' = SUMX(Sales, Sales[Quantity] * Sales[Price])
    formatString: $#,##0.00

  column Date
    dataType: dateTime
    formatString: Short Date

  column ProductKey
    dataType: int64
    isHidden: true

That's a fraction of what a real TMDL file contains. A production semantic model might have 15-20 tables, hundreds of columns, and 50+ measures. All of it is described in human-readable (and machine-readable) TMDL markup.

Where TMDL Comes From

TMDL files are generated by the Power BI tooling, not written by hand (though you can edit them by hand in advanced scenarios):

Fabric workspace with Git integration: When you connect a Fabric workspace to a Git repository, semantic model changes are serialized as TMDL and committed alongside your PBIR report files. The .SemanticModel folder in the repo root contains the full TMDL definition. Microsoft's PBIR semantic model reference explains the folder structure in detail.

Power BI Desktop with PBIR format: If you're using the PBIR format in Desktop (which became default in March 2026), you can access the TMDL files in the adjacent .SemanticModel directory when working with a locally-synced Fabric item.

Tabular Editor: Tabular Editor 3 (commercial) and Tabular Editor 2 (open-source) both provide a "Save as TMDL" export. Connect Tabular Editor to your Power BI Desktop model and export the full TMDL in seconds. This works even if you're not using Git integration.

Power BI CLI (pbi-tools): The community-maintained pbi-tools utility can extract TMDL from a PBIX file. Useful for teams working with older PBIX-format reports that haven't migrated to PBIR yet.

Why TMDL Matters for Report Design

Here's the problem that TMDL solves for report design: the people who design Power BI reports often don't know the semantic model well. The people who build the semantic model often don't design the report visuals.

This gap creates predictable problems:

A designer mocks up a report using "Sales by Category" as a bar chart, but the actual table is named FactSales and there's no Category column — it's ProductSubcategoryName in a related DimProduct table.
A matrix is designed to show "Regional performance by quarter," but the relationships in the model require a specific filter context setup that changes how the measure behaves.
A KPI card is designed to show "YoY Growth %" but no such measure exists in the model. The developer has to build it, which takes time that wasn't budgeted.

When the designer has access to the TMDL, they can see exactly what tables exist, what measures are already built, what columns are available for dimensions, and what the relationships are. Layout decisions become grounded in the actual data structure rather than an assumed one.

The AI Bridge

TMDL is too dense for most humans to read in full and reason about quickly. A 200-table semantic model's TMDL might be thousands of lines. But AI models are good at exactly this: reading structured text, extracting relevant information, and applying domain knowledge to generate suggestions.

When you upload TMDL to an AI model with the right context, it can:

Identify the key fact tables — which tables contain transactional data vs. dimension tables
Infer the most important measures — measures with names like "Revenue," "Margin %," or "Customer Count" are likely candidates for prominent placement
Suggest appropriate visual types — a date dimension + a numeric measure → time series chart; a category dimension + a numeric measure → bar or column chart
Propose a spatial hierarchy — summary KPIs at the top, trend charts in the middle, detail table at the bottom
Identify natural filter dimensions — date columns, category hierarchies, and geographic dimensions are natural slicer candidates

The AI output is a canvas layout suggestion: which visual goes where, with what dimensions and measures, in what rough proportions.

The Traditional Gap vs. the Draft BI Approach

Without tooling support, using TMDL for layout design requires:

Exporting TMDL from Tabular Editor or Git
Pasting it into a general-purpose AI chat interface
Writing a detailed prompt explaining what you want
Interpreting the AI's text description of a layout
Manually recreating that layout in a wireframing tool or directly in Desktop

Each step is manual. The output is text, not a functional layout.

Draft BI integrates this pipeline. You paste or upload your TMDL directly into the AI Wireframe tool, write a brief description of what the report needs to show, and get a canvas layout rendered in the editor. The layout uses real Power BI visual types positioned on the correct 1280x720 canvas.

From there, you can adjust the layout, add or remove visuals, and export as a PBIR file that opens directly in Power BI Desktop. The semantic model connection is separate — you connect it in Desktop — but the layout and visual types are pre-built based on what was in your TMDL.

What the TMDL Upload Workflow Looks Like

In practice, using TMDL with Draft BI takes about 10 minutes:

Export your TMDL. From Tabular Editor: File > Save Model As > TMDL Folder, then copy the contents of the main .tmd file. Or from Git: navigate to the .SemanticModel folder and open the table definition files.
Open Draft BI and start an AI Wireframe. The AI Wireframe panel is available from the canvas toolbar.
Paste your TMDL. The input accepts any TMDL content — you don't need the full model definition. Pasting the fact table definitions and measure list is usually sufficient.
Write a brief prompt. Something like: "Executive summary dashboard showing revenue, margin, and customer acquisition trends with geographic breakdown." The more specific you are about the audience and story, the better the layout suggestion.
Review the generated layout. Draft BI renders the AI's suggestion as a live canvas you can immediately edit. Visuals are positioned, sized, and labeled based on the measure and column names in your TMDL.
Iterate and export. Adjust the layout to match your preferences, then export as PBIR.

Why This Approach Works Better Than Generic AI Layout Tools

General-purpose AI tools don't know what a Power BI visual type is. They don't know that pivotTable is the identifier for a matrix visual, or that the canvas is 1280x720, or that visuals snap to 20px increments. The gap between an AI's text description of a layout and a valid Power BI report structure is significant.

Draft BI's AI integration uses structured outputs — the AI is given a schema that maps directly to valid PBIR visual structures. The output is a JSON object with valid visual type identifiers, valid canvas coordinates, and valid dimensions. There's no interpretation step between AI suggestion and functional layout.

This is the same reason wireframing without Power BI-native tools falls short — the translation step between the design artifact and the actual report is where precision is lost.