How do I install the Pbip Project Structure skill?

Run npx skillmds@latest add wardawgmalvicious/pbip-project-structure in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Pbip Project Structure skill do?

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. It is listed under Docs & Writing on SkillMD.

Is Pbip Project Structure safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Pbip Project Structure?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Pbip Project Structure free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Pbip Project Structure?

wardawgmalvicious (@wardawgmalvicious) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Pbip Project Structure by wardawgmalvicious

Name: Pbip Project Structure
Author: wardawgmalvicious

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

File	Purpose
`.pbip`	Project entry point. Optional — `definition.pbir` can be opened directly
`.pbir`	Report entry point. Points at semantic model via `byPath` or `byConnection`
`.pbism`	Semantic model entry point. `version: "4.2"` for TMDL
`.platform`	Fabric identity per item: `displayName`, `type`, `logicalId`
`version.json`	Inside `definition/` — PBIR schema version (`"2.0.0"`)

.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": {}
}

`version`	Supported Format
`1.0`	TMSL only (`model.bim`)
`4.0+`	TMSL or TMDL (`definition/` folder)

PBIX vs PBIP

PBIP is still preview. Saving as PBIP requires File > Options and settings > Options > Preview features > Power BI Project (.pbip) save option.

Aspect	PBIX	PBIP
Format	Single binary ZIP	Folder of text files
Source control	Not diff-friendly	Git-ready
External editing	Not supported	VS Code (Desktop has a built-in entry point that opens the project directly), pbir CLI, scripts
Cached data	Embedded	`cache.abf` gitignored
Conversion	File → Save As → PBIP in Desktop	File → Save As → PBIX in Desktop

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).

PBIX Internal File	Encoding
`Version`, `Settings`, `Metadata`, `Report/Layout`	UTF-16LE
`Connections`, `Report/definition/*`	UTF-8
`[Content_Types].xml`	UTF-8 with BOM
`DataModel`, `SecurityBindings`	Binary

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

Copy the entire project folder, rename the root
Rename .Report/ and .SemanticModel/ subfolders
Update .pbip → artifacts[].report.path
Update .pbir → datasetReference.byPath.path (if byPath)
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.

Location	What to Update
TMDL table/measure/column declaration	The `<type> Name` line
TMDL partition name	Matches table name
`model.tmdl`	`ref table Name` + `PBI_QueryOrder` annotation
`relationships.tmdl`	`fromColumn:` / `toColumn:` table prefix
All DAX expressions	Both `Table[` and `'Table'[` forms
visual.json query projections	`SourceRef.Entity`, `queryRef`
visual.json filter/sort/CF blocks	Nested `SourceRef.Entity`, `From[].Entity`
page.json filterConfig	`From[].Entity`
Bookmark JSONs	`filter.From[].Entity`, `expression.*.SourceRef.Entity`, `highlight.dataMap` keys
SparklineData metadata	Compact string `SparklineData(Table.Measure_[...])`
`reportExtensions.json`	Top-level `entities[].name` AND nested `references.measures[].entity`
Culture `.tmdl` linguistic metadata	`ConceptualEntity`, `ConceptualProperty`
`semanticModelDiagramLayout.json`	`nodeIndex`
DAX query files	Both `.SemanticModel/DAXQueries/` and `.Report/DAXQueries/`

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

Issue	Cause	Fix
Parse error on open	File saved with UTF-8 BOM	Re-save as UTF-8 without BOM
260-char path error on Git clone	Deep GUID folder nesting	Shorten root path; rename GUID folders
PBI Desktop ignores external edits	Apply-changes prompt dismissed or not shown	Desktop detects external project-file changes and prompts to apply them with one click — take the prompt. Reopening the project is the fallback only when no prompt appears
Broken visual after table rename	Missed cascade location	Grep for old name across `.json`, `.tmdl`, `.dax` (both DAXQueries folders)
Empty `reportExtensions.json` crashes Desktop	`"entities": []` is invalid	Delete the file instead of leaving empty
Forked project shows as same Fabric item	`logicalId` not regenerated	New GUID per `.platform` on fork
Thick PBIX cannot be converted to PBIP via script	`DataModel` binary is opaque	Use File → Save As in PBI Desktop
Merge conflicts in `diagramLayout.json`	Auto-generated per user	Treat as binary or add to `.gitignore`

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

Pbip Project Structure

File contents

PBIP Project Structure

Folder Layout

Entry-Point Files

.pbip

.platform

definition.pbir — byPath (Thick Project)

definition.pbir — byConnection (Thin Report)

definition.pbism

PBIX vs PBIP

PBIX Extraction

Forking a Project

Rename Cascade

Git-Friendly Organization

Gotchas

Reference

See also

Frequently asked questions

Pbip Project Structure

File contents

PBIP Project Structure

Folder Layout

Entry-Point Files

.pbip

.platform

definition.pbir — byPath (Thick Project)

definition.pbir — byConnection (Thin Report)

definition.pbism

PBIX vs PBIP

PBIX Extraction

Forking a Project

Rename Cascade

Git-Friendly Organization

Gotchas

Reference

See also

Related skills

Frequently asked questions

How do I install the Pbip Project Structure skill?

What does the Pbip Project Structure skill do?

Is Pbip Project Structure safe to use?

Which AI agents work with Pbip Project Structure?

Is Pbip Project Structure free to use?

Who published Pbip Project Structure?