{"id":113433,"date":"2026-09-29T14:53:11","date_gmt":"2026-09-29T14:53:11","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=113433"},"modified":"2026-09-29T14:57:31","modified_gmt":"2026-09-29T14:57:31","slug":"power-bi-project-pbip-format-guide","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/data-analytics\/powerbi\/power-bi-project-pbip-format-guide\/","title":{"rendered":"Power BI Project (PBIP) is now generally available. Here’s why that matters – and how it works"},"content":{"rendered":"\n

Do you know where you were on June 15, 2023? Do not fret, neither do I. But I do remember a blog post written by Rui Romano<\/strong><\/a> announcing the preview of the Power BI Project (PBIP)<\/a><\/strong> format back then. <\/p>\n\n\n\n

Many in the Power BI world rejoiced at this news. Microsoft was finally<\/em> taking steps toward better practices seen in software development and applying them to the analytics space.<\/p>\n\n\n\n

As it happens, June 15, 2023 was just the first step. Since then, PBIP has evolved into the format we have today and I am happy to see that, as of September 2026, PBIP is generally available as a fully-supported feature for Power BI<\/strong> by Microsoft.<\/p>\n\n\n\n

Before I explain the mechanics of PBIP, let me outline the real problems it was designed to solve.<\/p>\n\n\n\n

TL;DR:<\/strong> A Power BI Project (PBIP) saves a Power BI report and its semantic model as folders of plain-text files instead of one binary .pbix<\/code> file. The model is stored as TMDL and the report as PBIR JSON, so Git can show exactly what changed and teams can review, merge, script and automate their work.<\/em><\/p>\n\n\n\n

Why does the Power BI Project (PBIP) format exist?<\/h2>\n\n\n\n

Have you ever worked in Power BI and someone handed you a new version of a report and you had to figure out what changed? I have. A lot of people in this industry have, too. <\/p>\n\n\n\n

The problem is, Power BI history is usually stored in a binary format, .pbix<\/strong><\/a> – and comparing two binary files is not <\/em>easy! In many cases, teams end up opening the reports side-by-side and hunting for differences.<\/p>\n\n\n\n

In a way, it’s like playing the classic game of ‘spot-the-difference’ – except, in our case, it may be five, ten, or even hundreds<\/em> of differences that matter. <\/p>\n\n\n\n

Why comparing .pbix<\/code> versions is so hard<\/h3>\n\n\n\n

It’s not just the counting that’s difficult – the real challenge is actually figuring out which differences matter, and which ones might cause issues in production.<\/p>\n\n\n\n

\"A
Comparing two Power BI Report files: it’s like ‘spot-the-difference’, only you don\u2019t know how many changes there are…<\/em><\/figcaption><\/figure>\n\n\n\n

Further, have you ever tried to keep track of different versions of your Power BI files with your folder looking like this<\/em>?:<\/p>\n\n\n\n

\"image
Does your Power BI downloads folder look like this?<\/em><\/figcaption><\/figure>\n\n\n\n

The issue is the same. A .pbix<\/code> file is binary<\/strong>, which makes it difficult to use a tool like Git<\/a><\/strong> the way we do with plain text files such as .html<\/code>, .js<\/code>, and .md<\/code>. Git is excellent at tracking changes in text, but with .pbix<\/code> we’re mostly stuck saving duplicate copies of each version. <\/p>\n\n\n\n

This, of course, fills up repositories quickly, and removes the benefit of reviewing the actual changes. Quick aside: I do know Git Large File Storage<\/a><\/strong> is an option, but that\u2019s a bridge too far for many just learning Git<\/em>. <\/p>\n\n\n\n

If you’ve worked in this industry long enough you know, that when a published report starts misbehaving, understanding what changed recently is often one of the best clues to what broke.<\/p>\n\n\n\n

That’s the kind of problem PBIP was designed to solve.<\/p>\n\n\n\n

The limits of a single .pbix<\/code> file for teams<\/h2>\n\n\n\n

Comparing versions and bloating a Git repo are just two symptoms of a bigger issue. A .pbix<\/code> file is a fine way to move one report from one person to another, but was never built to support a team working on that report together<\/em> over time. <\/p>\n\n\n\n

Reusing a tested table, measure pattern, or report page from one file in another usually means rebuilding it by hand instead of copying it over. <\/p>\n\n\n\n

Tools don’t have it much easier, either. Yes, Power BI Desktop<\/a><\/strong> can expose a semantic model<\/strong><\/a> over its local XMLA endpoint<\/strong><\/a>, but that still means standing up Desktop and making a live connection just to inspect a model. <\/p>\n\n\n\n

Linting, automated checks, and AI assistance<\/strong><\/a> are all far simpler when the model and report definition are already sitting in plain text – both on your own machine and<\/em> inside a build pipeline that has no Desktop to connect to.<\/p>\n\n\n\n

None of this means Power BI authors were doing something wrong. The file format simply did not expose the pieces that a mature delivery process needs. We’ve been building reports with an incredibly capable visual tool, living in a low-code world while trying to build practices that are better suited to high-code files.<\/p>\n\n\n\n

PBIP has changed this.<\/p>\n\n\n\n

What is a Power BI Project (PBIP)?<\/h2>\n\n\n\n

A Power BI Project is still a Power BI report and semantic model. <\/strong>It’s not a different product, and you don’t need to stop using Power BI Desktop. The change is how<\/em> the work is stored on disk.<\/p>\n\n\n\n

Instead of keeping the report and model inside one .pbix<\/code> file, Power BI Desktop saves your report and semantic model as separate folders with a small project entry-point file (.pbip<\/code>)<\/strong> that can be double-clicked to open your report in Power BI Desktop. <\/p>\n\n\n\n

The SampleModel<\/code> project I use in my own training sessions looks like this:<\/p>\n\n\n\n

SampleModel\/\n\u251c\u2500\u2500 SampleModel.pbip\n\u251c\u2500\u2500 SampleModel.Report\/\n\u2502   \u251c\u2500\u2500 .pbi\/\n\u2502   \u251c\u2500\u2500 .platform\n\u2502   \u251c\u2500\u2500 definition.pbir\n\u2502   \u251c\u2500\u2500 definition\/\n\u2502   \u2514\u2500\u2500 StaticResources\/\n\u251c\u2500\u2500 SampleModel.SemanticModel\/\n\u2502   \u251c\u2500\u2500 .pbi\/\n\u2502   \u251c\u2500\u2500 .platform\n\u2502   \u251c\u2500\u2500 definition.pbism\n\u2502   \u251c\u2500\u2500 definition\/\n\u2502   \u251c\u2500\u2500 diagramLayout.json\n\u2502   \u251c\u2500\u2500 DAXQueries\/\n\u2502   \u2514\u2500\u2500 TMDLScripts\/\n\u2514\u2500\u2500 .gitignore<\/pre><\/div>\n\n\n\n
PBIX vs PBIP: a quick summary<\/h2>\n\n\n\n
Feature<\/th>.pbix<\/th>PBIP<\/th><\/tr><\/thead>
Storage<\/td>One binary file<\/td>Folders of plain-text files<\/td><\/tr>
Git diffs<\/td>Whole-file copies only<\/td>Line-level changes<\/td><\/tr>
Semantic model<\/td>Inside the binary<\/td>TMDL, roughly one file per table<\/td><\/tr>
Report<\/td>Inside the binary<\/td>PBIR, separate JSON files for pages and visuals<\/td><\/tr>
Data<\/td>Ships in the file<\/td>Stays in the git-ignored .pbi\/cache.abf<\/code><\/td><\/tr>
Automation and linting<\/td>Needs Desktop<\/td>Works on plain text, including in build pipelines<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
What’s inside a PBIP folder structure?<\/h2>\n\n\n\n
There are a few details in this structure that will help you understand how it works.<\/p>\n\n\n\n
The .pbip entry-point file<\/h3>\n\n\n\n
Firstly, the .pbip<\/code> file is the project entry point<\/strong>. It points Power BI Desktop at a report folder. When you double-click this file in File Explorer, Desktop reads the artifacts array, follows report.path<\/code>, and opens the SampleModel.Report<\/code> folder:<\/p>\n\n\n\n
{\n  \"$schema\": \"https:\/\/developer.microsoft.com\/json-schemas\/fabric\/pbip\/pbipProperties\/1.0.0\/schema.json\",\n  \"version\": \"1.0\",\n  \"artifacts\": [\n    {\n      \"report\": {\n        \"path\": \"SampleModel.Report\"\n      }\n    }\n  ],\n  \"settings\": {\n    \"enableAutoRecovery\": true\n  }\n}<\/pre><\/div>\n\n\n\n
The .Report<\/code> folder holds the report definition, including pages, visuals, bookmarks, themes, and the reference to its semantic model. <\/p>\n\n\n\n
Note that if the .pbip<\/code> file is ever missing, you can double-click definition.pbir<\/code> in the .Report<\/code> folder instead, and Power BI Desktop opens the report directly. <\/p>\n\n\n\n
It also tells Desktop which semantic model the report should connect to:<\/p>\n\n\n\n
{\n  \"$schema\": \"https:\/\/developer.microsoft.com\/json-schemas\/fabric\/item\/report\/definitionProperties\/2.0.0\/schema.json\",\n  \"version\": \"4.0\",\n  \"datasetReference\": {\n    \"byPath\": {\n      \"path\": \"..\/SampleModel.SemanticModel\"\n    }\n  }\n}<\/pre><\/div>\n\n\n\n
Thick reports vs thin reports<\/h3>\n\n\n\n
The definition.pbir<\/code> above points to the local semantic model with a relative path, often called a thick report<\/strong> because the report and model travel together. byPath<\/code> uses a relative path, not an absolute path, and always forward slashes<\/strong>, even on Windows – so the reference still works after you clone the repository somewhere else. <\/p>\n\n\n\n
When Power BI Desktop opens a thick report, it also opens the referenced semantic model in full edit mode. But what does it look like when the report instead references a semantic model already published to the cloud (sometimes called a thin report<\/strong>?) <\/p>\n\n\n\n
Here is the thin report version of the JSON<\/strong><\/a>:<\/p>\n\n\n\n
{\n  \"$schema\": \"https:\/\/developer.microsoft.com\/json-schemas\/fabric\/item\/report\/definitionProperties\/2.0.0\/schema.json\",\n  \"version\": \"4.0\",\n  \"datasetReference\": {\n    \"byConnection\": {\n      \"connectionString\": \"Data Source=powerbi:\/\/api.powerbi.com\/v1.0\/myorg\/pql-assert-demo;initial catalog=TestingModel;access mode=readonly;integrated security=ClaimsToken;semanticmodelid=xxxxx-ba64-40ab-9c9f-363dbxxxx\"\n    }\n  }\n}<\/pre><\/div>\n\n\n\n
Notice that byPath<\/code> becomes byConnection<\/code>, with the traditional connection string to a semantic model stored in the Power BI or Microsoft Fabric<\/strong><\/a> service.<\/p>\n\n\n\n
Why PBIP keeps your data out<\/em> of Git<\/h3>\n\n\n\n
With byConnection<\/code>, Desktop opens the report connected to the remote semantic model – but does not<\/em> open that model in edit mode. That boundary lets a report author focus on the report, while a separate team keeps ownership of the model.<\/p>\n\n\n
\n