pbip

# 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 file editing.** To modify TMDL files (semantic model), load the `tmdl` skill. To modify PBIR JSON files (report), load the `pbir-format` skill -- or preferably use the `pbir` CLI with the `pbir-cli` skill if available. Install with `uv tool install pbir-cli` or `pip install pbir-cli`; check with `pbir --version`. If the required skill is not loaded, ask the user to install the appropriate plugin before proceeding.
- **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.
- **PBI Desktop does not detect external changes.** Close and reopen PBI Desktop after editing files externally.
- **Rename cascades are cross-cutting.** Renaming a table, measure, or column requires updating references in TMDL files, visual JSONs, report extensions, culture files, DAX queries, and diagram layouts. Missing even one location causes broken visuals or DAX errors.
- **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

A `.pbix` file is a ZIP archive following the OPC (Open Packaging Convention) standard. It can be extracted with standard zip tools to inspect its contents or manually assemble a PBIP from the extracted files.

### PBIX Internal Structure

**Thick PBIX** -- contains an embedded semantic model (`DataModel` binary). The report and model are bundled together:

```
ThickReport.pbix (ZIP archive)
+-- [Content_Types].xml          # OPC manifest (UTF-8 with BOM)
+-- Version                      # Power BI version string (UTF-16LE)
+-- Settings                     # Query settings JSON (UTF-16LE)
+-- Metadata                     # Creation timestamp JSON (UTF-16LE)
+-- SecurityBindings             # Binary (empty for new reports)
+-- DataModel                    # <-- THIS MAKES IT THICK: binary ABF blob (opaque, not programmatically readable)
+-- Report/
|   +-- definition/              # PBIR report definition (modern PBIX)
|   |   +-- report.json
|   |   +-- pages/
|   |   +-- ...
|   +-- Layout                   # Legacy monolithic JSON (legacy PBIX, UTF-16LE)
|   +-- StaticResources/         # Themes, images
```

**Thin PBIX** -- no embedded model. Uses a `Connections` file to reference a remote semantic model:

```
ThinReport.pbix (ZIP archive)
+-- [Content_Types].xml          # OPC manifest (UTF-8 with BOM)
+-- Version                      # Power BI version string (UTF-16LE)
+-- Settings                     # Query settings JSON (UTF-16LE)
+-- Metadata                     # Creation timestamp JSON (UTF-16LE)
+-- SecurityBindings             # Binary (empty for new reports)
+-- Connections                  # <-- Remote model reference (UTF-8 JSON, contains connection string)
+-- Report/
|   +-- definition/              # PBIR report definition (modern PBIX)
|   |   +-- report.json
|   |   +-- pages/
|   |   +-- ...
|   +-- Layout                   # Legacy monolithic JSON (legacy PBIX, UTF-16LE)
|   +-- StaticResources/         # Themes, images
```

A PBIX is thick if `DataModel` exists in the ZIP; thin if it has `Connections` instead. The `Report/` folder structure is the same in both cases. A PBIX will have either `Report/definition/` (modern PBIR format) or `Report/Layout` (legacy format), not both.

### Thick vs Thin PBIX

A **thick PBIX** contains a `DataModel` entry -- a binary ABF (Analysis Services Backup) blob with the semantic model data and metadata baked in. A **thin PBIX** has no `DataModel` and instead has a `Connections` file (UTF-8 JSON) pointing to a remote semantic model. The `DataModel` binary cannot be deserialized programmatically -- thick PBIX semantic models are opaque.

### Legacy vs Modern PBIX

Legacy PBIX files (pre-PBIR) store the report as a single `Report/Layout` file encoded in UTF-16LE -- a monolithic JSON blob with nested JSON strings (e.g. `config`, `filters`, `query` are JSON-encoded strings inside the outer JSON). Modern PBIX files store the report in `Report/definition/` using the PBIR JSON format with separate files per page and visual. Detect legacy format by checking for the `Report/Layout` entry in the ZIP.

### Encoding

PBIX internal files use mixed encodings:

| File | Encoding |
|------|----------|
| `Version`, `Settings`, `Metadata` | UTF-16LE |
| `Connections` | UTF-8 |
| `Report/definition/` contents | UTF-8 |
| `Report/Layout` (legacy) | UTF-16LE |
| `[Content_Types].xml` | UTF-8 with BOM |
| `SecurityBindings`, `DataModel` | Binary |

Mismatched encoding when reading or writing these files causes