JosiahSiegel/programmatic-development

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

1. Pick the source format — PBIP (modern, TMDL + PBIR) for new work; legacy PBIX only for Report Server or pre-PBIP projects.
2. Edit programmatically — VS Code for PBIR/TMDL JSON; Tabular Editor for model authoring; semantic-link-labs for Fabric notebooks; TOM .NET for custom apps.
3. Validate locally — JSON schema, PBI-InspectorV2, lineage walker, BPA. See powerbi-master:validation-testing skill.
4. Parameterize — parameter.yml for environment-specific GUIDs/connection strings.
5. 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.
6. 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 syntax
• powerbi-master:validation-testing -- Validate generated PBIR / TMDL / DAX before deploy
• powerbi-master:rest-api-automation -- Raw Fabric REST API endpoints when fabric-cicd doesn't cover a scenario
• powerbi-master:deployment-admin -- Fabric Deployment Pipelines, workspace management, RLS at deploy time
• powerbi-master:fabric-integration -- Direct Lake, OneLake, Lakehouse/Warehouse integration

Official Microsoft References (2026)

• Deploy PBIP with fabric-cicd
• Power BI enhanced report format (PBIR)
• Fabric CLI v1.5 GA
• PBIR will become the default Power BI Report Format
• fabric-cicd GitHub and docs
• semantic-link-labs GitHub
• PBIR JSON schemas