pbip-project-structure
Skill1 starsChanged 34 days agoMITView on GitHub
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.
In this repository38 other files it gives its agents.
- claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- author-skillSkill
- drift-auditSkill
- drift-handoffSkill
- drift-updateSkill
- test-skillSkill
- triageSkill
- fabric-iqSkill
- fabric-catalog-governanceSkill
- fabric-deploySkill
- fabric-rest-apiSkill
- fabric-securitySkill
- fabric-variable-librarySkill
- fabric-databaseSkill
- fabric-dataflowSkill
- fabric-data-pipelineSkill
- fabric-sparkSkill
- fabric-warehouse-monitoringSkill
- fabric-warehouseSkill
- fabric-activatorSkill
- fabric-eventhouseSkill
- fabric-event-schema-setSkill
- fabric-eventstreamSkill
- fabric-realtime-dashboardSkill
- learnSkill
- fabric-semantic-model-auditSkill
- fabric-tmdlSkill
- pbir-report-workflowSkill
- linkedin-highlightsSkill
- msix-packagingSkill
- code-reviewSkill
- commitSkill
- find-sessionSkill
- landSkill
- prune-branchesSkill
- recreate-repoSkill
- run-briefsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 81
When forking a project, logicalId MUST be regenerated to a new GUID
- Very specific: line 179
Update .pbir → datasetReference.byPath.path (if byPath)
- Very specific: line 180
Update each .platform (Report and SemanticModel separately) → set the appropriate displayName and regenerate a NEW unique logicalId per …
- Distinctive: line 209
Keep the root path short — 260-char Windows path limit.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
+-- .platformEntry-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" }
}logicalIdis the Fabric identity — never change on an existing deployed item- When forking a project,
logicalIdMUST be regenerated to a new GUID typevalues: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 and PBIR are generally available, and Learn's save-as steps name no preview feature (overview, external editing, read 2026-10-12). Detecting external edits is still a preview: see External Edits with Desktop Open.
| 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 appropriatedisplayNameand regenerate a NEW uniquelogicalIdper file (the two.platformfiles 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.autocrlfor add* text=autoto.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.jsonfilenames and internalnameproperties must NOT change - Multiple
.Report/and.SemanticModel/folders can coexist in one project - Fabric Git Integration only processes
definition.pbir— other.pbirfiles are ignored but can coexist
External Edits with Desktop Open
Desktop picks up a saved external edit only with a preview switched on: File > Options and settings > Options > Preview features > Detect and reload external PBIP changes, then restart, on the August 2026 release or later. Without it, close and reopen the project. Per Learn, read 2026-10-12:
- Save in Desktop first: it writes nothing to the project files until you do.
- Edit the file externally and save it there.
- Take the Apply external changes banner. With unsaved changes in Desktop it warns that they will be overwritten; Cancel keeps them, leaving the external edit on disk, unapplied.
- A reload replaces the whole report, model or both, never one file or
visual. It resets filters and some UI, and does not reload
cache.abf. - During the preview,
definition.pbir,report.json,mobileState.jsonandsemanticModelDiagramLayout.jsoncannot be edited outside Desktop. - With
.pbi/unappliedChanges.jsonpresent, apply those pending changes before editing model expressions externally, or Desktop discards the external expression edits when it applies them. - A script reloads through the Desktop Bridge, also a preview: a
local JSON-RPC named pipe,
pbi-desktop-bridge-{processId}, that runs one operation at a time and errors on a second. ReadhasUnsavedChangesfromapplication.state.get/v1before callingfile.reload/v1, whosereloadModelDefinition: falsereloads the report alone. Thepowerbi-desktopCLI wraps both asstatusandreload. The bridge is on by default (Options > Security > Desktop Bridge), and an admin can turn it off with the registry policyDesktopNamedPipeBridge(Learn, read 2026-10-12).
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 | The detection preview is off, the external file is unsaved, or the Apply external changes banner was not taken | Switch the preview on and take the banner; with it off, close and reopen the project. See External Edits with Desktop Open |
| 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
See also
pbir-report-workflow— report creation workflow, with the pbir CLI reference and page JSON structure in its referencesfabric-tmdl— TMDL authoring rules
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

