Programmatic Power BI Development
Overview
Power BI supports multiple approaches for creating and managing reports and semantic models through code. As of 2026, the canonical stack is:
- PBIP (Power BI Project) as the folder-based source format
- TMDL as the semantic-model format inside PBIP (see
tmdl-mastery skill)
- PBIR (Power BI Enhanced Report Format) as the report format inside PBIP
- fabric-cicd (Python) or Fabric CLI
fab deploy for deployment
- TOM / .NET SDK for advanced programmatic model editing
- semantic-link-labs for Python-based scripting from Fabric notebooks
Reference Map
Detailed material lives in references/. Load only what the current task needs.
| Topic |
File |
When to load |
| PBIR rollout timeline, full PBIP folder structure, byPath/byConnection, annotations, validation, limitations |
references/pbir-format-deep-dive.md |
Authoring PBIR by hand, debugging definition.pbir, validating generated PBIR, understanding 2026 rollout state |
| PBIR JSON schema (visuals, pages, report settings) with Python manipulation examples |
references/pbir-schema-reference.md |
Scripting PBIR with Python: add page, batch-update visuals, copy between reports |
| TOM/Tabular Editor/fabric-cicd/Fabric CLI/semantic-link/pbi-tools/ALM Toolkit -- setup, examples, Desktop developer features |
references/tools-and-tabular-editor.md |
Choosing a tool, deploying, scripting TOM, running C# scripts, configuring Desktop |
| TOM advanced patterns (RLS, OLS, partitions, perspectives, translations, calc groups, SP auth) |
references/tom-advanced-patterns.md |
Writing complex TOM .NET code beyond basic measure/table edits |
| fabric-cicd advanced recipes (multi-workspace, hooks, GitHub Actions/Azure DevOps pipelines, parameter patterns, troubleshooting) |
references/fabric-cicd-recipes.md |
Production CI/CD workflows, multi-environment promotion, OIDC federated credentials |
PBIR - Power BI Enhanced Report Format
PBIR is Microsoft's modern, publicly documented, folder-based, JSON report format. It replaces the opaque report.json blob (now called PBIR-Legacy) with one file per visual, page, and bookmark, enabling proper Git diff/merge, code review, and schema-validated editing in VS Code.
Current state (April 2026): PBIR is the default for newly created reports in the Service. Existing Service reports are being auto-upgraded gradually. Desktop still needs the preview toggle until the May 2026 release, when PBIR becomes the Desktop default. PBIR-Legacy will be deprecated at PBIP GA.
For the full 2026 rollout timeline, admin opt-out, Service/Desktop restore policies, Sovereign Cloud caveats, complete project structure, byPath vs byConnection examples, annotations, self-validation procedure, and limitations, see references/pbir-format-deep-dive.md.
Quick PBIP structure (essentials only):
MyProject.pbip # Entry JSON
├── MyProject.Report/
│ ├── definition.pbir # Required entry; uses byPath or byConnection
│ └── definition/ # PBIR folder (one file per page/visual/bookmark)
└── MyProject.SemanticModel/
├── definition.pbism
└── definition/ # TMDL folder
TMDL - Tabular Model Definition Language
TMDL is the human-readable, source-control-friendly format for semantic model definitions. GA since 2025. For comprehensive TMDL coverage including complete syntax reference, all object types, CI/CD patterns, and deployment workflows, load the dedicated powerbi-master:tmdl-mastery skill.
Quick example:
table Sales
measure 'Total Sales' = SUM(Sales[Amount])
formatString: $ #,##0.00
displayFolder: Revenue
partition 'Sales-Partition' = m
mode: import
source =
let
Source = Sql.Database("server", "db"),
Sales = Source{[Schema="dbo",Item="Sales"]}[Data]
in
Sales
column Amount
dataType: decimal
sourceColumn: Amount
formatString: $ #,##0.00
Core Workflow
- Pick the source format — PBIP (modern, TMDL + PBIR) for new work; legacy PBIX only for Report Server or pre-PBIP projects.
- Edit programmatically — VS Code for PBIR/TMDL JSON; Tabular Editor for model authoring; semantic-link-labs for Fabric notebooks; TOM .NET for custom apps.
- Validate locally — JSON schema, PBI-InspectorV2, lineage walker, BPA. See
powerbi-master:validation-testing skill.
- Parameterize —
parameter.yml for environment-specific GUIDs/connection strings.
- Deploy —
fabric-cicd (Python library, primary) or fab deploy (CLI wrapper). Both consume the same parameter.yml. First deploy requires manual data-source credential entry in the Fabric portal.
- Diff and promote — ALM Toolkit for schema diff; Fabric Deployment Pipelines or scripted multi-workspace deploy for promotion.
Deployment Decision Matrix (2026)
| Scenario |
Recommended Tool |
| PBIP project with CI/CD (GitHub Actions / Azure DevOps) |
fabric-cicd (Python) |
| Local ad-hoc deploy of a PBIP |
fab deploy (Fabric CLI v1.5+) |
| Fabric notebook-based model editing |
semantic-link-labs (sempy_labs) |
| Pure semantic model via XMLA |
TOM (.NET) via Microsoft.AnalysisServices.NetCore.retail.amd64 |
| TMDL folder -> XMLA |
Tabular Editor 2 CLI (-D switch) |
| Legacy PBIX only (no PBIP) |
pbi-tools |
| Cross-environment promotion (dev/test/prod) |
Fabric Deployment Pipelines (GUI) OR fabric-cicd with parameter.yml |
| Schema diff between two models |
ALM Toolkit |
Tool Quick-Pick
| Need |
Load reference |
Tool |
| Modify a measure on a deployed model |
tools-and-tabular-editor.md |
TOM or semantic-link-labs |
| Auto-generate measures across folders |
tools-and-tabular-editor.md |
Tabular Editor C# script |
| Deploy PBIP from CI |
fabric-cicd-recipes.md |
fabric-cicd + parameter.yml |
| Generate PBIR pages from a template |
pbir-schema-reference.md |
Python + JSON schema validation |
| RLS/OLS in .NET |
tom-advanced-patterns.md |
TOM |
| Extract legacy PBIX for diff |
tools-and-tabular-editor.md |
pbi-tools |
Related Skills
powerbi-master:tmdl-mastery -- Deep TMDL language reference and syntaxpowerbi-master:validation-testing -- Validate generated PBIR / TMDL / DAX before deploypowerbi-master:rest-api-automation -- Raw Fabric REST API endpoints when fabric-cicd doesn't cover a scenariopowerbi-master:deployment-admin -- Fabric Deployment Pipelines, workspace management, RLS at deploy timepowerbi-master:fabric-integration -- Direct Lake, OneLake, Lakehouse/Warehouse integration
Official Microsoft References (2026)
1---2name: programmatic-development3description: Programmatic Power BI development with PBIR, PBIP, TMDL, TOM, and fabric-cicd. PROACTIVELY activate for: (1) creating Power BI reports programmatically (PBIR enhanced report format), (2) PBIR vs PBIR-Legacy selection (2026 default), (3) PBIP developer mode and Power BI project files, (4) Tabular Object Model (TOM) / .NET SDK scripting, (5) Tabular Editor scripting (C# scripts, advanced scripting), (6) pbi-tools workflows, (7) fabric-cicd Python deployments (FabricWorkspace, publish_all_items), (8) Fabric CLI (fab deploy), (9) Semantic Link / sempy / semantic-link-labs, (10) generating PBIX programmatically, (11) parameter.yml for environment-specific deployments, (12) ALM Toolkit. Provides: PBIR/PBIP project templates, fabric-cicd deploy.py, Tabular Editor scripting recipes, parameter.yml patterns, and end-to-end programmatic workflows.4---5
6# Programmatic Power BI Development
7
8## Overview
9
10Power BI supports multiple approaches for creating and managing reports and semantic models through code. As of 2026, the canonical stack is:
11
12- **PBIP** (Power BI Project) as the folder-based source format
13- **TMDL** as the semantic-model format inside PBIP (see `tmdl-mastery` skill)
14- **PBIR** (Power BI Enhanced Report Format) as the report format inside PBIP
15- **fabric-cicd** (Python) or **Fabric CLI `fab deploy`** for deployment
16- **TOM / .NET SDK** for advanced programmatic model editing
17- **semantic-link-labs** for Python-based scripting from Fabric notebooks
18
19## Reference Map
20
21Detailed material lives in `references/`. Load only what the current task needs.
22
23| Topic | File | When to load |
24|-------|------|--------------|
25| PBIR rollout timeline, full PBIP folder structure, byPath/byConnection, annotations, validation, limitations | `references/pbir-format-deep-dive.md` | Authoring PBIR by hand, debugging definition.pbir, validating generated PBIR, understanding 2026 rollout state |
26| PBIR JSON schema (visuals, pages, report settings) with Python manipulation examples | `references/pbir-schema-reference.md` | Scripting PBIR with Python: add page, batch-update visuals, copy between reports |
27| TOM/Tabular Editor/fabric-cicd/Fabric CLI/semantic-link/pbi-tools/ALM Toolkit -- setup, examples, Desktop developer features | `references/tools-and-tabular-editor.md` | Choosing a tool, deploying, scripting TOM, running C# scripts, configuring Desktop |
28| TOM advanced patterns (RLS, OLS, partitions, perspectives, translations, calc groups, SP auth) | `references/tom-advanced-patterns.md` | Writing complex TOM .NET code beyond basic measure/table edits |
29| fabric-cicd advanced recipes (multi-workspace, hooks, GitHub Actions/Azure DevOps pipelines, parameter patterns, troubleshooting) | `references/fabric-cicd-recipes.md` | Production CI/CD workflows, multi-environment promotion, OIDC federated credentials |
30
31## PBIR - Power BI Enhanced Report Format
32
33PBIR is Microsoft's modern, publicly documented, folder-based, JSON report format. It replaces the opaque `report.json` blob (now called PBIR-Legacy) with one file per visual, page, and bookmark, enabling proper Git diff/merge, code review, and schema-validated editing in VS Code.
34
35**Current state (April 2026):** PBIR is the default for newly created reports in the Service. Existing Service reports are being auto-upgraded gradually. Desktop still needs the preview toggle until the **May 2026** release, when PBIR becomes the Desktop default. PBIR-Legacy will be deprecated at PBIP GA.
36
37For the full 2026 rollout timeline, admin opt-out, Service/Desktop restore policies, Sovereign Cloud caveats, complete project structure, byPath vs byConnection examples, annotations, self-validation procedure, and limitations, see `references/pbir-format-deep-dive.md`.
38
39**Quick PBIP structure (essentials only):**
40
41```text
42MyProject.pbip # Entry JSON
43├── MyProject.Report/
44│ ├── definition.pbir # Required entry; uses byPath or byConnection
45│ └── definition/ # PBIR folder (one file per page/visual/bookmark)
46└── MyProject.SemanticModel/
47 ├── definition.pbism
48 └── definition/ # TMDL folder
49```
50
51## TMDL - Tabular Model Definition Language
52
53TMDL is the human-readable, source-control-friendly format for semantic model definitions. GA since 2025. For comprehensive TMDL coverage including complete syntax reference, all object types, CI/CD patterns, and deployment workflows, load the dedicated `powerbi-master:tmdl-mastery` skill.
54
55Quick example:
56
57```tmdl
58table Sales
59 measure 'Total Sales' = SUM(Sales[Amount])
60 formatString: $ #,##0.00
61 displayFolder: Revenue
62
63 partition 'Sales-Partition' = m
64 mode: import
65 source =
66 let
67 Source = Sql.Database("server", "db"),
68 Sales = Source{[Schema="dbo",Item="Sales"]}[Data]
69 in
70 Sales
71
72 column Amount
73 dataType: decimal
74 sourceColumn: Amount
75 formatString: $ #,##0.00
76```
77
78## Core Workflow
79
801. **Pick the source format** — PBIP (modern, TMDL + PBIR) for new work; legacy PBIX only for Report Server or pre-PBIP projects.
812. **Edit programmatically** — VS Code for PBIR/TMDL JSON; Tabular Editor for model authoring; semantic-link-labs for Fabric notebooks; TOM .NET for custom apps.
823. **Validate locally** — JSON schema, PBI-InspectorV2, lineage walker, BPA. See `powerbi-master:validation-testing` skill.
834. **Parameterize** — `parameter.yml` for environment-specific GUIDs/connection strings.
845. **Deploy** — `fabric-cicd` (Python library, primary) or `fab deploy` (CLI wrapper). Both consume the same `parameter.yml`. First deploy requires manual data-source credential entry in the Fabric portal.
856. **Diff and promote** — ALM Toolkit for schema diff; Fabric Deployment Pipelines or scripted multi-workspace deploy for promotion.
86
87## Deployment Decision Matrix (2026)
88
89| Scenario | Recommended Tool |
90|----------|------------------|
91| PBIP project with CI/CD (GitHub Actions / Azure DevOps) | `fabric-cicd` (Python) |
92| Local ad-hoc deploy of a PBIP | `fab deploy` (Fabric CLI v1.5+) |
93| Fabric notebook-based model editing | `semantic-link-labs` (sempy_labs) |
94| Pure semantic model via XMLA | TOM (.NET) via `Microsoft.AnalysisServices.NetCore.retail.amd64` |
95| TMDL folder -> XMLA | Tabular Editor 2 CLI (`-D` switch) |
96| Legacy PBIX only (no PBIP) | `pbi-tools` |
97| Cross-environment promotion (dev/test/prod) | Fabric Deployment Pipelines (GUI) OR `fabric-cicd` with `parameter.yml` |
98| Schema diff between two models | ALM Toolkit |
99
100## Tool Quick-Pick
101
102| Need | Load reference | Tool |
103|------|---------------|------|
104| Modify a measure on a deployed model | `tools-and-tabular-editor.md` | TOM or semantic-link-labs |
105| Auto-generate measures across folders | `tools-and-tabular-editor.md` | Tabular Editor C# script |
106| Deploy PBIP from CI | `fabric-cicd-recipes.md` | fabric-cicd + parameter.yml |
107| Generate PBIR pages from a template | `pbir-schema-reference.md` | Python + JSON schema validation |
108| RLS/OLS in .NET | `tom-advanced-patterns.md` | TOM |
109| Extract legacy PBIX for diff | `tools-and-tabular-editor.md` | pbi-tools |
110
111## Related Skills
112
113- `powerbi-master:tmdl-mastery` -- Deep TMDL language reference and syntax
114- `powerbi-master:validation-testing` -- Validate generated PBIR / TMDL / DAX before deploy
115- `powerbi-master:rest-api-automation` -- Raw Fabric REST API endpoints when fabric-cicd doesn't cover a scenario
116- `powerbi-master:deployment-admin` -- Fabric Deployment Pipelines, workspace management, RLS at deploy time
117- `powerbi-master:fabric-integration` -- Direct Lake, OneLake, Lakehouse/Warehouse integration
118
119## Official Microsoft References (2026)
120
121- [Deploy PBIP with fabric-cicd](https://learn.microsoft.com/en-us/power-bi/developer/projects/projects-deploy-fabric-cicd)
122- [Power BI enhanced report format (PBIR)](https://learn.microsoft.com/en-us/power-bi/developer/projects/projects-report)
123- [Fabric CLI v1.5 GA](https://blog.fabric.microsoft.com/en-US/blog/fabric-cli-v1-5-is-here-generally-available/)
124- [PBIR will become the default Power BI Report Format](https://powerbi.microsoft.com/en-us/blog/pbir-will-become-the-default-power-bi-report-format-get-ready-for-the-transition/)
125- [fabric-cicd GitHub](https://github.com/microsoft/fabric-cicd) and [docs](https://microsoft.github.io/fabric-cicd/latest/)
126- [semantic-link-labs GitHub](https://github.com/microsoft/semantic-link-labs)
127- [PBIR JSON schemas](https://github.com/microsoft/json-schemas/tree/main/fabric/item/report/definition)
josiahsiegel