Master Power BI TMDL — Edit Semantic Models Natively
Tabular Model Definition Language (TMDL) turns a Power BI semantic model into readable, version-controllable text — tables, measures, relationships, and partitions each as their own file. This tutorial covers TMDL view in Power BI Desktop and the new web editor, the full folder structure, Git and Azure DevOps integration, CI/CD pull-request workflows, and AI-assisted DAX authoring — verified against official Microsoft Learn documentation through June 2026.
TMDL (Tabular Model Definition Language) is a human-readable, YAML-like text format that describes an entire Power BI semantic model as code, replacing the single large JSON file used by the legacy TMSL format. TMDL splits the model into a folder structure — one file per table, measure, relationship, perspective, role, and culture — making it diff-friendly and mergeable in Git. TMDL view in Power BI Desktop became generally available in September 2025. TMDL View on the Web, announced at FabCon and SQLCon 2026, brings the same code-first editing experience to published semantic models directly in the browser — no PBIX download required. TMDL exposes properties not available in the standard UI, such as partition definitions and isAvailableInMdx.
What Is TMDL in Power BI?
Tabular Model Definition Language (TMDL) is a text-based representation of a Power BI semantic model. Instead of one opaque binary PBIX file or a single massive JSON document, TMDL expresses the entire model — tables, columns, measures, relationships, partitions, perspectives, roles, and cultures — as structured, human-readable text files organized into folders.
The practical effect is that a semantic model becomes something a developer can open in a code editor, search, diff line by line, and review in a pull request — the same way application source code is reviewed. TMDL originated from the Power BI community before Microsoft formally adopted it as the semantic model file format for Power BI Project (PBIP) files.
- TMDL view introduced in Power BI Desktop — January 2025, as a preview feature
- TMDL view general availability — September 2025
- TMDL View on the Web — announced at FabCon and SQLCon 2026, rolling out in the following weeks as a preview
TMDL view offers an alternative way to build and modify semantic models — using code instead of exclusively relying on the graphical Model view. It is not a replacement that forces every developer to abandon the UI; it is a parallel, code-first path that coexists with the standard graphical experience.
TMDL vs TMSL — Why the Format Change Matters
Before TMDL, semantic models in Power BI Project files were stored using TMSL (Tabular Model Scripting Language) — a single large JSON file representing the entire model, sometimes called model.bim. TMSL was designed for the Tabular Object Model API to consume programmatically, not for humans to read or for version control systems to diff meaningfully.
| Aspect | TMSL (Legacy) | TMDL (Current) |
|---|---|---|
| File structure | Single large JSON file (model.bim) | Folder with one file per table, perspective, role, culture |
| Human readability | Deeply nested, machine-oriented | YAML-like, designed to be read and edited directly |
| Git diffs | Whole-file changes — noisy, hard to review | Line-level diffs scoped to the specific object changed |
| Merge conflicts | Frequent — entire model is one mergeable unit | Rare — changes isolated to individual table/measure files |
| Editable in any text editor | Technically yes, practically no | Yes — designed for it |
| Used by PBIP format | Optional legacy option | Default for new Power BI Projects |
The merge conflict reduction is the underrated win here. With TMSL, two developers editing different measures in the same model would frequently produce a JSON merge conflict in the same file, forcing serialized development — one person waits while the other finishes and publishes. With TMDL, those same two developers are editing two different .tmdl files. Git resolves it automatically in the vast majority of cases. That single change is what makes concurrent semantic model development on a team actually practical.
TMDL Folder Structure — How a Model Becomes Files
When a Power BI Project is saved using the TMDL format, the semantic model folder replaces the single model.bim file with a structured directory. Understanding this layout is essential before working with TMDL in Git.
YourReport.SemanticModel/ ├── definition/ │ ├── database.tmdl │ ├── model.tmdl │ ├── relationships.tmdl │ ├── tables/ │ │ ├── Sales.tmdl │ │ ├── Customer.tmdl │ │ ├── Date.tmdl │ │ └── Product.tmdl │ ├── perspectives/ │ ├── roles/ │ └── cultures/ │ └── en-US.tmdl ├── .pbi/ │ └── editorSettings.json └── definition.pbism
Each table — including its columns, measures, and hierarchies — lives in its own .tmdl file under definition/tables/. Relationships are tracked centrally in relationships.tmdl. Roles and cultures (translations) each get their own file. This is the structure that makes a pull request reviewer’s job tractable: a change to one measure in the Sales table shows up as a small diff in Sales.tmdl — not as a thousand-line JSON delta across the entire model.
// Example: a measure as it appears inside Sales.tmdl
measure 'Total Revenue' = SUM(Sales[ExtendedAmount])
formatString: $#,0.00
displayFolder: Financial Measures
measure 'Revenue YTD' = ```
CALCULATE(
[Total Revenue],
DATESYTD('Date'[Date])
)
```
formatString: $#,0.00
displayFolder: Time IntelligenceUsing TMDL View in Power BI Desktop
TMDL view became generally available in Power BI Desktop in September 2025. It provides a modern code editor for scripting, modifying, and applying changes to semantic model objects, as an alternative to the graphical Model view.
Core Editor Capabilities
Editing Experience
- Search-and-replace across the model
- Keyboard shortcuts and multi-line edits
- Semantic syntax highlighting
- Full code editor — not a plain text box
Drag-and-Drop Scripting
- Drag any object from the Data pane into the TMDL editor
- Generates a createOrReplace TMDL script automatically
- Hold Ctrl to multi-select objects for bulk scripting
- Right-click → “Script TMDL to new tab” or “to clipboard”
Typical Workflow
- Drag an object into the editorDrag a table, measure, or column from the Data pane. Power BI scripts its full metadata as TMDL into the current tab, or opens a new tab.
- Edit the scriptModify properties directly in text — change a DAX expression, update a format string, add a description, or set a property unavailable in the UI.
- Apply the changeSelect Apply to execute the TMDL script against the semantic model. On success, the change reflects immediately in the model.
- Review errors if Apply failsIf the script fails, no changes are applied. Select “Show details” to expand the Output pane and see the specific error before retrying.
For organizations standardizing reusable objects — a calendar table, a set of time intelligence calculation groups — teams can script those objects to TMDL and share them through a centralized location such as SharePoint, letting any developer paste and apply the same proven definitions into a new model.
TMDL View on the Web — Edit Published Semantic Models in the Browser
TMDL View on the Web, announced at FabCon and SQLCon 2026, extends the same code-first modelling experience to semantic models already published in a Fabric or Power BI workspace — directly in the browser. No PBIX download. No switching to Power BI Desktop. The published model is scripted, modified, and applied to entirely within the web interface.
TMDL View on the Web is in preview, rolling out following the FabCon and SQLCon 2026 announcement. Feature availability, editor capabilities, and tenant settings are subject to change before general availability. Verify current rollout status in your tenant via Power BI service → workspace → semantic model settings.
Why the Web Editor Matters
Previously, modifying a published semantic model meant one of two paths: download the PBIX, open in Desktop, make the change, republish — or use an external tool such as Tabular Editor connected directly to the workspace. TMDL View on the Web collapses this into a single in-browser step, particularly valuable for quick fixes, governance reviews, and organizations where not every developer has Power BI Desktop installed locally.
Enabling the Web Editor
The published semantic model must allow editing in the service. In workspace settings, under Power BI → General → Data model settings, enable “Users can edit data models in the Power BI service.” This setting is also required for the workspace to export model metadata as serialized TMDL during Git integration — covered in Section 07.
For semantic models built on Direct Lake in a Fabric workspace, edits made through the web TMDL editor apply directly to the running model — no separate save-refresh-republish cycle. This significantly speeds up iterative development for Fabric-connected semantic models compared to the traditional Power BI Desktop publish flow.
Advanced Properties Only Accessible Through TMDL
One of the strongest arguments for learning TMDL is that it exposes the complete set of semantic model object properties — including several that are not surfaced anywhere in the standard Power BI Desktop user interface. Before TMDL, accessing these required an external tool such as Tabular Editor.
| Property / Capability | Available in Standard UI? | Available in TMDL? |
|---|---|---|
| Partition definitions | No | Yes |
| isAvailableInMdx | No | Yes |
| Calculation groups — advanced ordinal settings | Partial | Yes |
| Object-level annotations | No | Yes |
| Bulk property edits across many objects | No — one at a time | Yes — multi-select and script |
| Standard measures, columns, relationships | Yes | Yes |
This matters for BI architects managing enterprise-scale models where DirectQuery partitioning strategy, MDX client compatibility, or calculation group ordinals require precise control that the graphical interface was never built to expose. TMDL gives complete transparency and control over the model metadata — the same level of access previously reserved for external tooling.
Connecting Fabric Workspaces to Git with TMDL
TMDL becomes most valuable once a workspace is connected to a Git repository. Each commit captures meaningful, reviewable changes to individual model objects rather than an opaque binary diff.
- Confirm prerequisitesThe workspace must be on Fabric or Power BI Premium capacity. Enable “Users can edit data models in the Power BI service” in workspace data model settings — required for the workspace to export model metadata as serialized TMDL.
- Connect the workspace to GitIn workspace settings, select Git Integration and connect to your Azure DevOps or GitHub repository and branch.
- Sync the model as TMDLOnce connected, Power BI represents the published semantic model in the repository using TMDL files — each table, measure, and relationship as a discrete file in the folder structure described in Section 03.
- Commit changes from either directionCommit from the workspace UI after editing through TMDL View on the Web, or edit the .tmdl files directly in VS Code or another editor and push — Power BI syncs changes back to the live model from the connected branch.
A commit triggered from the workspace contains only the semantic model. A commit made from Power BI Desktop using a connected PBIP file contains both the model and the connected report. Understand which surface you are committing from — workspace-only commits will not capture report-level changes such as visual layout.
Azure DevOps CI/CD Workflow for TMDL Semantic Models
For BI architects building a real ALM (Application Lifecycle Management) pattern, TMDL is the foundation that makes Azure DevOps pull-request review and automated validation possible for semantic models — something that was never practical with binary PBIX files or single-file TMSL.
Reference Branching Pattern
feature/add-revenue-measures → Dev workspace (individual development) release/2026-q3 → Test workspace (validation before promotion) main → Production workspace (live reporting) # Azure DevOps pipeline stages Dev workspace → [PR + Review] → Test workspace → [PR + Review] → Production workspace
Recommended Enterprise ALM Stack
| Component | Role |
|---|---|
| PBIP + TMDL | Source-controlled semantic model format committed to the repository |
| Fabric Git Integration | Syncs the repository with the live workspace in both directions |
| Azure DevOps Repos | Pull request review, branch policies, required reviewers on .tmdl diffs |
| Azure DevOps Pipelines | Build validation — Tabular Editor command-line, Best Practice Analyzer rule checks |
| Power BI Deployment Pipelines | Controlled Dev → Test → Production promotion with deployment rules for swapping data sources per stage |
Pull Request Review in Practice
A developer edits a measure through TMDL View in Desktop or the web editor, commits the change to a feature branch, and opens a pull request. A reviewer opens the PR in Azure DevOps and sees exactly what changed — a few lines inside one .tmdl file — not a full-model binary replacement. This is the workflow improvement that most enterprise Power BI teams are searching for: code review applied to semantic models the same way it is applied to application code.
Most mature 2026 implementations add a Tabular Editor command-line step to the Azure DevOps pipeline that runs Best Practice Analyzer rules against the TMDL files in the PR — catching unused columns, missing descriptions, or naming convention violations automatically before merge, rather than relying solely on human reviewers.
AI-Assisted TMDL Workflows
Because TMDL represents the entire semantic model as plain text, it is directly consumable by AI coding assistants in a way a binary PBIX file never could be. This is the practical convergence between BI development and modern AI-assisted engineering workflows.
Documentation Generation
Point an AI assistant at a .tmdl file and ask it to draft column and measure descriptions based on naming patterns and DAX logic — then review and refine rather than writing from a blank page.
Translation Automation
The cultures/ folder holds per-language translation files in TMDL. AI translation of display names and descriptions into a new culture file is a direct text-to-text task with a clear, reviewable output.
Measure Refactoring
Ask an AI assistant to standardize formatting strings, rename measures to match a naming convention, or identify duplicate logic across multiple .tmdl table files — programmatic operations difficult to perform manually at scale.
Agentic Modeling via MCP
The Power BI local MCP server (Model Context Protocol) reads and writes semantic models directly using TMDL under the hood, enabling AI agents to create tables, measures, and relationships through natural language. See Model Context Protocol Power BI MCP Server for the full agent-driven modeling workflow.
Treat AI-generated TMDL the same way you would treat AI-generated application code — as a draft requiring review, not an authoritative output. Apply AI-suggested changes to a feature branch and run them through the same pull-request review and Best Practice Analyzer validation gate as human-authored changes. The text-first format is what makes this review process possible — it is also what makes skipping that review a mistake.
Current Limitations of TMDL
| Limitation | Detail |
|---|---|
| Web editor in preview | TMDL View on the Web is rolling out following its FabCon/SQLCon 2026 announcement. Feature scope may change before GA. |
| Workspace tier requirement | Editing published models via TMDL requires a Fabric or Power BI Premium workspace — not available on shared/Pro-only workspaces. |
| Diagram layout not in TMDL | Report-level diagram view metadata is stored separately and, during preview, does not support external editing. |
| Requires explicit opt-in for editing | “Users can edit data models in the Power BI service” must be explicitly enabled per workspace — not on by default. |
| Learning curve for non-developers | TMDL syntax, while more readable than TMSL, still requires comfort with text-based, indentation-sensitive editing — a shift for UI-only modelers. |
| External tool dependency for some workflows | Certain bulk operations and Best Practice Analyzer validation still rely on external tools like Tabular Editor rather than native Fabric tooling. |
FAQ — Power BI TMDL Tutorial
Official Resources — Power BI TMDL Documentation
Information is verified against official Microsoft Learn TMDL documentation and the Power BI blog through June 2026. TMDL View on the Web is in preview — features and availability may change before General Availability. UIG Data Lab is an independent publication, not affiliated with Microsoft Corporation.