agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/skills/power-bi/pbip-project-structure/SKILL.md

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.

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
  1. Very specific:

    When forking a project, logicalId MUST be regenerated to a new GUID

    line 81
  2. Very specific:

    Update .pbir → datasetReference.byPath.path (if byPath)

    line 179
  3. Very specific:

    Update each .platform (Report and SemanticModel separately) → set the appropriate displayName and regenerate a NEW unique logicalId per …

    line 180
  4. Distinctive:

    Keep the root path short — 260-char Windows path limit.

    line 209

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

FilePurpose
.pbipProject entry point. Optional — definition.pbir can be opened directly
.pbirReport entry point. Points at semantic model via byPath or byConnection
.pbismSemantic model entry point. version: "4.2" for TMDL
.platformFabric identity per item: displayName, type, logicalId
version.jsonInside 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": {}
}
versionSupported Format
1.0TMSL 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.

AspectPBIXPBIP
FormatSingle binary ZIPFolder of text files
Source controlNot diff-friendlyGit-ready
External editingNot supportedVS Code (Desktop has a built-in entry point that opens the project directly), pbir CLI, scripts
Cached dataEmbeddedcache.abf gitignored
ConversionFile → Save As → PBIP in DesktopFile → 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 FileEncoding
Version, Settings, Metadata, Report/LayoutUTF-16LE
Connections, Report/definition/*UTF-8
[Content_Types].xmlUTF-8 with BOM
DataModel, SecurityBindingsBinary
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.

LocationWhat to Update
TMDL table/measure/column declarationThe <type> Name line
TMDL partition nameMatches table name
model.tmdlref table Name + PBI_QueryOrder annotation
relationships.tmdlfromColumn: / toColumn: table prefix
All DAX expressionsBoth Table[ and 'Table'[ forms
visual.json query projectionsSourceRef.Entity, queryRef
visual.json filter/sort/CF blocksNested SourceRef.Entity, From[].Entity
page.json filterConfigFrom[].Entity
Bookmark JSONsfilter.From[].Entity, expression.*.SourceRef.Entity, highlight.dataMap keys
SparklineData metadataCompact string SparklineData(Table.Measure_[...])
reportExtensions.jsonTop-level entities[].name AND nested references.measures[].entity
Culture .tmdl linguistic metadataConceptualEntity, ConceptualProperty
semanticModelDiagramLayout.jsonnodeIndex
DAX query filesBoth .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

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:

  1. Save in Desktop first: it writes nothing to the project files until you do.
  2. Edit the file externally and save it there.
  3. 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.json and semanticModelDiagramLayout.json cannot be edited outside Desktop.
  • With .pbi/unappliedChanges.json present, 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. Read hasUnsavedChanges from application.state.get/v1 before calling file.reload/v1, whose reloadModelDefinition: false reloads the report alone. The powerbi-desktop CLI wraps both as status and reload. The bridge is on by default (Options > Security > Desktop Bridge), and an admin can turn it off with the registry policy DesktopNamedPipeBridge (Learn, read 2026-10-12).

Gotchas

IssueCauseFix
Parse error on openFile saved with UTF-8 BOMRe-save as UTF-8 without BOM
260-char path error on Git cloneDeep GUID folder nestingShorten root path; rename GUID folders
PBI Desktop ignores external editsThe detection preview is off, the external file is unsaved, or the Apply external changes banner was not takenSwitch 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 renameMissed cascade locationGrep for old name across .json, .tmdl, .dax (both DAXQueries folders)
Empty reportExtensions.json crashes Desktop"entities": [] is invalidDelete the file instead of leaving empty
Forked project shows as same Fabric itemlogicalId not regeneratedNew GUID per .platform on fork
Thick PBIX cannot be converted to PBIP via scriptDataModel binary is opaqueUse File → Save As in PBI Desktop
Merge conflicts in diagramLayout.jsonAuto-generated per userTreat as binary or add to .gitignore

Reference

See also

  • pbir-report-workflow — report creation workflow, with the pbir CLI reference and page JSON structure in its references
  • fabric-tmdl — TMDL authoring rules

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.