Version-control Power BI with PBIP and TMDL

Before PBIP, "version-controlling a Power BI file" meant committing a binary .pbix. Diffs were useless; merges were impossible; code review was a screenshot exchange. PBIP solved this in 2024, and TMDL made it practical.

This guide walks through the setup, the daily workflow, and the two patterns that actually let more than one person edit a semantic model without losing work.

What PBIP and TMDL are

• PBIP (Power BI Project): a folder format. Splits into .Report (visuals, layout) and .SemanticModel (tables, measures, relationships, roles).
• TMDL (Tabular Model Definition Language): a human-readable DSL for the semantic model. Each table, measure, role, and perspective is its own file. Diff-friendly, merge-friendly, review-friendly.

Folder layout:

my_report.pbip                     ← Open this from Power BI Desktop
my_report.Report/
  definition.pbir
  report.json
  visualContainers/...
my_report.SemanticModel/
  definition.pbism
  tables/
    fct_orders.tmdl
    dim_customers.tmdl
  relationships/
    relationships.tmdl
  measures/
    sales_metrics.tmdl
  roles/
    analyst.tmdl

Every file is plain text. Every change is a legible diff.

1. Set PBIP as the default save format

Power BI Desktop → File → Options → Preview features → enable Power BI Project (.pbip) save option.

Then save any existing .pbix as PBIP: Save As → Power BI project.

2. Default the SemanticModel to TMDL

PBIP saves the semantic model as TMDL when you enable Store semantic model using TMDL format in Power BI Desktop's preview features, or when you save from Tabular Editor 3 (which produces TMDL natively).

Verify: the .SemanticModel/ folder should contain .tmdl files, not a monolithic model.bim.

3. Commit the project

git add my_report.pbip my_report.SemanticModel/ my_report.Report/
git commit -m "feat(sales-model): add YoY revenue measure"

Reviews read the TMDL diff directly:

measure 'Revenue YoY' =
    VAR Current  = [Total Revenue]
    VAR Prior    = CALCULATE([Total Revenue], SAMEPERIODLASTYEAR('dim_date'[date]))
    RETURN
        DIVIDE(Current - Prior, Prior)
formatString: 0.00%;-0.00%;0%

No screenshots, no "trust me the measure is right", just DAX in version control.

4. The concurrent-editing problem

Power BI Desktop is not great at concurrent editing of the same semantic model. Two patterns work; the third does not.

Pattern A: domain-sliced ownership

Split one monolithic semantic model into multiple domain semantic models (sales, finance, inventory). Each has one owner. Merges within a domain are rare because only one person edits it.

• sales_model.pbip
• finance_model.pbip
• inventory_model.pbip

Each owner has their own Git branch discipline; merges to main are surgical.

Pattern B: report-model separation

Report authors work on thin reports connected to a shared semantic model. They touch .Report/ files only.

One or two modelers own each shared semantic model. They work in Tabular Editor 3 (script-driven edits produce tiny TMDL diffs that are easy to review).

This way, report authors never touch the model, and the modeler ownership is narrow enough that merges are rare.

Pattern C (do not): shared semantic model, everyone edits

If five people open the same semantic model in Power BI Desktop and all push changes, you will have merge conflicts in TMDL that Power BI Desktop cannot resolve. Pattern A or B; pick one.

5. Trunk-based development

Apply the same discipline you would to code:

• Short-lived feature branches. Merged in hours, not days. The longer a branch lives, the more likely it diverges from the shared model.
• Never branch off a branch. State is compared against main.
• Per-developer dev workspaces (workspace-dev-<user>) for testing.
• Feature flags via TMDL perspectives or roles, not long-running branches, for changes that can't ship atomically.

6. PR review, the right way

Two things go wrong in Power BI PR review:

First, reviewers open the PBIP file in Desktop and "look at the report". This catches visual regressions but misses measure logic. The TMDL diff is the authoritative change record; read it.

Second, reviewers say "LGTM" on a measure change without running it. A measure that compiles may still produce the wrong number.

A practical review checklist:

• [ ] TMDL diff reads cleanly (the reviewer can describe the change without opening Desktop).
• [ ] New measures are listed in a model-change note in the PR description.
• [ ] Measure logic validated against a known period: "revenue for 2025-Q1 in this model = $X; matches the reference".
• [ ] Best Practice Analyzer (BPA) rules pass; no new violations.
• [ ] Visual regressions spot-checked by opening the report against the updated model.

7. Best Practice Analyzer as a PR gate

Tabular Editor's Best Practice Analyzer ships a strong default rule set. Typical rules enforce:

• Measures formatted consistently.
• No calculated columns on fact tables.
• No bidirectional relationships without a documented reason.
• Hidden columns on fact grain keys.
• DAX anti-patterns: / instead of DIVIDE(), implicit conversions, SUMX(FILTER(...)) over CALCULATE(SUM(...)).

Extend the default rules with org-specific ones (naming conventions, banned functions, required descriptions). Run BPA in CI:

tabular-editor-cli.exe my_report.SemanticModel \
  -A "BPA Rules.json" \
  -V

PRs with open BPA violations fail the check.

8. Tools per role

Common mistakes

See also

• CI/CD for Power BI — deploy the PBIP project via fabric-cicd.
• Model authoring standards — Causeway's rules enforced by BPA.
• DAX reference — the rules BPA checks against.