Power BI Desktop project semantic model folder

Important

Power BI Desktop projects is currently in preview.

This article describes the files and subfolders in a Microsoft Power BI Desktop project's Semantic Model folder. The files and subfolders here represent a Power BI semantic model. Depending on your project, the semantic model folder can include:

• .pbi\
  • localSettings.json
  • editorSettings.json
  • cache.abf
  • unappliedChanges.json
• definition.pbism¹
• model.bim²
• definition\ folder³
• diagramLayout.json
• .platform

1 - This file is required.
2 - This file is required when saving using TMSL format.
3 - This file is required when saving using TMDL format.

Not every project semantic model folder includes all of the files and subfolders described here.

Semantic Model files

.pbi\localSettings.json

Contains semantic model settings that apply only for the current user and computer. It should be included in gitIgnore or other source control exclusions. By default, Git ignores this file.

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

.pbi\editorSettings.json

Contains semantic model editor settings saved as part of the semantic model definition for use across users and environments.

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

.pbi\cache.abf

An Analysis Services Backup (ABF) file containing a local cached copy of the model and data when it was last edited. It should be included in gitIgnore or other source control exclusions. By default, Git ignores this file.

Power BI Desktop can open a project without a cache.abf file. In that case, it opens the report connected to a model with its entire definition but without data. If a cache.abf exists, Power BI Desktop loads the data and overwrites the model definition with the content in model.bim.

.pbi\unappliedChanges.json

Power BI Desktop allows you to save changes made in the Transform Data editor (Power Query) without first applying those changes to the data model.

When you select Apply later, the unapplied changes are saved into the unappliedChanges.json file. When pending changes are in the unappliedChanges file, Power BI Desktop prompts you to apply or discard those pending changes:

If you select Apply changes, Power BI Desktop overwrites the queries in model.bim with the queries from unappliedChanges.json. If you edited queries in model.bim outside of Power BI Desktop and there's a previous unappliedChanges.json file, your changes are lost and replaced by the queries in unappliedChanges.json when those changes are applied.

The unappliedChanges.json file is automatically incorporated into the semantic model definition and saved in Git by default. This allows you to commit your ongoing work to the development branch, serving as a backup and making it accessible to other team members. However, you can exclude this file from Git's tracking, preventing unfinished query work from affecting other developers.

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

definition.pbism

Contains the overall definition of a semantic model and core settings.

For more information, see the definition.pbism schema document.

model.bim

This file is only available if the Power BI project is saved using the TMSL format. It contains a Tabular Model Scripting Language (TMSL) Database object definition of the project model.

definition\ folder

This file is only available if the Power BI project is saved using the TMDL format. It replaces the model.bim file.

This file contains a Tabular Model Definition Language (TMDL) Database object definition of the project model.

diagramLayout.json

Contains diagram metadata that defines the structure of the semantic model associated with the report. During PREVIEW, this file doesn't support external editing.

.platform

Fabric platform file that holds properties vital for establishing and maintaining the connection between Fabric items and Git.

To learn more, see Git integration automatically generated system files.

TMDL format

With the objective of providing a better source control and co-development experience, you can save your Power BI Project files (PBIP) using Tabular Model Definition Language (TMDL) as the semantic model file format.

Unlike Tabular Model Scripting Language (TMSL), TMDL has been designed from the ground up to be human-friendly, facilitating not only readability but also easy editing in any text editor. This represents a substantial enhancement for source control and collaborative development experiences.

Instead of a big JSON file like Tabular Model Scripting Language (TMSL), TMDL has a folder structure with separate files for each table, perspective, role, and culture. This makes it easier to work with others, and to understand the semantic model structure by just looking at the folder and files. Ultimately, this leads to a great source control and co-development experience when dealing with git diff’s and merge conflicts.

Learn more about TMDL here.

Enable TMDL format Preview feature

Saving as a Power BI Project using TMDL is currently in preview. Before using it, you must first enable it in Preview features:

Go to File > Options and settings > Options > Preview features and check the box next to Store semantic model using TMDL format.

Save as a project using TMDL

With the TMDL Preview feature enabled, when you save a project, your semantic model is saved as a TMDL folder named \definition inside of semantic model folder:

Learn more about the TMDL folder structure.

Convert existing PBIP to TMDL

If you already have a PBIP using TMSL as semantic model format, you can convert it to TMDL as follows:

1. Open the PBIP in Power BI Desktop.

2. Ensure the Preview Feature is enabled.

3. Save the project. A prompt appears asking you to upgrade into TMDL.

4. Select Upgrade.

   Important

   Once you upgrade to TMDL, you can't revert back to TMSL. If you think you might want to revert back to TMSL, save a copy of your PBIP files first.

   

The existing Tabular Model Scripting Language (TMSL) file (model.bim) is replaced with a \definition folder containing the TMDL representation of the semantic model.

If you select to Keep current format, Desktop won't prompt again to upgrade.

Make external changes to TMDL files

For a better experience reading and editing your TMDL files, install the TMDL - Visual Studio Marketplace Microsoft VS Code extension.

Open the PBIP folder using VS Code and navigate to semantic model definition folder.

Power BI Desktop isn't aware of changes to project files made by other tools. Therefore, if you make any changes to open files outside of Power BI Desktop, you need to restart for those changes to be shown in Power BI Desktop.

Please refer here for supported write operations outside of Power BI Desktop.

TMDL Errors

If any invalid edits are made to the TMDL files, Power BI Desktop throws an error on open, with the location of the error:

Fabric Git Integration with TMDL

During the Public Preview, Fabric Git Integration will still export the semantic model using TMSL by default. However, if the semantic model is imported into Fabric using Fabric Git Integration with TMDL format, then Fabric Git Integration will use TMDL format to export the semantic model definition to Git if there are any semantic model changes in the service.

Important

If you import your semantic model using any other import method, such as Power BI Desktop Publish, Fabric Git Integration will switch back to the default TMSL format.

Related content

• Power BI Desktop project report folder
• Power BI Desktop projects
• Tabular Model Scripting Language (TMSL)