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:

Mismatched encoding when reading or writing these files causes parse failures.

Extracting a PBIX

import zipfile
from pathlib import Path

pbix_path = Path("MyReport.pbix")
output_dir = Path("MyReport_extracted")

with zipfile.ZipFile(pbix_path, "r") as z:
    # Safety: validate no entries escape the target directory (Zip Slip protection)
    resolved_output = output_dir.resolve()
    for member in z.infolist():
        member_path = (output_dir / member.filename).resolve()
        if not member_path.is_relative_to(resolved_output):
            raise ValueError(f"Zip entry escapes target: {member.filename}")
    z.extractall(output_dir)

# Detect PBIX type
is_thick = (output_dir / "DataModel").exists()
is_legacy = (output_dir / "Report" / "Layout").exists()
is_modern = (output_dir / "Report" / "definition" / "report.json").exists()

# Quick extraction via CLI
unzip MyReport.pbix -d MyReport_extracted/

# Check contents without extracting
unzip -l MyReport.pbix

Assembling a PBIP from an Extracted Thin PBIX

For thin PBIX files (no DataModel), a PBIP can be assembled from the extracted contents:

1. Extract the PBIX ZIP 2. Create the PBIP folder structure:

   MyReport/
   +-- MyReport.pbip
   +-- MyReport.Report/
   |   +-- definition.pbir
   |   +-- definition/           # Copy from extracted Report/definition/
   |   +-- StaticResources/      # Copy from extracted Report/StaticResources/
   |   +-- .platform

3. Create MyReport.pbip:

   {
     "version": "1.0",
     "artifacts": [
       { "report": { "path": "MyReport.Report" } }
     ],
     "settings": { "enableAutoRecovery": true }
   }

4. Create definition.pbir with byConnection derived from the extracted Connections file. The Connections file contains a JSON array with connection string details:

   {
     "$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"
       }
     }
   }

5. Create .platform with a new logicalId GUID and "type": "Report"

This only works for thin PBIX with modern PBIR format. Thick PBIX files require the semantic model to be handled separately (e.g. exported via XMLA/TOM, or deployed from a model.bim or TMDL source). Legacy PBIX report content (Report/Layout) is not compatible with the PBIR definition/ structure.

PBIX vs PBIP

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
|   |   +-- pages/
|   |   |   +-- pages.json
|   |   |   +-- <page-slug>/                 # See "Page folder naming" below
|   |   |   |   +-- page.json
|   |   |   |   +-- visuals/...
|   +-- report.json                          # PBIR-Legacy format (legacy alt to definition/)
|   +-- mobileState.json                     # Mobile layout (no external edit)
|   +-- semanticModelDiagramLayout.json      # Diagram positions (table renames)
|   +-- CustomVisuals/                       # Private custom visual metadata
|   +-- StaticResources/
|   |   +-- SharedResources/                 # Base themes, shared resources
|   |   |   +-- BaseThemes/<name>.json       # Resolution path: <report>/StaticResources/SharedResources/<item.path>
|   |   +-- RegisteredResources/             # Custom themes, images, .pbiviz files
|   +-- DAXQueries/                          # .dax files from report DAX query view
|   +-- .platform                            # Fabric identity

Page folder naming

Power BI Desktop uses opaque 20-character hex slugs for new page, visual, bookmark, and filter folders by default (e.g. 847663d71e27e0840063). Per Microsoft docs, these can be renamed to friendly names but the replacement must satisfy:

• Regex: ^[\w-]+$ — word characters (letters, digits, underscore) or hyphen only.
• No spaces, no dots, no other punctuation. Names outside this set are silently ignored by Power BI Desktop and the page/visual vanishes from the loaded report. This is the hardest bug class to diagnose because there is no error dialog.
• Folder name and `name` field must match exactly (case-sensitive). The folder may be bare (<slug>/) or suffixed (<slug>.Page/) — both forms are valid on disk. pbir-cli uses the .Page suffix in its CLI path syntax; current Desktop saves omit the suffix.
• `pages.json.pageOrder` entries must reference the slug, not the display name. activePageName must be one of the entries in pageOrder.
• Restart Desktop after external rename. PBI Desktop does not detect file changes while open.

If you rename a page from a hex slug to a friendly name, you must also update every reference to the old slug in visual JSONs, filter configs, bookmarks, sparkline metadata, and DAX queries — see references/rename-cascade.md.

SharedResources path resolution

Items listed in resourcePackages[] are resolved relative to:

<Report>/StaticResources/<package_type>/<item.path>

For a SharedResources package with an item { "path": "BaseThemes/Fluent2-CY26SU03.json" }, Power BI Desktop looks for:

<Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json

Missing resource files are a common blocking error. If report.json declares themeCollection.baseTheme.type = "SharedResources" and points at a resource that doesn't exist on disk, the report will not open. validate_pbip.py checks this explicitly.

What to Read for Common Tasks

Forking a PBIP Project

1. Copy the project folder -- duplicate the entire root folder with a new name. 2. Rename artifact folders -- rename .Report/ and .SemanticModel/ subfolders to match the new project name. 3. Rename and update `.pbip` -- rename the .pbip file and update artifacts[].report.path to point to the renamed .Report folder. 4. Update `.pbir` -- if the report uses byPath, update the path to point to the renamed .SemanticModel folder. 5. Update `.platform` files -- set displayName to the new project name in each .platform file. Regenerate logicalId (new GUID) if deploying as a separate Fabric item.

Verification

Two tools for validation, used together:

1. `scripts/validate_pbip.py` — project-level validator for cross-cutting concerns: .pbip root file, .platform identity, semantic model format (TMDL vs TMSL), datasetReference resolution, theme resource resolution on disk, orphan page folders, and the silent-ignore page name regex rule (page names outside ^[\w-]+$ are silently ignored by Power BI Desktop). Delegates deep .Report schema validation to pbir validate if it is on PATH.

   python3 scripts/validate_pbip.py <path-to-.pbip-or-project>           # validate
   python3 scripts/validate_pbip.py <path> --fix                         # scaffold .gitignore
   python3 scripts/validate_pbip.py <path> --json                        # machine-readable
   python3 scripts/validate_pbip.py <path> --no-pbir-cli                 # skip delegation

Exit codes: 0 clean, 1 warnings only, 2 errors, 3 usage error.

2. `pbir validate <Report.Report>` (from the pbir-cli skill) — canonical JSON schema + PBIR structure validator for the .Report folder. Covers JSON syntax, schema compliance, required fields, and optional --qa / --fields / --strict checks.

3. `pbip-validator` agent — use for interactive, LLM-driven checking of orphaned references after renames, when you need reasoning over the whole project rather than a deterministic report.

Known gotcha with `pbir validate`: if the project's .pbi/localSettings.json uses a schema version newer than the one bundled in pbir-cli, pbir validate returns SCHEMA_UNSUPPORTED. Pass --allow-download-schemas to let it fetch the missing schema on demand, or ignore .pbi/ files (they are per-user runtime state and not part of the committed definition).

After any rename or fork operation, verify no old references remain.

# Search for old name across all project files
grep -r "Old Name" "Project.Report/" "Project.SemanticModel/" --include="*.json" --include="*.tmdl" --include="*.dax"

# Search with word boundaries to avoid partial matches
grep -rP "\bOld Name\b" "Project.Report/" "Project.SemanticModel/"

# Look for old name in single-quoted DAX references
grep -r "'Old Name'" --include="*.tmdl" --include="*.dax"

Common missed locations: 1. SparklineData metadata -- compact string format outside standard JSON structure 2. Conditional formatting expressions -- Entity refs nested in Conditional.Cases 3. Filter config -- page-level and visual-level filters in filterConfig sections 4. Sort definitions -- sortDefinition blocks in visual JSON 5. DAX queries in Report folder -- the second DAX query location 6. Culture file linguisticMetadata -- ConceptualEntity and ConceptualProperty inside embedded JSON

Related Skills

Within this plugin:

• `tmdl` -- TMDL syntax, authoring, and editing rules for direct .tmdl file editing
• `pbir-format` -- PBIR JSON format, visual.json, theme, filters, report extensions

Other plugins:

• `semantic-models` plugin -- tooling and workflows for semantic model development (naming conventions, model quality). Use for working with the actual model content, not just its file format.
• `pbi-desktop` plugin -- connecting to Power BI Desktop's local Analysis Services instance via TOM/ADOMD.NET
• `tabular-editor` plugin -- Tabular Editor CLI, C# scripting, BPA rules, documentation search

References

Project structure:

• `references/pbip-file-types.md` -- Entry point file structures (.pbip, .pbir, .pbism, .platform), .pbi/ subfolder, DAXQueries/, TMDLScripts/, model.bim, .gitignore, version properties, JSON examples
• `references/copilot-folder.md` -- Copilot/ folder structure (AI instructions, verified answers, schema, example prompts)

Rename operations:

• `references/rename-cascade.md` -- Detailed before/after examples for each rename cascade location (TMDL + report files)

Fetching Docs: To retrieve current PBIP reference docs, use microsoft_docs_search + microsoft_docs_fetch (MCP) if available, otherwise mslearn search + mslearn fetch (CLI). Search based on the user's request and run multiple searches as needed to ensure sufficient context before proceeding.

External references:

• PBIP overview (Microsoft Learn)
• Semantic model folder (Microsoft Learn)
• Report folder (Microsoft Learn)

Copilot Folder Reference

Archival note: This documentation was removed from the official Microsoft Learn page

(projects-dataset.md)

on 2026-03-25 in commit `facaed5`

("Remove Copilot tooling details from projects dataset").

The folder structure remains present in PBIP projects saved with Copilot tooling enabled.

Content below is sourced from the pre-removal version of the docs

(`f806de7`).

The Copilot/ folder lives inside the .SemanticModel/ folder and contains all Copilot tooling metadata and settings configured for the semantic model via Prep data for AI.

Folder Structure

<Name>.SemanticModel/
  Copilot/
  ├── Instructions/
  │   ├── instructions.md
  │   └── version.json
  ├── VerifiedAnswers/
  │   ├── definitions/
  │   │   └── [verified-answer-ID]/
  │   │       ├── definition.json
  │   │       ├── filters.json
  │   │       └── visualSource.json
  │   └── version.json
  ├── schema.json
  ├── examplePrompts.json
  ├── settings.json
  └── version.json

File Descriptions

Instructions/instructions.md

Contains the AI instructions configured for the semantic model, stored as a markdown file. These provide Copilot with business context, terminology, and analytical priorities.

AI instructions:

• Are saved at the semantic model level (not report level)
• Are limited to 10,000 characters
• Are unstructured guidance that the LLM interprets (no guarantee of exact adherence)
• Affect Copilot capabilities but do not extend to general conversations

Instructions/version.json

Tracks the version of the Instructions file structure. Updated whenever the file representation changes.

schema.json

Contains the AI data schema selection and field synonyms configured for the semantic model. Controls which tables and columns are visible to Copilot and provides alternative names for fields.

For more information, see the schema.json schema document.

VerifiedAnswers/ folder

Contains configured Verified answers for the semantic model. Each verified answer is stored in its own subfolder within definitions/ using PBIR format:

VerifiedAnswers/version.json

Tracks the version of the VerifiedAnswers file structure.

settings.json

Contains top-level Copilot tooling settings.

For more information, see the settings.json schema document.

examplePrompts.json

Contains example prompts set up for the semantic model, used by Copilot Zero Prompt experiences (the suggested questions shown when a user first opens Copilot).

For more information, see the examplePrompts.json schema document.

version.json (root)

Tracks the version of the overall Copilot feature file structure. The version is updated whenever the file representation changes (e.g. when a new file is added to the folder).

For more information, see the version.json schema document.

Authoring and Consumption

• Authoring of AI instructions, AI data schema, and verified answers is available in

both Power BI Desktop and the Power BI service via the Prep data for AI button on the Home ribbon.

• Consumption of these features is available everywhere that Copilot in Power BI exists.
• Power BI Desktop supports Prep data for AI with Import, DirectQuery, and Composite (local)

connection types only.

• All model types can use Prep data for AI within the Power BI service.

Git and Deployment Notes

• AI instructions and AI data schemas also save to the LSDL (Linguistic Schema Definition

Language) and can be edited through that path as well.

• When making LSDL or Copilot tooling edits through Git or deployment pipelines, a model

refresh in the Power BI service is required to sync changes after deployment:

• Import models: refresh required after deployment
• DirectQuery models: refresh required, but only once per day
• Direct Lake models: refresh required, but only once per day
• The Copilot/ folder is committed to Git by default. Include or exclude individual files

as needed via .gitignore.

Marking a Model as Approved for Copilot

After configuring Copilot tooling, mark the semantic model as Approved for Copilot in the Power BI service (Settings > Approved for Copilot). This removes friction treatment from the standalone Copilot experience for that model and its associated reports.

PBIP File Types Reference

Structure and purpose of each entry-point and project-level file in a Power BI Project (PBIP).

Verify against the current Microsoft docs for the latest schema versions:

- PBIP overview

- PBIP semantic model folder

- PBIP report folder

.pbip (Project Entry Point)

The root file that references the report folder. One per project:

{
  "version": "1.0",
  "artifacts": [
    {
      "report": {
        "path": "My Report.Report"
      }
    }
  ],
  "settings": {
    "enableAutoRecovery": true
  }
}

When forking a project, update the path to match the renamed .Report/ folder.

This file is optional -- open definition.pbir directly to load the report without a .pbip wrapper.

Schema: pbipProperties

.platform (Item Metadata)

Found inside each .Report/ and .SemanticModel/ folder. Contains the item's display name, type, and a logicalId used by Fabric for identity:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/platformProperties/2.0.0/schema.json",
  "metadata": {
    "type": "SemanticModel",
    "displayName": "SpaceParts OTC Full"
  },
  "config": {
    "version": "2.0",
    "logicalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Critical rules:

• logicalId is the unique identity of the item in Fabric. Never change it on an existing item -- this would break the connection to the deployed item.
• When forking (creating a copy), logicalId must be changed to a new GUID to avoid conflicts with the original item.
• displayName is what appears in the Fabric workspace. Update it when forking to distinguish the copy.
• type values: SemanticModel, Report

definition.pbir (Report Entry Point)

Found inside the .Report/ folder. References the semantic model the report is connected to.

byPath (Local Reference)

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../My Model.SemanticModel"
    }
  }
}

The path is relative to the .Report/ folder. ../ navigates up to the project root.

byConnection (Remote Model) — Current Form

For new reports connected to a remote semantic model, use the connectionString-only form. This is the current recommended format:

{
  "$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"
    }
  }
}

When deploying via Fabric REST API, use the semanticmodelid form:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

byConnection Legacy Form

Older reports may use the verbose six-property form. Do not use this for new reports — prefer the connectionString-only form above:

{
  "$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",
      "pbiServiceModelId": null,
      "pbiModelVirtualServerName": "sobe_wowvirtualserver",
      "pbiModelDatabaseName": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "EntityDataSource",
      "connectionType": "pbiServiceXmlaStyleLive"
    }
  }
}

Multiple .pbir Files

Fabric Git Integration only processes definition.pbir; other .pbir files are ignored but can coexist (e.g. definition-liveConnect.pbir for forcing live connect mode).

version Property

Schema: definitionProperties

definition.pbism (Semantic Model Entry Point)

Found inside the .SemanticModel/ folder:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/semanticModel/definitionProperties/1.0.0/schema.json",
  "version": "4.2",
  "settings": {}
}

version Property

Schema: definitionProperties

.pbi/ Subfolder

Per-item subfolder containing local settings, caches, and editor state. Present in both .Report/ and .SemanticModel/ folders.

localSettings.json

User/machine-specific settings, gitignored by default. Each user gets their own local state (e.g. last-opened page, query editor state). Present in both report and semantic model folders.

Schema: localSettings

editorSettings.json

Editor settings saved with the model definition, committed to Git. Shared across all users of the project.

Schema: editorSettings

cache.abf

Analysis Services Backup file, local data cache, gitignored. PBI Desktop can open the project without it -- the model loads without data. If present, data is loaded and the model definition is overwritten from project files.

unappliedChanges.json

Pending Power Query changes from the Transform Data editor. Committed to Git by default (can exclude).

WARNING: If this file exists and changes are applied, it overwrites queries in model metadata.

Schema: unappliedChanges

daxQueries.json

DAX query view editor settings (tab order, default tab).

tmdlscripts.json

TMDL view script tab settings.

DAXQueries/ Folder

Contains .dax files, one per DAX query view tab, named [Tab name].dax. Exists in both .SemanticModel/ and .Report/ folders. DAX queries are saved when saving from PBI Desktop. Settings stored in .pbi/daxQueries.json.

TMDLScripts/ Folder

Contains .tmdl files, one per TMDL view script tab, named [Tab name].tmdl. Only in .SemanticModel/ folder. Settings stored in .pbi/tmdlscripts.json.

model.bim (TMSL Legacy)

Present only when saving in TMSL format (mutually exclusive with definition/ folder). Single large JSON file containing the complete model definition. TMDL is the recommended format for source control (better diffs, per-table files).

.gitignore

Default content auto-generated by PBI Desktop:

**/.pbi/localSettings.json
**/.pbi/cache.abf

Auto-generated only if one does not already exist in the save folder or parent Git repo.

Other Report Folder Files

Brief overview of remaining files in the .Report/ and .SemanticModel/ folders. For PBIR report definition details, see the pbir-format skill.

CustomVisuals/ details: Contains metadata for private custom visuals (.pbiviz packages loaded by the user). Organizational store and AppSource visuals are NOT stored here -- they load automatically. Each custom visual gets a subfolder named with its GUID (e.g., PBI_CV_a1b2c3d4-...).

Rename Cascade Reference

Detailed before/after examples for every location that must be updated when renaming tables, measures, or columns in a PBIP project.

Table Rename Examples

The examples below show renaming a table from Customers to Customer.

TMDL File Name

# Before
tables/Customers.tmdl

# After
tables/Customer.tmdl

Table Declaration

// Before
table Customers
	lineageTag: abc-123

// After
table Customer
	lineageTag: abc-123

Quoting rules: Only quote names that contain spaces or special characters. Simple names like Customer are unquoted. Names with spaces use single quotes: 'Invoice Document Type'. Underscore-prefixed names without spaces are unquoted: _Measures.

Partition Name

The partition name typically matches the table name:

// Before
partition Customers = m
	mode: import
	source = ...

// After
partition Customer = m
	mode: import
	source = ...

Model.tmdl Ref Entries

// Before
ref table Customers

// After
ref table Customer

Also update `PBI_QueryOrder` annotation if it contains the table name:

// Before
annotation PBI_QueryOrder = ["Brand","Customers","Product"]

// After
annotation PBI_QueryOrder = ["Brand","Customer","Product"]

Relationships.tmdl

Both fromColumn and toColumn use the format TableName.'Column Name':

// Before
relationship abc-123
	fromColumn: Invoices.'Customer Key'
	toColumn: Customers.'Customer Key'

// After
relationship abc-123
	fromColumn: Invoices.'Customer Key'
	toColumn: Customer.'Customer Key'

DAX Expressions Across All TMDL Files

Table references in DAX appear in single quotes when the name contains spaces, otherwise unquoted. After a rename, update every occurrence across all .tmdl files:

// Before (table name with no spaces - appears in single quotes in DAX anyway)
CALCULATE (
    [Sales Amount],
    Customers[Account Type] = "Enterprise"
)

// After
CALCULATE (
    [Sales Amount],
    Customer[Account Type] = "Enterprise"
)

Edge case — unquoted vs. quoted in DAX:

DAX always allows single-quoting table names, even simple ones. Both forms are valid:

// Both valid DAX:
Customer[Column]
'Customer'[Column]

When doing bulk find-and-replace, search for both patterns:

• Customers[ (unquoted)
• 'Customers'[ (quoted)
• 'Customers' (standalone reference in CALCULATE filters)

Visual JSON Entity References

SourceRef.Entity

// Before
{
  "Expression": {
    "SourceRef": {
      "Entity": "Customers"
    }
  }
}

// After
{
  "Expression": {
    "SourceRef": {
      "Entity": "Customer"
    }
  }
}

queryRef

The queryRef format is TableName.ColumnOrMeasureName:

// Before
"queryRef": "Customers.Account Type"

// After
"queryRef": "Customer.Account Type"

nativeQueryRef

The nativeQueryRef contains only the column/measure name (no table prefix). It does not change during table renames — only during column/measure renames.

Filter Config Entity References

Filter configurations in visual and page JSON files contain From[].Entity references:

// Before (in visual.json or page.json filterConfig)
"From": [
  { "Name": "p", "Entity": "Customers", "Type": 0 }
]

// After
"From": [
  { "Name": "p", "Entity": "Customer", "Type": 0 }
]

Conditional Formatting Entity References

Conditional formatting rules embed SourceRef.Entity inside expression trees:

// Before (nested in objects.*.properties.*.expr.Conditional.Cases)
"Measure": {
  "Expression": {
    "SourceRef": { "Entity": "Customers" }
  },
  "Property": "Some Measure"
}

// After
"Measure": {
  "Expression": {
    "SourceRef": { "Entity": "Customer" }
  },
  "Property": "Some Measure"
}

Bookmark Filter Snapshots

Bookmark JSON files (in definition/bookmarks/) contain filter state snapshots. Each filter entry has two distinct Entity references that must both be updated:

1. filter.From[].Entity — the aliased filter predicate 2. expression.Column.Expression.SourceRef.Entity — the top-level expression field

// Before (in .bookmark.json explorationState.filters.byExpr[])
{
  "expression": {
    "Column": {
      "Expression": {"SourceRef": {"Entity": "Customers"}},  // ← must update
      "Property": "Account Name"
    }
  },
  "filter": {
    "Version": 2,
    "From": [{"Name": "c", "Entity": "Customers", "Type": 0}],  // ← must update
    "Where": [...]
  }
}

// After (renaming Customers → Customer)
{
  "expression": {
    "Column": {
      "Expression": {"SourceRef": {"Entity": "Customer"}},
      "Property": "Account Name"
    }
  },
  "filter": {
    "Version": 2,
    "From": [{"Name": "c", "Entity": "Customer", "Type": 0}],
    "Where": [...]
  }
}

Bookmark Highlight Blocks

Bookmarks may also contain highlight blocks with dataMap keys in "Table.Column" format that must be updated on table or column renames:

// Before (in .bookmark.json explorationState.sections.<page>.visualContainers.<visual>)
{
  "highlight": {
    "dataMap": {
      "Customers.Key Account Name": {...},   // ← key string must update
      "Sales.Revenue": {...}
    },
    "filterExpressionMetadata": {
      "expressions": [{
        "Column": {
          "Expression": {"SourceRef": {"Entity": "Customers"}},  // ← must update
          "Property": "Key Account Name"
        }
      }]
    }
  }
}

// After (renaming Customers → Customer)
{
  "highlight": {
    "dataMap": {
      "Customer.Key Account Name": {...},
      "Sales.Revenue": {...}
    },
    "filterExpressionMetadata": {
      "expressions": [{
        "Column": {
          "Expression": {"SourceRef": {"Entity": "Customer"}},
          "Property": "Key Account Name"
        }
      }]
    }
  }
}

Both dataMap key strings AND filterExpressionMetadata.expressions[].Column.Expression.SourceRef.Entity must be updated.

SparklineData Metadata Selectors

SparklineData metadata selectors embed table names in a compact string format:

// Before
{
  "selector": {
    "metadata": "SparklineData(Customers.Customer Count_[Date.Date Hierarchy.Date])"
  }
}

// After
{
  "selector": {
    "metadata": "SparklineData(Customer.Customer Count_[Date.Date Hierarchy.Date])"
  }
}

Format breakdown:

SparklineData(<MeasureTable>.<MeasureName>_[<GroupingTable>.<Hierarchy>.<Level>])

SparklineData also appears in query projections as structured JSON:

// Before
{
  "field": {
    "SparklineData": {
      "Measure": {
        "Measure": {
          "Expression": {
            "SourceRef": { "Entity": "Customers" }
          },
          "Property": "Customer Count"
        }
      },
      "Groupings": [
        {
          "HierarchyLevel": {
            "Expression": {
              "Hierarchy": {
                "Expression": {
                  "SourceRef": { "Entity": "Date" }
                },
                "Hierarchy": "Date Hierarchy"
              }
            },
            "Level": "Date"
          }
        }
      ]
    }
  }
}

Both the Entity in the structured JSON and the table name in the metadata selector string must be updated.

SemanticModelDiagramLayout.json

// Before
{
  "nodeIndex": "Customers",
  "size": { "height": 300, "width": 234 }
}

// After
{
  "nodeIndex": "Customer",
  "size": { "height": 300, "width": 234 }
}

ReportExtensions.json

// Before
{
  "entities": [
    {
      "name": "Customers",
      "measures": [
        {
          "name": "Customer Color",
          "expression": "IF ( [Customer Count] > 100, \"blue\", \"gray\" )",
          "references": {
            "measures": [
              { "entity": "Customers", "name": "Customer Count" }
            ]
          }
        }
      ]
    }
  ]
}

// After
{
  "entities": [
    {
      "name": "Customer",
      "measures": [
        {
          "name": "Customer Color",
          "expression": "IF ( [Customer Count] > 100, \"blue\", \"gray\" )",
          "references": {
            "measures": [
              { "entity": "Customer", "name": "Customer Count" }
            ]
          }
        }
      ]
    }
  ]
}

Note: The entity field in references.measures entries must also be updated — not just the top-level name.

Culture Files

The linguisticMetadata JSON inside culture .tmdl files contains ConceptualEntity and ConceptualProperty references:

// Before (inside cultures/en-US.tmdl)
{
  "customers.account_type": {
    "Definition": {
      "Binding": {
        "ConceptualEntity": "Customers",
        "ConceptualProperty": "Account Type"
      }
    }
  }
}

// After
{
  "customers.account_type": {
    "Definition": {
      "Binding": {
        "ConceptualEntity": "Customer",
        "ConceptualProperty": "Account Type"
      }
    }
  }
}

Note: The dictionary key (customers.account_type) is an auto-generated lookup key. It does not need to match the actual table name, but the ConceptualEntity value does.

DAX Query Files

Check both locations:

<Name>.SemanticModel/DAXQueries/*.dax
<Name>.Report/DAXQueries/*.dax

// Before
EVALUATE TOPN(100, Customers)

// After
EVALUATE TOPN(100, Customer)

Measure Rename Examples

Renaming a measure from # Customers to # Active Customers.

TMDL Measure Declaration

// Before
measure '# Customers' =
		COUNTROWS ( Customer )
	formatString: #,##0
	displayFolder: Measures
	lineageTag: abc-123

// After
measure '# Active Customers' =
		COUNTROWS ( Customer )
	formatString: #,##0
	displayFolder: Measures
	lineageTag: abc-123

DAX References in Other Measures

// Before
measure '% Customer Growth' =
		DIVIDE ( [# Customers], [# Customers PY] )

// After
measure '% Customer Growth' =
		DIVIDE ( [# Active Customers], [# Customers PY] )

Visual JSON Property and queryRef

// Before
{
  "Measure": {
    "Expression": { "SourceRef": { "Entity": "Customer" } },
    "Property": "# Customers"
  }
},
"queryRef": "Customer.# Customers",
"nativeQueryRef": "# Customers"

// After
{
  "Measure": {
    "Expression": { "SourceRef": { "Entity": "Customer" } },
    "Property": "# Active Customers"
  }
},
"queryRef": "Customer.# Active Customers",
"nativeQueryRef": "# Active Customers"

ReportExtensions.json

// Before
{ "entity": "Customer", "name": "# Customers" }

// After
{ "entity": "Customer", "name": "# Active Customers" }

Sort Definitions

sortDefinition blocks inside visual.json contain SourceRef.Entity references that must be updated during table or column renames. These are commonly missed because they live outside the queryState projections.

// Before (in visual.json query.sortDefinition)
"sortDefinition": {
  "sort": [{
    "field": {
      "Measure": {
        "Expression": {
          "SourceRef": {"Entity": "Customers"}
        },
        "Property": "Revenue"
      }
    },
    "direction": "Descending"
  }],
  "isDefaultSort": true
}

// After
"sortDefinition": {
  "sort": [{
    "field": {
      "Measure": {
        "Expression": {
          "SourceRef": {"Entity": "Customer"}
        },
        "Property": "Revenue"
      }
    },
    "direction": "Descending"
  }],
  "isDefaultSort": true
}

Note: sortDefinition does not use queryRef — only SourceRef.Entity and Property. Search for "sortDefinition" across all visual.json files to find every instance.

Edge Cases

Names with Special Characters

DAX measure names with special characters (parentheses, percentage signs, delta symbols) are common:

Orders Target vs. Net Orders (Δ)
Sales Target MTD vs. Actuals (%)
OTD % (Value; PY REPT)

When searching for these in JSON files, remember that some characters may be escaped or may need regex escaping in grep patterns.

Unquoted Names in TMDL

Simple names (no spaces, no special characters) are unquoted in TMDL declarations:

table Product          // unquoted - no spaces
table _Measures        // unquoted - underscore prefix, no spaces
table 'Budget Rate'    // quoted - contains space
table '1) Selected Metric'  // quoted - starts with digit, contains special chars

Multiple Tables with Similar Names

When renaming Order in a model that also has Orders and Order Status, use word-boundary-aware search to avoid false matches:

# Use word boundaries to match exact table name
grep -rP "\bOrder\b" --include="*.tmdl" --include="*.json"

# Or search for the specific TMDL/JSON patterns
grep -r "table Order$" --include="*.tmdl"
grep -r '"Entity": "Order"' --include="*.json"

Bulk Rename Strategy

For large-scale renames (e.g., applying SQLBI naming conventions to all tables):

1. Build a rename mapping (old name → new name) 2. Sort by longest name first to avoid substring collisions 3. Process one table at a time, running verification after each 4. Use a script for consistency to avoid manual errors