/pbip

name: pbip
description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations.

PBIP Project Format

PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a `.pbix` binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.

General, critical guidance

• **This skill covers project structure, not report editing.** Use `te` for the semantic model and

`pbir` for every report mutation. Never hand-edit PBIR JSON.

• **PBIX is a black box; PBIP is transparent.** PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop.
• **Thick vs thin reports:** A thick report bundles `.Report/` + `.SemanticModel/` in the same project (`definition.pbir` uses `byPath`). A thin report has `.Report/` only, connecting to a remote model via `byConnection`. Thin reports are preferred for managed/shared BI.
• **A project can contain multiple items.** Multiple `.Report/` and `.SemanticModel/` folders can coexist. The `.pbip` file is optional -- open `definition.pbir` directly.
• **UTF-8 without BOM.** All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools.
• **Git line endings:** PBI Desktop writes CRLF. Configure `core.autocrlf` or `* text=auto` in `.gitattributes` to normalize.
• **260-char Windows path limit.** Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit.
• **Desktop reload is selective.** Use `pbir desktop refresh` for supported report/model changes;

close and reopen Desktop for theme changes.

• **Rename cascades are cross-cutting.** Rename model objects with `te mv --save`, then update each

report with `pbir fields replace` or `replace-table` and validate both sides.

• **SparklineData metadata** selectors embed Entity references in compact strings that do not follow the standard `SourceRef.Entity` JSON structure. Easy to miss.
• **DAX query files exist in TWO locations:** `<Name>.SemanticModel/DAXQueries/` and `<Name>.Report/DAXQueries/`. Always check both during renames.

Working with PBIX Files

Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.

Use Power BI Desktop **File > Save As > Power BI Project (.pbip)**, then work on the resulting `.Report` folder with `pbir` and on the semantic model with `te`. If Desktop conversion is not available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path.

PBIX vs PBIP

| Aspect | PBIX | PBIP | |--------|------|------| | Format | Single binary file | Folder of text files | | Source control | Not diff-friendly | Git-ready, human-readable diffs | | Collaboration | Single author at a time | Multiple authors, merge-friendly | | External editing | Not supported | VS Code, Tabular Editor, scripts | | Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd | | Data | Contains cached data | `cache.abf` is gitignored; metadata only in Git | | Convert | File > Save As > PBIP | File > Save As > PBIX |

Project Structure

The `.Report/` folder is required in a PBIP. The `.SemanticModel/` folder is optional — a thin report has only `.Report/` and points at a remote semantic model via `definition.pbir` `byConnection`.

The `.pbi/` subfolders in both items (`localSettings.json`, `editorSettings.json`, `cache.abf`, etc.) are **all optional** — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.

<ProjectName>/
+-- <Name>.pbip                              # Entry point (references .Report folder) — optional
+-- .gitignore                               # Recommended; excludes .pbi/localSettings.json and cache.abf
+-- <Name>.SemanticModel/                    # OPTIONAL — absent for thin reports
|   +-- .pbi/                                # All contents OPTIONAL, per-user runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   |   +-- editorSettings.json              # Editor settings (committed)
|   |   +-- cache.abf                        # Data cache (gitignored)
|   |   +-- unappliedChanges.json            # Pending Power Query changes
|   |   +-- daxQueries.json                  # DAX query view tab settings
|   |   +-- tmdlscripts.json                 # TMDL view script tab settings
|   +-- definition.pbism                     # SM entry point (required if .SemanticModel exists)
|   +-- definition/                          # TMDL format (preferred) — see tmdl skill
|   +-- model.bim                            # TMSL format (legacy alt to definition/, mutually exclusive)
|   +-- diagramLayout.json                   # SM diagram (no external edit)
|   +-- DAXQueries/                          # .dax files from DAX query view
|   +-- TMDLScripts/                         # .tmdl files from TMDL view
|   +-- Copilot/                             # Copilot tooling metadata
|   +-- .platform                            # Fabric identity (displayName, logicalId)
+-- <Name>.Report/                           # REQUIRED
|   +-- .pbi/                                # OPTIONAL runtime state
|   |   +-- localSettings.json               # User-specific (gitignored)
|   +-- definition.pbir                      # Report entry point (required for PBIR format)
|   +-- definition/                          # PBIR format — see pbir-format skill
|   |   +-- report.json
|   |   +-- version.json
|   |