What is a PBIP project, and what is TMDL?

What a PBIP is

When you save your work as a Power BI project, Power BI Desktop writes the report and the semantic model as separate plain text files in a folder. Microsoft documents the files, and you can read them, so you can review changes and keep them in Git.

You convert in Power BI Desktop with File > Save as, in either direction: a .pbix to a PBIP, or a PBIP back to a .pbix.

Source: Power BI Desktop projects (PBIP).

What is in the folder

{
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../SM_SalesSense.SemanticModel"
    }
  }
}

Source: Power BI Desktop projects (PBIP), Power BI Desktop project report folder, Power BI Desktop project semantic model folder.

What TMDL is

TMDL (Tabular Model Definition Language) is a text format for tabular models. It reads a little like YAML: each object is declared on its own line, and indentation shows what belongs to what.

A PBIP saved in TMDL keeps the model in the definition folder of the semantic model, with a separate file for each table, role, culture and perspective. The other format, TMSL, keeps the whole model in one JSON file, model.bim.

A definition.pbism at version 4.0 or above allows either format. Version 1.0 requires model.bim.

	column Manufacturer
		dataType: string
		lineageTag: 59e45f50-f68d-44c3-becd-70ccd5a7eb7d
		summarizeBy: none
		sourceColumn: Manufacturer

		annotation SummarizationSetBy = Automatic

Source: Tabular Model Definition Language (TMDL), Power BI Desktop project semantic model folder.

The TMDL rules that trip people up

• Indentation is one tab per level. An object declaration is level 1, its properties level 2, and a multi-line expression level 3. Breaking the rule is a parsing error.
• A name with a dot, an equals sign, a colon, a single quote or a space goes in single quotes, and a single quote inside the name is written twice.
• A property value stays on the same line as its colon.
• A line that starts with /// above an object is its description.

When a file breaks these rules, Power BI Desktop shows one of these:

• TMDL Format ErrorPower BI Desktop read a .tmdl file in the project and found something it does not accept.
• TMDL Format Error: Invalid indentation was detected!TMDL reads the lines under an object declaration as that object's properties.

Source: Tabular Model Definition Language (TMDL).

Editing the files outside Power BI Desktop

You can edit TMDL files in VS Code while the project is open. Save your work in Power BI Desktop first. It then offers to apply the external changes, and warns you if that would overwrite unsaved work.

Some files do not support editing outside Power BI Desktop: the legacy report.json at the root of the report folder, mobileState.json and semanticModelDiagramLayout.json in the report, and diagramLayout.json in the model.

TMDL view, the TMDL editor inside Power BI Desktop, is generally available. On the web it is in preview.

Source: Power BI Desktop project semantic model folder, Power BI Desktop projects (PBIP), Work with TMDL view in Power BI Desktop.

Check a project in your browser

Other guides

• Power BI Desktop can't open a PBIPWhen Power BI Desktop refuses a project, the message usually names a file.
• PBIR vs PBIR-LegacyPBIR saves a report as a folder with a file for each page, visual and bookmark.
• PBIP and Git: what to commit and what to ignoreA PBIP project is plain text, so Git can track it.

Sources

• Microsoft Learn: Power BI Desktop projects (PBIP). "Save as a project", "Changes outside Power BI Desktop", "Considerations and limitations" and the FAQ. Page dated 2026-09-23. Read 2026-10-04.
• Microsoft Learn: Power BI Desktop project report folder. The file list, "PBIR format", "External changes to PBIR files", "Convert existing report to PBIR" and "PBIR considerations and limitations". Page dated 2026-09-29. Read 2026-10-04.
• Microsoft Learn: Power BI Desktop project semantic model folder. The file list, "TMDL format" and "TMDL errors". Page dated 2026-09-29. Read 2026-10-04.
• Microsoft Learn: Tabular Model Definition Language (TMDL). The introduction, "TMDL folder structure", "Object declaration", "Object Properties", "Descriptions" and "Indentation". Read 2026-10-04.
• Microsoft Learn: Work with TMDL view in Power BI Desktop. The note at the top of the page. Page dated 2026-07-09. Read 2026-10-04.