Power BI as Code: The Setup AI Needs for Your Reports

Everything but the data is metadata

A Power BI report has two parts: the data you load, and everything you build on top of it. The second part covers the model’s tables, columns, measures, and relationships, the report’s pages and visuals, and the filters, formatting, security roles, and descriptions attached to them. All of that is metadata, and a text editor can read and change metadata, as long as the report is saved in the right format.

A .pbix keeps the metadata in a binary format that only Power BI Desktop can open. Save the same report as a Power BI project and Desktop writes it to disk as a folder of text files instead. You can read those files, and when something changes, a diff shows exactly which lines moved. A script can apply one change to every visual on every page, and an AI tool can read and edit the files the same way you do.

Three names come up throughout. PBIP, the Power BI project, is the container: a folder plus a small .pbip file that points into it. PBIR, the enhanced report format, stores the report as JSON, with one file per page and one per visual. TMDL, the Tabular Model Definition Language, stores the semantic model as indented text, with one file per table and one per security role.

When I recorded the video in May 2026, all of this was in preview. At FabCon Europe in Barcelona, at the end of September 2026, Microsoft announced that Power BI projects are generally available and that PBIR is now the default report format for both .pbix and .pbip files. Desktop converts an older report to PBIR the next time you save it, and keeps a backup of the original for 30 days.

The example throughout is a one-page sales report I built for the video. Its model is a small star schema: a Sales table with Date, Customer, and Product dimensions, a User Region table that maps people to regions, two row-level security roles, and a description on every object. The whole project is in the downloads below. Extract the zip before you open anything: opening the .pbip from inside the zip fails with “Required artifact is missing”, because Desktop can’t find the report folder next to it.

The top of the demo report. The Year slicer on the left is the visual this article follows through the files.

2:05Save a report as a project

In the September 2026 release of Desktop, the project settings still sit under File > Options and settings > Options > Preview features, even though Microsoft announced general availability the same month. Check that the first three are on: “Power BI Project (.pbip) save option”, “Store semantic model using TMDL format”, and “Store reports using enhanced metadata format (PBIR)”. If you turn any of them on, restart Desktop.

Preview features in the September 2026 release of Desktop. The fourth setting turns on the external-change reload described under “What you can edit outside Desktop”.

Then open the report and go to File > Save as > Browse this device. Set “Save as type” to “Power BI project files (*.pbip)” and save. Desktop writes four things into the folder you chose.

What Desktop writes when the demo report is saved as a project.

The data isn’t part of the project. Desktop keeps the imported data in .pbi/cache.abf inside the semantic model folder, and the .gitignore it writes excludes that file along with your local settings:

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

Desktop only writes this .gitignore when the folder, or a Git repository above it, doesn’t already have one. Anyone who opens the project without your cache needs to refresh before the visuals show data.

To reopen the project, double-click the .pbip file. Opening definition.pbir in the report folder does the same thing, which helps if the .pbip ever goes missing. File > Save as turns the project back into a .pbix whenever you need one, and Desktop is the only tool that converts in either direction.

Desktop can’t save a project directly to OneDrive or SharePoint, and saving into a locally synced OneDrive folder can cause sync problems that make saves fail. Windows also limits file paths to 260 characters by default, and a project nests several folders deep, so a long root path plus a long table name can break a save. Use a short local path such as C:\PBIP Demo\. Desktop’s built-in version history needs a file saved to OneDrive or SharePoint, so it works only for a .pbix; Easy Version History Comes to Power BI Desktop covers it.

4:11Two folders and a pointer

How the demo project’s files point at each other.

The .pbip file is the project’s entry point, and this is all of it:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/pbip/pbipProperties/1.0.0/schema.json",
  "version": "1.0",
  "artifacts": [
    {
      "report": {
        "path": "PBIP and GitHub Demo.Report"
      }
    }
  ],
  "settings": {
    "enableAutoRecovery": true
  }
}

The line that matters is the path to the report folder. Double-click the file and Desktop opens that report.

Inside the report folder, definition.pbir says which semantic model the report uses:

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

byPath is a relative path: .. goes up one folder, then the path goes down into the semantic model folder. Because the reference is relative, the project keeps working when you move or copy the whole folder. A thin report, one built on a semantic model that’s already published to the service, has byConnection here instead, with a connection string that names the workspace and the model. In the video I guessed this would be a URL. It’s a connection string, and with it Desktop opens the report without opening the model for editing.

Each folder also has a .platform file. It holds the item’s display name in the service, "displayName": "PBIP and GitHub Demo", and an ID that Fabric’s Git integration uses. Select the project name in Desktop’s title bar and a flyout shows where both folders are and lets you change the display names.

StaticResources holds the report’s theme and images. The demo’s base theme, Fluent2-CY26SU04.json, is under SharedResources/BaseThemes, and the logo is under RegisteredResources. Each one has an entry in definition/report.json, which is also where report-level filters live. A file in RegisteredResources can be replaced with a new version under the same name, which is how one change to a custom theme or logo can roll out to many reports.

5:37Follow one slicer through the files

The report folder holds everything you see on the canvas. The quickest way to learn its layout is to take one visual and find every file that describes it. Here that’s the Year slicer, and its trail crosses into the semantic model before it ends.

The five files that define the Year slicer and what it filters.

Page order

definition/pages/pages.json lists the pages and says which one opens first. From here on, the excerpts leave out each file’s $schema line.

{
  "pageOrder": [
    "d3583278a4fc59eaa0d6"
  ],
  "activePageName": "d3583278a4fc59eaa0d6"
}

Dragging a page tab in Desktop reorders this list, and editing the list reorders the tabs. activePageName is the page that was open when you last saved, and it’s the page people land on when they open the report in the service.

The page

Every page gets a folder named with a 20-character ID. In it, page.json holds the page’s display name and size:

{
  "name": "d3583278a4fc59eaa0d6",
  "displayName": "Page 1",
  "displayOption": "FitToPage",
  "height": 720,
  "width": 1280
}

Page-level filters would go in this file too. This page doesn’t have any.

The visual

Each visual on the page has its own folder under visuals/, again named with an ID, holding a visual.json. The Year slicer’s file is 149 lines. This excerpt keeps the parts that define it, with the nesting compacted to fit:

{
  "name": "43811631260ee3580e9a",
  "position": {
    "x": 34.481632653061226,
    "y": 222.51836734693876,
    "z": 9000,
    "height": 61.648979591836735,
    "width": 229.87755102040816,
    "tabOrder": 9000
  },
  "visual": {
    "visualType": "slicer",
    "query": {
      "queryState": {
        "Values": {
          "projections": [
            {
              "field": {
                "Column": {
                  "Expression": { "SourceRef": { "Entity": "Date" } },
                  "Property": "Year"
                }
              },
              "queryRef": "Date.Year",
              "nativeQueryRef": "Year",
              "active": true
            }
          ]
        }
      }
    },
    "objects": {
      "items": [
        {
          "properties": {
            "textSize": { "expr": { "Literal": { "Value": "10D" } } },
            "padding": { "expr": { "Literal": { "Value": "0D" } } }
          }
        }
      ]
    },
    "visualContainerObjects": {
      "stylePreset": [
        { "properties": { "name": { "expr": { "Literal": { "Value": "'Tile'" } } } } }
      ]
    }
  }
}

position is the slicer’s box on the canvas, in pixels from the top-left corner of the page, with z for stacking order and tabOrder for keyboard navigation. visualType says it’s a slicer. The query has one projection, the field it shows: the column Year on the table Date, which the file also writes as "queryRef": "Date.Year". Under objects, the items use 10-point text with no padding, and stylePreset gives the slicer its tile layout. Change a setting in the Format pane and it shows up as a property in this file.

Find a visual by name

With 20-character IDs, browsing for a visual is hopeless. This one page has 19 visual folders. Desktop can tell you the ID instead. Go to File > Options and settings > Report settings > Report objects and turn on “Copy object names when right clicking on report objects”. You only need to do that once. Then right-click any visual on the canvas, choose Copy object name, and paste the ID into the search box in File Explorer or VS Code. It works for pages, bookmarks, and filters too.

What these files can reveal

PBIR saves some data values along with the metadata. A filter on a visual stores the values it filters on, and the same goes for slicer selections, custom column widths in a matrix, and formatting applied to one specific series. The demo’s Year slicer has no selection saved, so its file only names the column. Two of its KPI cards, Sales LY and Sales YoY%, each have a visual-level filter on Year, and their files hold the year in plain text as "Value": "2025L". On a real report, a filter on a customer’s name puts that name in the project, and in every repository the project is pushed to. Check before you share one.

I don’t expect you to read report JSON for fun. I find the semantic model the more interesting folder, and it’s where the slicer’s trail goes next.

11:13Read the model in TMDL

The slicer’s field, Date.Year, is defined in the semantic model folder, in definition/tables/Date.tmdl. Here is the start of that file, without the table’s description:

table Date
	lineageTag: b02a60a3-a1a2-599d-8fa0-50b1b4c3a35f
	dataCategory: Time

	measure 'Max Year' = MAX('Date'[Year])
		formatString: 0
		lineageTag: ca894948-852b-4100-a5b1-810b623e0c12

	/// Calendar year as a 4-digit integer.
	column Year
		dataType: int64
		formatString: 0
		lineageTag: 12ac3e17-614f-55a3-87c2-1f1828c8c893
		summarizeBy: none
		sourceColumn: Year

		annotation SummarizationSetBy = Automatic

table Date declares the table, and everything indented under it belongs to it. dataCategory: Time is what marking the table as a date table writes. The Max Year measure’s DAX starts right after its equals sign. The Year column carries the properties you set in Desktop: its data type, a format string, no default summarization, and sourceColumn, the Power Query column it’s loaded from. The lineageTag lines are IDs that Desktop assigns to keep track of each object, and you don’t need to touch them.

Picking a year filters the sales numbers because of three lines in relationships.tmdl:

relationship 797c5f8b-0c04-5c82-8c4b-2ad8828299b6
	fromColumn: Sales.'Sale Date'
	toColumn: Date.Date

The relationship runs from the Sale Date column on Sales to the Date column on Date. The file lists the model’s other two relationships the same way, Sales to Customer and Sales to Product. Settings left at their defaults, such as the single filter direction, aren’t written at all, so three lines describe an ordinary one-to-many relationship.

Security roles are text too, so a reviewer can read a change to one line by line, like any other edit. roles/East Region.tmdl is a static role:

role 'East Region'
	modelPermission: read

	tablePermission Customer = 'Customer'[Region] = "East"

The filter is ordinary DAX on the Customer table, and the relationship to Sales carries it to every sale. roles/Regional Manager.tmdl is the dynamic version. It keeps the customers in whatever regions the User Region table maps to the signed-in user’s email:

role 'Regional Manager'
	modelPermission: read

	tablePermission Customer =
			'Customer'[Region] IN
			    CALCULATETABLE (
			        VALUES ( 'User Region'[Region] ),
			        'User Region'[User Email] = USERPRINCIPALNAME ()
			    )

A few rules make any TMDL file readable:

• Indentation is structure. Desktop indents with tabs, and an object has at most three levels: the declaration, its properties, and a multi-line expression under a property. Wrong indentation is a parsing error.
• A name that contains a space, a dot, an equals sign, a colon, or a single quote goes in single quotes, as in 'Sale Date' and 'User Region'.
• model.tmdl lists ref table and ref role lines. They fix the order of the tables and roles, so the order doesn’t change between saves and show up as a difference.
• Measure, role, and partition expressions are plain DAX and M, starting after the equals sign. If a model has DAX user-defined functions, they go in functions.tmdl.

Each table’s partition holds its Power Query code, and when I built the demo, every partition read its CSV file from an absolute path on my machine. The video didn’t mention it, but anyone else who opened that project would have hit a refresh error on every table. The downloadable project fixes that with a parameter, declared in expressions.tmdl:

/// Folder that holds the five CSV files. Change it with Transform data > Edit parameters, then refresh.
expression DataFolder = "C:\PBIP Demo\data\" meta [IsParameterQuery=true, Type="Text", IsParameterQueryRequired=true]

Each partition now builds its path from the parameter. This is the first step of the Customer table’s query:

Source = Csv.Document(File.Contents(DataFolder & "customer.csv"),[Delimiter=",", Columns=3, Encoding=65001, QuoteStyle=QuoteStyle.Csv]),

Before you share a project, search the semantic model folder for File.Contents. Every hard-coded file path turns up in one pass.

15:42Descriptions are part of the model

In TMDL, lines that start with /// directly above an object are that object’s description. In the video I called them comments, which is what they look like. Each one is the Description property you can type into the Properties pane in Desktop, and Desktop shows it as a tooltip in the Data pane and the model view. Here’s the Customer ID column from tables/Customer.tmdl:

	/// Surrogate key. Hidden because consumers should filter by Customer Name or Region, not by the internal ID.
	column 'Customer ID'
		dataType: int64
		isHidden
		isKey

The Customer table’s description in the Properties pane is the /// text above table Customer in Customer.tmdl.

The rules come from Microsoft’s TMDL reference:

• The /// lines go immediately above the object they describe. Nothing can sit between the last /// line and the object, not even a blank line.
• They use the same indentation as the object’s own line.
• A description can span several /// lines.

A blank line between the description and the column breaks the first rule:

	/// Surrogate key. Hidden because consumers should filter by Customer Name or Region, not by the internal ID.

	column 'Customer ID'

Indenting the description a level deeper than the column breaks the second:

		/// Surrogate key. Hidden because consumers should filter by Customer Name or Region, not by the internal ID.
	column 'Customer ID'

In both cases the text doesn’t become the column’s description.

Check for both when a chat model writes descriptions for you. I’ve pasted a table’s TMDL into ChatGPT or Claude and asked for descriptions on every column. Sometimes it does a good job and sometimes it doesn’t. TMDL is new enough that models haven’t seen much of it, so tell it the /// syntax up front, and it can usually write the descriptions correctly.

In TMDL view, right-click a table in the Data pane and choose Script TMDL to > Script tab. Desktop opens the table’s full definition, wrapped in a createOrReplace command. Edit a description, or paste in the version your chat model wrote, and select Apply to write the change to the model. TMDL view also runs in the browser, on a model already published to the service; How to Fix Your Live Power BI Model Straight from the Browser fixes a measure that way without republishing.

The Customer table scripted to a tab in TMDL view. Apply runs the script against the open model.

Descriptions are also the context a person, or an AI tool, reads before changing the model. A column’s name says what it is. A description can say why: the Customer ID description says the column is hidden because people should filter by name or region instead. An AI tool asked to build a visual on this model can’t work that out from the column name, but it can read it in the file. An agent can also write the descriptions for every table, column, and measure and apply them to the model itself; the Power BI Modeling MCP server article walks through it.

What you can edit outside Desktop

Most of the files in a project are documented: the report files have public JSON schemas, and the model files follow Microsoft’s TMDL reference. A few aren’t documented, and Microsoft doesn’t support editing those outside Desktop.

In the report folder:

In Desktop	File	Edit outside Desktop?
Page order, and the page that opens first	definition/pages/pages.json	Yes
A page’s name, size, and filters	definition/pages/<page>/page.json	Yes
A visual’s position, fields, formatting, and filters	definition/pages/<page>/ visuals/<visual>/visual.json	Yes
Bookmarks	definition/bookmarks/	Yes
Report filters, and the list of themes and images	definition/report.json	Yes
Custom theme and image files	StaticResources/RegisteredResources/	Yes, for files already registered
The semantic model the report uses	definition.pbir	Not while the reload preview is on

In the semantic model folder:

In Desktop	File	Edit outside Desktop?
Tables, columns, measures, hierarchies, and their Power Query	definition/tables/<table>.tmdl	Yes
Relationships	definition/relationships.tmdl	Yes
Security roles	definition/roles/<role>.tmdl	Yes
Parameters and shared queries	definition/expressions.tmdl	Yes
Descriptions	/// lines in the TMDL files	Yes
Model diagram layout	diagramLayout.json	No
Imported data	.pbi/cache.abf	No

A report that hasn’t been converted to PBIR yet keeps its whole definition in a single report.json at the top of the report folder. That file isn’t documented either, and neither are mobileState.json and semanticModelDiagramLayout.json, which some report folders contain.

Desktop’s August 2026 release added a preview that picks up edits made in other tools while the project is open. Turn on “Detect and reload external PBIP changes” in Preview features, the fourth box in the screenshot above, and restart Desktop. Then:

1. Save in Desktop. Desktop doesn’t write its latest changes to the files until you do.
2. Select the project name in Desktop’s title bar and choose Visual Studio Code. VS Code opens the project folder.
3. Edit a file and save it.
4. Back in Desktop, select Apply external changes in the banner that appears.

If Desktop has unsaved changes when you apply, it warns you that they’ll be overwritten. Apply discards them, and Cancel keeps them while your edits wait on disk. A reload also resets filters and some parts of the interface, and it doesn’t reload the data in cache.abf. If the project has a .pbi/unappliedChanges.json, meaning Power Query edits you haven’t applied yet, apply them in Desktop before you edit queries elsewhere, or Desktop discards your outside edits when it applies its own. Without the preview, close the project and reopen it to pick up outside edits.

Two formatting rules apply to any file you edit. Save it as UTF-8 without a byte-order mark, and keep the Windows line endings (CRLF) that Desktop writes. If the project is in Git, set up line-ending handling (autocrlf) so a diff doesn’t show every line as changed.

Why this is the setup AI needs

Suppose you want to rename the Year column on the Date table. In a .pbix, finding everything that uses it means clicking through every visual and every measure. In a project, it takes two searches.

Search the report folder for "queryRef": "Date.Year" and two files come back: the Year slicer and the combo chart of sales and margin by year and quarter. That search misses two visuals. The Sales LY and Sales YoY% cards filter on Year, and a filter names its column as "Property": "Year" with no queryRef. Search for "Property": "Year" and all four files turn up. Only the Date table has a Year column in this model, so every match is the column you’re renaming.

Then search the semantic model folder for 'Date'[Year]. Three measures use the column: Max Year, plus Sales YTD and Sales LY, which both check HASONEVALUE ( 'Date'[Year] ) before they return a value. The Calendar hierarchy’s Year level also points at it, as column: Year in Date.tmdl. That’s eight references in six files, besides the column’s own definition.

An AI tool works the same way. It searches the files, reads what it finds, and reads the descriptions to understand why each object exists. Then it can make the change in every file and show you the result as a diff.

After any edit, whether you made it in Desktop, ran a script, or let an AI tool do it, the changed files show exactly what moved. Putting the project under version control is the next step, and the subject of Get Your Power BI Reports AI-Ready with GitHub. Handing the edits themselves to an agent is covered in How To Use Claude Code for Power BI Development. The Tabular Editor CLI article has an agent change the model’s TMDL files with command-line tools.

Save your next report as a project, even if you never plan to use Git. You still open it in Desktop with a double-click, and the next article starts from that folder.