Power BI Enhanced Report Format (PBIR) Complete 2026 Guide
What PBIR is, how it fits into Power BI Projects, the corrected rollout timeline from the June 2026 Feature Summary, folder structure, PBIX vs PBIR, migration steps, and what the rollout pause means for your team — all verified against Microsoft official documentation.
Power BI Enhanced Report Format (PBIR) stores report metadata as individual, human-readable JSON files — one per visual, page, and bookmark — instead of a compressed binary blob. It is the report layer inside Power BI Projects (.pbip), paired with TMDL for the semantic model. PBIR is not replacing .pbix. It is a change to the internal metadata format inside both .pbix and .pbip. The March 2026 Desktop default was delayed. The June 2026 Feature Summary states: service rollout re-enabled in June 2026, Desktop default moved to July/August 2026, and GA to follow — contingent on clean service rollout.
The Corrected PBIR Rollout Timeline
The original timeline published in November 2025 stated March 2026 for Power BI Desktop default. That date has moved. The June 2026 Feature Summary contains the most accurate current statement from Microsoft. Read this section carefully before planning any migration work.
Microsoft paused the PBIR default-on rollout after encountering issues when it expanded to a broader set of reports. As of the June 2026 Feature Summary: “These pauses in the default-on rollout do not represent a change in direction. PBIR will become the default code format for Power BI reports.” The June summary re-enables the service rollout in June 2026, with Desktop default pushed to July/August 2026. Source: Power BI June 2026 Feature Summary.
PBIR introduced as a Preview feature in Power BI Desktop developer mode. Optional opt-in only. PBIP files could be saved in PBIR format by enabling the Preview Feature.
All new reports created in the Power BI service default to PBIR. Existing reports begin automatic conversion to PBIR when edited and saved. Tenant admins can opt out via the tenant setting “Automatically convert and store reports using Power BI enhanced metadata format (PBIR)”. As of March 2026, automatic upgrades covered reports with fewer than 100 visuals.
PBIR Desktop default (originally planned for March 2026) was delayed to the May 2026 release, then paused again. The May 2026 Desktop release did not enable PBIR by default. Microsoft paused the rollout to resolve issues encountered when expanding to a broader set of reports. Desktop users must continue manually enabling the PBIR Preview Feature.
Microsoft re-enables the PBIR default-on rollout in the Power BI service. TMDL View on the Web also launches in June 2026 — relevant to PBIR teams using TMDL for semantic model source control. Source: June 2026 Feature Summary.
PBIR enabled by default in Power BI Desktop, contingent on a clean service rollout. Microsoft explicitly states this is contingent — not confirmed. Opt-out will still be available during Preview.
PBIR and PBIP reach GA. PBIR-Legacy removed. PBIR becomes the only supported report format. Opt-out will not be available at GA. Assuming the default-on rollout progresses smoothly through the summer.
What Is Power BI Enhanced Report Format (PBIR)?
PBIR is the new internal format for storing Power BI report metadata. Before PBIR, the report layer of a .pbix file was stored as a single large report.json file (PBIR-Legacy) — a monolithic JSON blob that could not be meaningfully diffed or merged in Git. PBIR breaks that single file into a structured folder with individual files per visual, page, and bookmark.
PBIR is not a new file you publish or share. Your reports still save as .pbix or .pbip. The change is internal — the format Power BI uses to store the report definition inside those files. For PBIX users, the transition is a silent upgrade: the file extension stays .pbix, the Save workflow does not change, and the report opens identically. The benefit appears when you look inside the file with version control tools.
What PBIR Changes
- Internal report metadata format — JSON folder instead of single blob
- Every visual, page, bookmark gets its own file
- JSON schema declaration at the top of each file enables tooling
- Merge conflicts become resolvable line-by-line
- Batch editing via VS Code find-and-replace across visual files
What PBIR Does Not Change
- The .pbix file extension — still the primary format
- The semantic model — stored separately in TMDL or .bim
- Existing datasets or measures — no DAX changes required
- Power BI Desktop UI — the Save button works identically
- Published report behaviour — visuals render identically
The June 2026 Feature Summary explicitly notes that PBIR supports AI agents and scripts that programmatically create, edit, and manage Power BI reports. Because the report definition is now structured, readable JSON, external tools — including AI coding agents — can reliably parse, modify, and generate report components without reverse-engineering a binary format. This capability did not exist in PBIR-Legacy.
PBIR Folder Structure
When you save a report using PBIR format inside a Power BI Project (.pbip), the report layer creates the following folder structure. Each component of the report gets its own file — the most consequential change from PBIR-Legacy where everything was one monolithic JSON.
MyReport.pbip ← entry point — open this in Desktop MyReport.Report/ ← PBIR report layer ├── definition.pbir ← core entry point for the report ├── definition/ │ ├── pages/ ← one JSON file per report page │ │ ├── ReportSection1/ │ │ │ └── page.json │ │ └── ReportSection2/ │ │ └── page.json │ ├── visuals/ ← one JSON file PER VISUAL │ │ ├── d3f4a1b2/ │ │ │ └── visual.json │ │ └── e9c2b7f1/ │ │ └── visual.json │ └── bookmarks/ ← one JSON file per bookmark └── mobileState.json MyReport.Dataset/ ← TMDL semantic model layer ├── model.tmdl ← tables, relationships, measures ├── tables/ │ ├── Sales.tmdl │ └── Customer.tmdl └── relationships.tmdl
The visual-per-file structure is the change that makes Git practical. Changing one chart’s colour previously produced a diff of an entire multi-megabyte JSON blob — impossible to review. With PBIR, the same change produces a 3-line diff in a single visual.json file that a code reviewer can understand in seconds.
The PBIR upgrade is irreversible — once a PBIP file is upgraded from PBIR-Legacy to PBIR, you cannot downgrade without a backup. Power BI Desktop creates an automatic backup at the time of upgrade, but that backup is only available for a limited window. Before upgrading production reports in bulk, test on one report, validate it opens cleanly, confirm custom visuals render correctly, and then proceed. The upgrade from PBIR-Legacy to PBIR is a one-way operation — treat it like a database schema migration, not a minor save-format change.
PBIX vs PBIR — What Actually Differs
The PBIX vs PBIR framing requires clarification that is missing from most coverage of this topic. PBIX is the file format — it will continue to exist. PBIR is the internal report metadata format — it will eventually be the only option inside both PBIX and PBIP. The comparison is between PBIR-Legacy (old internal format) and PBIR (new internal format), not between the .pbix and .pbip file extensions.
| Dimension | PBIR-Legacy (Current Default) | PBIR (New Format) |
|---|---|---|
| Report metadata storage | Single report.json file — one large JSON blob for all visuals, pages, bookmarks | Folder structure — one JSON file per visual, one per page, one per bookmark |
| Git diff readability | Binary or unreadable — any change modifies the entire blob | Line-by-line readable diffs — changing one visual modifies only that visual’s JSON file |
| Merge conflict resolution | Not possible — teams had to lock files and take turns | Standard Git merge conflict resolution at line level — two developers can work on different pages simultaneously |
| Batch editing | Manual UI clicks or complex regex on an opaque blob | VS Code Find and Replace across visual JSON files — change a hex colour across 500 visuals in seconds |
| External tooling | Limited — tools had to reverse-engineer the blob format | JSON schema declaration at top of each file — VS Code, Tabular Editor, AI coding agents can parse reliably |
| Programmatic report creation | Not reliably supported | Supported — AI agents and scripts can create, edit, and manage reports via the structured JSON |
| File extension | .pbix or .pbip — unchanged | .pbix or .pbip — unchanged. PBIR is internal only. |
| Semantic model affected | No | No — report layer only. Model stored separately in TMDL or .bim. |
TMDL, PBIP, and How the Three Pieces Fit Together
PBIR does not exist in isolation. It is one component of a larger shift in how Power BI handles developer workflows. Understanding the three-part structure clarifies why all three matter and what role each plays.
PBIP — Power BI Projects
The outer container. A .pbip file is the entry point that Power BI Desktop opens. It points to two sub-folders: the Report folder (PBIR) and the Dataset folder (TMDL). PBIP is the project structure that makes source control possible — the folder is what you commit to Git, not a binary file.
PBIR — Report Layer
The report metadata — visuals, pages, bookmarks, mobile state. One JSON file per component. Stored in the MyReport.Report/ folder inside a PBIP project. The format that is changing from Legacy to PBIR in 2026.
TMDL — Semantic Model Layer
Tabular Model Definition Language. The source-control-friendly format for the semantic model — tables, relationships, measures, DAX. Stored in the MyReport.Dataset/ folder. As of June 2026, TMDL View on the Web brings TMDL editing to the Power BI Service browser — previously Desktop-only.
June 2026 introduced TMDL View on the Web — bringing code-first semantic model editing to the browser. Script, preview, and apply model changes without opening Power BI Desktop, with IntelliSense and multi-line editing. For PBIR/PBIP teams doing source-control-based development, this removes the requirement to open Desktop for model metadata updates and enables browser-based CI/CD workflows for both the report (PBIR) and model (TMDL) layers simultaneously.
Impact on Power BI Development Workflows
The shift to PBIR moves Power BI reports from file-based artifacts to code artifacts. The practical impact differs significantly by role.
| Role | Before PBIR | After PBIR |
|---|---|---|
| Report developer | Lock the .pbix file while editing. Email files to colleagues. Binary uploads to Azure DevOps with no meaningful history. | Commit individual visual or page changes. Colleagues work on different pages simultaneously. Pull request reviews show readable diffs. |
| BI architect / tech lead | Code review of Power BI reports was impossible — no readable diff of visual changes. | Review visual configuration changes in pull requests. Enforce standards via CI/CD checks on visual JSON files. |
| Data modeller | Model and report changes bundled in same .pbix — had to wait for report developer to release the file. | Model changes in Dataset/TMDL folder are completely independent from report changes in Report/PBIR folder. Parallel development without file locking. |
| DevOps / platform engineer | Deployment pipelines pushed binary blobs. No automated testing of report structure. | CI/CD pipelines can parse JSON, validate visual configurations, enforce naming standards, and deploy individual page changes. |
| Self-service analyst | Saved .pbix directly. No source control. | Save workflow unchanged — .pbix saves silently in PBIR format after the default rolls out. No workflow change required. |
Who Needs to Act Now vs. Who Can Wait
The rollout pause means the urgency level has changed from the original November 2025 messaging. The practical guidance by team type:
Act Now — Enterprise BI Teams with Git
- Teams already using Azure DevOps or GitHub for Power BI
- Teams running deployment pipelines with PBIP-based workflows
- Teams using Tabular Editor, VS Code, or external tools on report files
- Action: opt in now via Desktop Preview Feature, test on a low-risk report, validate custom visuals, build the Git workflow before the default forces the transition
Plan Soon — Enterprise Teams Not Yet on Git
- Enterprises with 50+ reports currently using .pbix with no Git
- Teams using Power BI deployment pipelines (workspace-to-workspace)
- Training content creators and template builders
- Action: assign someone to evaluate PBIR on a test report, understand the opt-out process, and plan migration before GA removes the opt-out
Wait and Monitor — Solo Analysts
- Individual analysts creating personal dashboards or one-off reports
- Small teams with no Git integration and no DevOps requirements
- Action: no immediate change required. When the default rolls out (July/August 2026 target for Desktop), the Save workflow stays the same — PBIR is applied silently. No opt-in needed.
Risks to Know Before Migrating
| Risk | Detail | Mitigation |
|---|---|---|
| PBIR upgrade is irreversible | Once a PBIP file is upgraded from PBIR-Legacy to PBIR, there is no automated downgrade path | Automatic backup is created at upgrade time — keep that backup until the report is verified. Do not bulk-upgrade production reports without per-report validation. |
| Custom visuals serialisation | Some older or uncertified custom visuals may not serialise correctly in PBIR JSON during the Preview phase | Test each report containing custom visuals in a development environment before enabling PBIR. Certified visuals from AppSource are expected to work correctly. |
| Manual JSON editing corruption | Editing visual JSON files directly in VS Code without schema validation can corrupt the report if syntax errors are introduced | Use an editor with JSON schema validation. Power BI Desktop includes automatic repair for some corruption. Always commit the last clean state to Git before manual edits. |
| Rollout timing uncertainty | The July/August 2026 Desktop default is contingent on a clean service rollout — it could be delayed again | Plan against the GA date (later 2026), not against the Desktop default date. At GA, PBIR-Legacy is removed and opt-out is gone — that is the hard deadline to plan against. |
Migration Steps — Start with One Report
The correct approach to PBIR migration is per-report validation, not bulk conversion. Start with one low-risk report, complete the full workflow, and use it as the reference model for the rest of your estate.
- Enable the PBIR Preview Feature in Power BI DesktopFile → Options → Preview features → enable both: “Store reports using enhanced metadata format (PBIR)” and “Store PBIX reports using enhanced metadata format (PBIR)”. If you only want to test PBIP format first without changing your PBIX workflow, enable only the first option.
- Open the target report and save as Power BI Project (.pbip)File → Save As → Power BI Project (*.pbip). Choose a location that is or will be a Git repository. This creates the MyReport.Report/ and MyReport.Dataset/ folder structure. The original .pbix file is not modified.
- Verify the report opens and renders correctlyOpen the .pbip file in Power BI Desktop. Verify all pages load, all visuals render, and all custom visuals display correctly. Pay specific attention to any custom visuals from AppSource or third parties — these are the most common failure point during Preview.
- Initialise a Git repository and commit the folder structureNavigate to the parent folder in your terminal or VS Code. Run
git init, add a .gitignore (exclude .pbix backup files and local cache), and commit the initial state. You will immediately see thousands of readable JSON files representing your report — this is the intended result, not an error. - Make a change and verify the diffChange the colour of one chart in Power BI Desktop. Save. Run
git diffin the terminal. You should see a small, readable diff inside the specific visual’s JSON file — a few lines, not a binary change. If you see a binary diff, the PBIR Preview Feature was not enabled correctly. - Validate custom visuals and publish to servicePublish the .pbip report to Power BI Service. Verify the published report renders identically to the Desktop version. Check that any Power BI Copilot features, AI instructions, and verified answers on the underlying semantic model still function correctly — PBIR does not affect these, but validation confirms the report-to-model connection is intact.
If your team is not ready to migrate yet, configure the opt-out before the Desktop default rolls out (July/August 2026 target). In Power BI Desktop: File → Options → Preview features → disable “Store reports using enhanced metadata format (PBIR)” and “Store PBIX reports using enhanced metadata format (PBIR)”. In Power BI Service (tenant admin): Admin Portal → Tenant settings → disable “Automatically convert and store reports using Power BI enhanced metadata format (PBIR)”. Opt-out will not be available after General Availability — PBIR-Legacy is removed at GA.
Frequently Asked Questions
Timeline information is sourced from the Power BI June 2026 Feature Summary and the official PBIR transition blog. The Desktop default date (July/August 2026) and GA timeline are stated as contingent on clean service rollout — they may change. Always verify current status at learn.microsoft.com/power-bi/developer/embedded/projects-enhanced-report-format. UIG Data Lab is an independent publication, not affiliated with or endorsed by Microsoft Corporation.
