pbip-project-structure

name: pbip-project-structure description: Use when working with PBIP (Power BI Project) folders — the text-based developer format that replaces binary .pbix. Covers folder layout (.SemanticModel/, .Report/, definition/, StaticResources/), entry-point files (.pbip, .pbir, .pbism, .platform), byPath vs byConnection (thick vs thin report), .pbism version 4.2 / TMDL signalling, PBIX-to-PBIP extraction (OPC ZIP, UTF-16LE vs UTF-8 internals), forking a project with new logicalId GUIDs, the rename cascade across TMDL/PBIR/DAX/bookmark/reportExtensions locations, and git hygiene (UTF-8 no BOM, CRLF, 260-char path limit, gitignoring diagramLayout.json). Invoke when user mentions .pbip, .pbir, .pbism, .platform, logicalId, PBIP conversion, forking a report, or setting up a Power BI repo for source control. paths: - "/*.pbip" - "/.pbir" - "**/.pbism" - "/.platform" - "/.Report/" - "/.SemanticModel/**"

PBIP Project Structure

Power BI Project (PBIP) is the text-based developer format for Power BI. Replaces the .pbix binary with a folder of UTF-8 text files (TMDL for semantic models, PBIR JSON for reports).

Folder Layout

<ProjectName>/
+-- <Name>.pbip                              # Optional entry point
+-- .gitignore                               # Auto-generated
+-- <Name>.SemanticModel/
|   +-- .pbi/
|   |   +-- localSettings.json               # Gitignored
|   |   +-- cache.abf                        # Data cache, gitignored
|   |   +-- unappliedChanges.json            # Pending PQ changes
|   +-- definition.pbism                     # SM entry point
|   +-- definition/                          # TMDL files
|   +-- model.bim                            # TMSL legacy (mutually exclusive)
|   +-- diagramLayout.json
|   +-- DAXQueries/                          # .dax query view tabs
|   +-- TMDLScripts/                         # .tmdl script view tabs
|   +-- .platform                            # Fabric identity
+-- <Name>.Report/
    +-- .pbi/localSettings.json              # Gitignored
    +-- definition.pbir                      # Report entry point
    +-- definition/                          # PBIR JSON files
    +-- report.json                          # PBIR-Legacy (legacy alt)
    +-- mobileState.json                     # No external edit
    +-- semanticModelDiagramLayout.json      # Diagram node positions
    +-- CustomVisuals/                       # Private .pbiviz metadata
    +-- StaticResources/RegisteredResources/ # Themes, images
    +-- DAXQueries/                          # Report-level .dax files
    +-- .platform

Entry-Point Files

.pbip

{
  "version": "1.0",
  "artifacts": [{ "report": { "path": "MyReport.Report" } }],
  "settings": { "enableAutoRecovery": true }
}

.platform

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/platformProperties/2.0.0/schema.json",
  "metadata": { "type": "Report", "displayName": "MyReport" },
  "config": { "version": "2.0", "logicalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}

• logicalId is the Fabric identity — never change on an existing deployed item
• When forking a project, logicalId MUST be regenerated to a new GUID
• type values: Report, SemanticModel

definition.pbir — byPath (Thick Project)

Report + model bundled in same project folder.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": { "path": "../MyModel.SemanticModel" }
  }
}

definition.pbir — byConnection (Thin Report)

Report connects to a remote published semantic model. Preferred for managed/shared BI.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/WorkspaceName;Initial Catalog=ModelName"
    }
  }
}

For Fabric REST API deployments, use the id form: "connectionString": "semanticmodelid=[SemanticModelId]".

Do NOT use the legacy six-property form (pbiServiceModelId, pbiModelVirtualServerName, etc.) for new reports.

definition.pbism

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/semanticModel/definitionProperties/1.0.0/schema.json",
  "version": "4.2",
  "settings": {}
}

PBIX vs PBIP

PBIX Extraction

A .pbix is a ZIP (OPC) archive. Thick PBIX contains a DataModel binary (opaque ABF); thin PBIX has a Connections file instead. Modern PBIX stores reports in Report/definition/ (PBIR); legacy PBIX uses a monolithic Report/Layout (UTF-16LE).

import zipfile
with zipfile.ZipFile("MyReport.pbix") as z:
    z.extractall("MyReport_extracted")
# Detect type
is_thick = Path("MyReport_extracted/DataModel").exists()
is_modern = Path("MyReport_extracted/Report/definition/report.json").exists()

Assembling a PBIP from an extracted thin PBIX: copy Report/definition/ into <Name>.Report/definition/, generate definition.pbir with byConnection, generate .platform with a new logicalId GUID.

Thick PBIX cannot be converted programmatically — the DataModel binary is opaque. Use PBI Desktop File → Save As.

Forking a Project

1. Copy the entire project folder, rename the root
2. Rename .Report/ and .SemanticModel/ subfolders
3. Update .pbip → artifacts[].report.path
4. Update .pbir → datasetReference.byPath.path (if byPath)
5. Update each .platform (Report and SemanticModel separately) → set the appropriate displayName and regenerate a NEW unique logicalId per file (the two .platform files get different GUIDs)

Rename Cascade

Renaming a table, measure, or column requires updates in every location that references it. Missing one causes broken visuals or DAX errors.

Commonly missed: sortDefinition blocks, SparklineData compact strings, bookmark highlight.dataMap keys, the second DAX query location, references.measures[].entity nested inside reportExtensions.json.

Git-Friendly Organization

• Set core.autocrlf or add * text=auto to .gitattributes — PBI Desktop writes CRLF
• UTF-8 without BOM for all files — a BOM prefix causes parse errors
• Keep the root path short — 260-char Windows path limit; page/visual GUID folders can exceed it
• Rename PBIR GUID folders (0c32c81b...) to human names (Overview, lineChart_Sales) for better diffs. Folder names are freely renamable; page.json / visual.json filenames and internal name properties must NOT change
• Multiple .Report/ and .SemanticModel/ folders can coexist in one project
• Fabric Git Integration only processes definition.pbir — other .pbir files are ignored but can coexist

Gotchas

Reference

• Microsoft Learn: Power BI Desktop project (PBIP) overview
• Microsoft Learn: Power BI Desktop project — semantic model folder
• Microsoft Learn: Introduction to Fabric Git integration
• Comprehensive MS Learn link bundle (PBIP docs / entry-point file shapes / Direct Lake live editing / Fabric Git / REST envelope / TMDL): references/REFERENCE.md

See also

• pbir-cli — pbir CLI command reference
• pbir-report-workflow — report creation workflow
• pbir-pages — page JSON structure
• fabric-tmdl — TMDL authoring rules